Metadata-Version: 2.2
Name: okiff-sdk
Version: 1.2.0
Summary: Okiff SDK
License: Proprietary
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# okiff-sdk

Python SDK for connecting to and communicating with MQTT brokers.
Built as a compiled native extension for high performance and ease of deployment.

---

## Requirements

- Python 3.9 or later
- Linux x86-64 (additional platforms coming soon)

---

## Installation

```bash
pip install okiff-sdk
```

No compilation is required. The package is distributed as a pre-built binary wheel.

---

## Quick Start

```python
"""
Example:
    Connect to an MQTT broker, subscribe to a topic,
    publish a message, and receive messages using callbacks.
"""

import time
from okiff_sdk import SDK


# Create SDK instance
sdk = SDK()


# Connection callback
def on_connection(connected: bool, rc: int) -> None:
    """
    Called whenever the connection state changes.

    Args:
        connected: True if connected, False otherwise.
        rc: MQTT return code (0 = success, -1 = unexpected disconnect).
    """
    print(f"[on_connection] connected={connected}, rc={rc}")


# Message callback
def on_message(topic: str, payload: str) -> None:
    """
    Called when a message is received.

    Args:
        topic: MQTT topic.
        payload: UTF-8 message payload.
    """
    print(f"[on_message] topic={topic}, payload={payload}")


# Register callbacks
sdk.on_connection(on_connection)
sdk.on_message(on_message)


# Initialize SDK
sdk.init(
    clientId="clientId",
    brokerHost="ip:port",
    protocol="tcp",
    username="username",
    password="YOUR_JWT_TOKEN",
    cleanSession=True,
    resumeSubs=True,
    connectRetry=True,
    autoReconnect=True,
    connectRetryInterval=5,
    maxReconnectInterval=30,
    keepAlive=30,
    pingTimeout=20,
    writeTimeout=20,
    orderMatters=False,
    connectTimeout=5,
    edition="Enterprise",
)


# Connect
if sdk.connect():
    sdk.subscribe("okiff/sdk/test")
    sdk.publish("okiff/sdk/test", "hello from okiff-sdk")

    # Wait to receive messages
    time.sleep(5)


# Disconnect
sdk.disconnect()
print("Disconnected")
```

---

# API Reference

## `SDK()`

Creates a new SDK instance.

---

## `init(...)`

Initializes the MQTT client. L'option edition Enterprise permet à connecter l'IoT Thing to the Cloud Core. For Testing you can use edition Community and connect to Edge/Onpremise Broker core.

This method **must** be called before `connect()`.

| Parameter | Type | Description |
|------------|------|-------------|
| `clientId` | `str` | Unique MQTT client identifier |
| `brokerHost` | `str` | Broker address with port (`host:port`) |
| `protocol` | `str` | Connection protocol (`"tcp"` or `"ssl"`) |
| `username` | `str` | MQTT username |
| `password` | `str` | MQTT password or JWT token |
| `cleanSession` | `bool` | Start a clean MQTT session |
| `resumeSubs` | `bool` | Restore subscriptions after reconnect |
| `connectRetry` | `bool` | Retry the initial connection if it fails |
| `autoReconnect` | `bool` | Automatically reconnect after disconnect |
| `connectRetryInterval` | `int` | Initial retry interval (seconds) |
| `maxReconnectInterval` | `int` | Maximum reconnect interval (seconds) |
| `keepAlive` | `int` | MQTT keep-alive interval (seconds) |
| `pingTimeout` | `int` | Ping response timeout (seconds) |
| `writeTimeout` | `int` | Socket write timeout (seconds) |
| `orderMatters` | `bool` | Preserve message ordering |
| `connectTimeout` | `int` | Connection timeout (seconds) |
| `edition` | `str` | SDK edition (for example `"Community"` or `"Enterprise"`) |

---

## `connect() -> bool`

Connects to the configured MQTT broker.

Returns `True` if the connection succeeds.

---

## `disconnect()`

Gracefully disconnects from the MQTT broker.

---

## `publish(topic, payload, qos=0, retained=False)`

Publishes a message to the specified topic.

| Parameter | Type | Description |
|------------|------|-------------|
| `topic` | `str` | MQTT topic |
| `payload` | `str` | Message payload |
| `qos` | `int` | MQTT Quality of Service (0, 1 or 2) |
| `retained` | `bool` | Publish as a retained message |

---

## `subscribe(topic, qos=0) -> bool`

Subscribes to an MQTT topic.

Returns `True` if the subscription succeeds.

---

## `unsubscribe(topic)`

Removes an existing topic subscription.

---

## `on_message(callback)`

Registers a callback invoked whenever a message is received.

Callback signature:

```python
callback(topic: str, payload: str) -> None
```

---

## `on_connection(callback)`

Registers a callback invoked whenever the connection state changes.

Callback signature:

```python
callback(connected: bool, rc: int) -> None
```

Where:

- `connected=True` indicates the client is connected.
- `connected=False` indicates the client has disconnected.
- `rc` is the MQTT/Paho return code.

---

## `is_connected() -> bool`

Returns the current connection status.

---

## License

**Proprietary** — All rights reserved.