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

# okiff-sdk

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

---

## Requirements

- Python 3.9 or later
- Linux x86-64 (glibc ≥ 2.39), with additional platforms coming

---

## Installation

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

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

---

## Quick Start

```python
"""
Example:
    Basic publish/subscribe usage of the okiff-sdk.
"""


# Imports
import time
from okiff_sdk import SDK


# Client setup
sdk = SDK()


# Callbacks
def on_connection(connected: bool, rc: int) -> None:
    """
    Handle connection state changes.

    Args:
        connected: True if connected, False if disconnected.
        rc: Paho return code. 0 = clean, -1 = unexpected loss.
    """

    print(f"[on_connection] connected={connected}, rc={rc}")


def on_message(topic: str, payload: str) -> None:
    """
    Handle incoming messages.

    Args:
        topic: Topic on which the message was received.
        payload: Message body as a UTF-8 string.
    """

    print(f"[on_message] topic={topic}, payload={payload}")


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


# Initialize and connect
sdk.init(
    client_id   = "my_client",
    broker_host = "broker.example.com:1883",
    protocol    = "tcp",
    username    = "user",
    password    = "password",
)


# Connect
ok = sdk.connect()


# Publish and subscribe
if ok:
    sdk.subscribe("my/topic")
    sdk.publish("my/topic", "hello")
    time.sleep(2)


# Cleanup
sdk.disconnect()
sdk.stop()
```

---

## API Reference

### `SDK()`
Creates a new SDK instance.

### `init(client_id, broker_host, protocol, username, password)`
Initializes the client. Must be called before `connect()`.

| Parameter | Type | Description |
|---|---|---|
| `client_id` | `str` | Unique identifier for this client |
| `broker_host` | `str` | Broker address including port, e.g. `broker.example.com:1883` |
| `protocol` | `str` | Transport protocol: `"tcp"` or `"ssl"` |
| `username` | `str` | Authentication username |
| `password` | `str` | Authentication password |

### `connect() -> bool`
Connects to the broker. Returns `True` on success.

### `disconnect()`
Gracefully disconnects from the broker.

### `publish(topic, payload, qos=0, retained=False)`
Publishes a message to the given topic.

### `subscribe(topic, qos=0) -> bool`
Subscribes to a topic. Returns `True` on success.

### `unsubscribe(topic)`
Unsubscribes from a topic.

### `on_message(callback)`
Registers a callback invoked when a message arrives.
Signature: `callback(topic: str, payload: str) -> None`

### `on_connection(callback)`
Registers a callback invoked on connection state changes.
Signature: `callback(connected: bool, rc: int) -> None`

### `is_connected() -> bool`
Returns the current connection state.

### `stop()`
Stops all activity and releases resources. Call after `disconnect()`.

---

## License

Proprietary — all rights reserved.