Python SDK

The Iottly Python SDK runs on the device alongside your application code. It communicates with the local Iottly Agent over a Unix socket, so it never opens a direct network connection.

Installation

pip install iottly-sdk

Requires Python ≥ 3.8. The SDK has no external dependencies beyond the standard library.

Initialisation

from iottly import IottlySDK

sdk = IottlySDK(
    socket_path='/var/run/iottly/agent.sock',  # default path
    reconnect=True,                            # auto-reconnect if agent restarts
)
sdk.start()

Always call sdk.start() before using any other method. It establishes the local connection to the agent.

Publishing telemetry

import time

while True:
    cpu_temp = read_cpu_temperature()  # your own function

    sdk.send({
        'stream': 'temperature',
        'value': cpu_temp,
    })

    time.sleep(1)

Batch publishing

sdk.send_batch([
    {'stream': 'cpu',         'value': 18.4},
    {'stream': 'memory',      'value': 312},
    {'stream': 'temperature', 'value': 47.2},
])

All frames in a batch share the same server-side timestamp.

Receiving commands

Register a handler for commands your application wants to respond to:

@sdk.on_command('restart_worker')
def handle_restart(params, reply):
    # params: dict parsed from the command payload
    stop_worker()
    start_worker()
    reply(ok=True, message='Worker restarted')

The reply callback sends a structured response back to the operator who issued the command.

Wildcard handler

If you want to handle all commands:

@sdk.on_command('*')
def handle_any(command_name, params, reply):
    print(f'Received command: {command_name}', params)
    reply(ok=False, message=f'Unknown command: {command_name}')

Logging integration

The SDK ships with a standard logging handler that forwards Python log records as telemetry frames:

import logging
from iottly.logging import IottlyHandler

logger = logging.getLogger('myapp')
logger.addHandler(IottlyHandler(sdk))
logger.setLevel(logging.INFO)

logger.info('Application started')
# → published as { stream: '__logs__', level: 'info', message: 'Application started' }

These frames are automatically displayed in the Logs tab of the Iottly dashboard.

Graceful shutdown

import signal

def on_sigterm(signum, frame):
    sdk.stop()
    raise SystemExit(0)

signal.signal(signal.SIGTERM, on_sigterm)

Full example

import time
import signal
from iottly import IottlySDK
import logging
from iottly.logging import IottlyHandler

sdk = IottlySDK()
sdk.start()

log = logging.getLogger('demo')
log.addHandler(IottlyHandler(sdk))
log.setLevel(logging.INFO)

@sdk.on_command('ping')
def pong(params, reply):
    reply(ok=True, message='pong')

def on_sigterm(signum, frame):
    sdk.stop()
    raise SystemExit(0)

signal.signal(signal.SIGTERM, on_sigterm)
log.info('Demo started')

while True:
    sdk.send({'stream': 'heartbeat', 'value': 1})
    time.sleep(10)