SDK Python

L’SDK Python di Iottly gira sul device accanto al codice della tua applicazione. Comunica con l’Iottly Agent locale tramite un socket Unix, quindi non apre mai una connessione di rete diretta.

Installazione

pip install iottly-sdk

Richiede Python ≥ 3.8. L’SDK non ha dipendenze esterne oltre alla libreria standard.

Inizializzazione

from iottly import IottlySDK

sdk = IottlySDK(
    socket_path='/var/run/iottly/agent.sock',  # percorso default
    reconnect=True,                            # riconnetti automaticamente se l'agent si riavvia
)
sdk.start()

Chiama sempre sdk.start() prima di usare qualsiasi altro metodo. Stabilisce la connessione locale con l’agent.

Pubblicare telemetria

import time

while True:
    temp_cpu = leggi_temperatura_cpu()  # la tua funzione

    sdk.send({
        'stream': 'temperatura',
        'value': temp_cpu,
    })

    time.sleep(1)

Pubblicazione a batch

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

Tutti i frame di un batch condividono lo stesso timestamp lato server.

Ricevere comandi

Registra un handler per i comandi a cui la tua applicazione vuole rispondere:

@sdk.on_command('riavvia_worker')
def gestisci_riavvio(params, reply):
    # params: dict ricavato dal payload del comando
    ferma_worker()
    avvia_worker()
    reply(ok=True, message='Worker riavviato')

Il callback reply invia una risposta strutturata all’operatore che ha emesso il comando.

Handler wildcard

Se vuoi gestire tutti i comandi:

@sdk.on_command('*')
def gestisci_tutti(nome_comando, params, reply):
    print(f'Comando ricevuto: {nome_comando}', params)
    reply(ok=False, message=f'Comando sconosciuto: {nome_comando}')

Integrazione logging

L’SDK include un handler logging standard che inoltra i record di log Python come frame di telemetria:

import logging
from iottly.logging import IottlyHandler

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

logger.info('Applicazione avviata')
# → pubblicato come { stream: '__logs__', level: 'info', message: 'Applicazione avviata' }

Questi frame vengono visualizzati automaticamente nel tab Log della dashboard Iottly.

Shutdown graceful

import signal

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

signal.signal(signal.SIGTERM, su_sigterm)

Esempio completo

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 su_sigterm(signum, frame):
    sdk.stop()
    raise SystemExit(0)

signal.signal(signal.SIGTERM, su_sigterm)
log.info('Demo avviata')

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