SDK Python – Iottly Docs
🇬🇧 Read in English

SDK Python iottly

Modulo Python che gestisce l’interazione con l’agent iottly da applicazioni di terze parti installate localmente sul device.

Ad esempio l’applicazione custom si occupa delle interazioni con l’hardware e i bus di basso livello, delegando all’Agent iottly la comunicazione sicura su MQTT.

Inoltre l’applicazione custom può invocare script Python registrati nell’Agent per eseguire operazioni come il rilevamento e la correlazione di eventi complessi. È come avere “functions as a service su device embedded”, e risulta particolarmente utile quando le regole devono essere aggiornate frequentemente, o quando è necessario mantenere versioni diverse delle regole per device in installazioni differenti.

In breve, l’app registrata può:

  • Inviare messaggi a iottly
  • Sottoscrivere specifici comandi ricevuti dall’iottly-agent
  • Chiamare uno snippet Python negli script definiti dall’utente dell’Agent collegato
  • Registrare callback su specifiche notifiche dell’iottly-agent

Schema di un'applicazione custom che comunica con iottly tramite l'SDK e l'Agent iottly

Installazione

Installa usando pip (consigliato):

sudo pip3 install https://github.com/tomorrowdata/iottly-sdk-python/archive/1.3.0.tar.gz

La classe IottlySDK

Crea un’istanza di IottlySDK, assegnando alla tua applicazione un name che la identifica nel tuo progetto iottly (compare nei log della dashboard).

from iottly_sdk import IottlySDK

iottlysdk = IottlySDK(
    name='myfirstiottlyapp',
    max_buffered_msgs=100,
    on_agent_status_changed=on_agent_status_changed,
    on_connection_status_changed=on_connection_status_changed)

Parametri e argomenti keyword:

  • name (str) — un identificatore per l’applicazione collegata.
  • socket_path (str) — percorso dell’unix-socket esposto dall’agent iottly. Default /var/run/iottly.com-agent/sdk/iottly_sdk_socket.
  • max_buffered_msgs (int) — numero massimo di messaggi bufferizzati internamente. Default 10.
  • on_agent_status_changed (func, opzionale) — callback per le notifiche di stato dell’agent iottly.
  • on_connection_status_changed (func, opzionale) — callback per lo stato della connessione dell’agent.

Callback di stato dell’agent

on_agent_status_changed viene chiamata quando l’SDK si connette e si disconnette dall’agent iottly. Riceve uno tra:

  • started — l’SDK è collegato correttamente con l’agent iottly
  • stopping — l’agent iottly sta effettuando un riavvio programmato
  • stopped — l’SDK è disconnesso dall’agent iottly

on_connection_status_changed viene chiamata quando l’agent notifica un cambiamento nella connettività MQTT del device. Riceve uno tra:

  • connected — MQTT è attivo nell’agent iottly collegato
  • disconnected — MQTT è inattivo (i messaggi inviati mentre si è disconnessi vengono bufferizzati internamente)
def on_agent_status_changed(status):
    print('on_agent_status_changed: {}'.format(status))

def on_connection_status_changed(status):
    print('on_connection_status_changed: {}'.format(status))

Sottoscrivere i comandi

Usa subscribe(cmd_type, callback) per reagire a uno specifico comando ricevuto dall’iottly-agent. Dopo la sottoscrizione, l’SDK invoca la tua callback—con un dict di parametri del comando—ogni volta che l’agent riceve un messaggio di quel tipo. I comandi sono definiti nel pannello dashboard iottly / management commands.

def on_echo_received(cmdpars):
    print('on_echo_received: {}'.format(cmdpars))

iottlysdk.subscribe(
    cmd_type='echo',
    callback=on_echo_received)

Se chiami subscribe con un cmd_type già registrato, la callback viene sovrascritta.

Inviare messaggi

Dopo aver chiamato start(), usa send(msg, channel=None) per recapitare un messaggio a iottly tramite l’agent locale. Se l’agent non è disponibile il messaggio viene bufferizzato internamente—ne vengono conservati al massimo max_buffered_msgs, dopodiché i più vecchi vengono scartati. L’argomento opzionale channel instrada il messaggio, ad esempio verso uno specifico webhook.

# avvia i loop dell'sdk
iottlysdk.start()

# invia un messaggio a iottly
iottlysdk.send({'temperature': 22})

Il messaggio deve essere un dict serializzabile in JSON; altrimenti send solleva TypeError o ValueError.

Chiamare gli snippet dell’agent

Usa call_agent(cmd, args) per invocare uno snippet Python dagli script definiti dall’utente dell’agent iottly collegato. Le chiamate sono sincrone: se l’agent non è disponibile la chiamata viene scartata con un errore DisconnectedSDK, che dovresti intercettare e ritentare più tardi una volta ristabilita la connessione. Il dict args deve essere serializzabile in JSON.

Attenzione: richiede l’agent iottly versione ≥ 1.8.0. Chiamarla verso un agent più vecchio solleva InvalidAgentVersion.

Esempio

import time

from iottly_sdk import IottlySDK

# Definisci una callback per ricevere notifiche
# sullo stato dell'agent iottly:
# -  started
# -  stopping
# -  stopped
def on_agent_status_changed(status):
    print('on_agent_status_changed: {}'.format(status))

# Definisci una callback per ricevere notifiche
# sullo stato della connessione mqtt dell'agent iottly:
# -  connected
# -  disconnected
def on_connection_status_changed(status):
    print('on_connection_status_changed: {}'.format(status))

# Crea un'istanza di IottlySDK
iottlysdk = IottlySDK(
    name='myfirstiottlyapp',
    max_buffered_msgs=100,
    on_agent_status_changed=on_agent_status_changed,
    on_connection_status_changed=on_connection_status_changed)

# Definisci una callback per ogni comando in arrivo che
# vuoi sottoscrivere. I comandi sono definiti nel pannello
# dashboard iottly / management commands.
def on_echo_received(cmdpars):
    print('on_echo_received: {}'.format(cmdpars))

def on_examplecommand_received(cmdpars):
    print('on_examplecommand_received: {}'.format(cmdpars))

# Sottoscrivi i comandi di interesse e associa una callback
iottlysdk.subscribe(
    cmd_type='echo',
    callback=on_echo_received)
iottlysdk.subscribe(
    cmd_type='examplecommand',
    callback=on_examplecommand_received)

# Avvia i loop dell'sdk
iottlysdk.start()

# Loop bloccante principale della tua applicazione. "Legge una
# temperatura" e la invia a iottly usando 'send'.
while True:
    try:
        s = input(
            '\n^C per uscire, "m" per inviare 1 messaggio, '
            '"l" per inviare 20 messaggi:\n')
        if s == 'm':
            # invia un messaggio a iottly
            iottlysdk.send({'temperature': 22})
        if s == 'l':
            for t in range(10, 30):
                # invia un messaggio a iottly
                iottlysdk.send({'temperature': t})
                time.sleep(1)
    except KeyboardInterrupt:
        break