okiff-sdk 1.2.0

Okiff SDK

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

pip install okiff-sdk

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

---

Quick Start

"""
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:

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

---

on_connection(callback)

Registers a callback invoked whenever the connection state changes.

Callback signature:

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.