`senml` — Sensor Markup Language¶

Questo modulo implementa un piccolo encoder/decoder per il Sensor Markup Language (SenML, RFC 8428). SenML è un tipo di media per le misurazioni dei sensori e i parametri dei dispositivi: ogni «pack» è un elenco di «record», dove ogni record contiene un nome, un’unità, un valore, un timestamp e una somma opzionale.

L’implementazione supporta sia la rappresentazione JSON che quella CBOR e consente di annidare i pack in modo che un singolo pack radice possa descrivere un gateway che fa da front-end a più dispositivi. I payload in ingresso possono attivare callback degli attuatori sui record esistenti.

Esempio di utilizzo:

from senml import SenmlPack, SenmlRecord, SenmlUnits

# A pack collects readings for one device, identified by URN.
pack = SenmlPack("urn:dev:mac:0024befffe804ff1")

# Add a temperature reading in degrees Celsius.
pack.add(SenmlRecord(
    "temperature",
    unit=SenmlUnits.SENML_UNIT_DEGREES_CELSIUS,
    value=23.4,
))

# Add a humidity reading in %RH.
pack.add(SenmlRecord(
    "humidity",
    unit=SenmlUnits.SENML_UNIT_RELATIVE_HUMIDITY,
    value=51.2,
))

# Render the pack as a SenML/JSON document.
print(pack.to_json())

Classi¶

class senml.SenmlPack(name: str, callback=None)¶

Rappresenta un pack SenML, ovvero una raccolta di istanze SenmlRecord ed eventualmente altri oggetti SenmlPack figli. Quando un pack contiene solo record, rappresenta un singolo dispositivo; quando contiene altri pack, funge da gateway.

name è il nome base SenML (bn) usato per ogni record contenuto in questo pack.

callback viene invocata da from_json / from_cbor ogni volta che un record in ingresso nomina un sensore precedentemente sconosciuto; il nuovo SenmlRecord viene passato come primo argomento e (per i pack annidati) il pack del dispositivo di origine viene passato come device=.... Viene tipicamente usata per gestire i comandi degli attuatori.

Le istanze SenmlPack sono iterabili – l’iterazione restituisce ogni record nell’ordine di inserimento – e possono essere usate come context manager in modo che all’uscita il pack si rimuova dal proprio genitore.

name: str¶: Il nome base del pack (bn).

base_value: int | float | None¶: Valore base opzionale (bv) aggiunto al valore numerico di ogni record durante la codifica e sottratto durante la decodifica. L’impostazione di un valore non numerico solleva Exception.

base_time: int | float | None¶: Tempo base opzionale (bt) aggiunto al timestamp di ogni record.

base_sum: int | float | None¶: Somma base opzionale (bs) aggiunta al campo somma di ogni record.

base_unit: str | None¶: Unità base opzionale (bu) – tipicamente un valore di SenmlUnits.

actuate¶: La callback fornita al momento della costruzione. Può essere riassegnata a runtime.

add(item: SenmlRecord | SenmlPack) → None¶: Aggiunge item a questo pack. item deve essere un SenmlRecord o un altro SenmlPack e non deve già appartenere a un genitore diverso; in caso contrario viene sollevata Exception.

remove(item: SenmlRecord | SenmlPack) → None¶: Rimuove item da questo pack. Viene sollevata Exception se item non è un figlio di questo pack.

clear() → None¶: Rimuove ogni record/sub-pack da questo pack e li scollega dal loro riferimento al genitore.

from_json(data: str) → None¶: Analizza un documento SenML/JSON e unisce i record in questo pack. I record che esistono già (corrispondenti per nome) attivano SenmlRecord.do_actuate(); i nuovi record vengono aggiunti e viene invocata la callback a livello di pack.

to_json() → str¶: Esegue il rendering del pack e dei suoi figli in una stringa SenML/JSON.

from_cbor(data: bytes) → None¶: Analizza una stringa di byte SenML/CBOR e unisce i record in questo pack.

to_cbor() → bytes¶: Esegue il rendering del pack e dei suoi figli in una stringa di byte SenML/CBOR.

do_actuate(raw: dict, naming_map: dict, device: SenmlPack | None = None) → None¶: Helper interno invocato durante l’analisi dei dati in ingresso quando nessun record esistente corrisponde a una voce. Aggiunge un nuovo SenmlRecord a device (o a questo pack) e lo inoltra alla callback.

class senml.SenmlRecord(name: str, **kwargs)¶

Rappresenta una singola misurazione all’interno di un SenmlPack.

name è il nome del record SenML (n).

Sono accettati i seguenti argomenti keyword:

value – bool, int, float, str o bytearray. Altri tipi sollevano Exception.
time – timestamp numerico (t).
unit – una stringa di unità, tipicamente un membro di SenmlUnits.
sum – somma integrata numerica (s).
update_time – tempo massimo prima che il sensore fornisca una nuova lettura (ut).
callback – funzione invocata quando un payload in ingresso aggiorna questo record. Riceve il SenmlRecord come unico argomento.

SenmlRecord può essere usato come context manager in modo che all’uscita si rimuova dal pack genitore.

name: str¶: Nome del record (n).

value¶: Il valore corrente. La riassegnazione verifica il tipo; sono accettati solo bool, numeri, str e bytearray. Per controllare la precisione del rendering di un valore float, arrotondalo prima dell’assegnazione, ad esempio record.value = round(x, 2).

unit: str | None¶: Stringa di unità (u).

time: int | float | None¶: Timestamp associato a questa misurazione (t).

update_time: int | float | None¶: Tempo massimo prima che il sensore fornisca una lettura aggiornata (ut).

sum: int | float | None¶: Campo somma integrata (s).

actuate¶: La callback fornita al momento della costruzione. Può essere riassegnata a runtime.

do_actuate(raw: dict, naming_map: dict) → None¶: Aggiorna questo record da un dizionario SenML grezzo in ingresso e, se presente, invoca la callback di attuazione.

class senml.SenmlBase¶: Classe base comune condivisa da SenmlPack e SenmlRecord. Non espone alcuna API pubblica propria; esiste affinché SenmlPack.add() possa verificare che un elemento appartenga alla gerarchia SenML.

class senml.SenmlUnits¶

Classe namespace i cui attributi di classe sono i simboli delle unità SenML definiti da RFC 8428. Ogni attributo si risolve nel codice stringa dell’unità, adatto all’assegnazione a SenmlRecord.unit o SenmlPack.base_unit.

SENML_UNIT_METER: str¶: "m" – metro.

SENML_UNIT_KILOGRAM: str¶: "kg" – chilogrammo.

SENML_UNIT_GRAM: str¶: "g" – grammo.

SENML_UNIT_SECOND: str¶: "s" – secondo.

SENML_UNIT_AMPERE: str¶: "A" – ampere.

SENML_UNIT_KELVIN: str¶: "K" – kelvin.

SENML_UNIT_CANDELA: str¶: "cd" – candela.

SENML_UNIT_MOLE: str¶: "mol" – mole.

SENML_UNIT_HERTZ: str¶: "Hz" – hertz.

SENML_UNIT_RADIAN: str¶: "rad" – radiante.

SENML_UNIT_STERADIAN: str¶: "sr" – steradiante.

SENML_UNIT_NEWTON: str¶: "N" – newton.

SENML_UNIT_PASCAL: str¶: "Pa" – pascal.

SENML_UNIT_JOULE: str¶: "J" – joule.

SENML_UNIT_WATT: str¶: "W" – watt.

SENML_UNIT_COULOMB: str¶: "C" – coulomb.

SENML_UNIT_VOLT: str¶: "V" – volt.

SENML_UNIT_FARAD: str¶: "F" – farad.

SENML_UNIT_OHM: str¶: "Ohm" – ohm.

SENML_UNIT_SIEMENS: str¶: "S" – siemens.

SENML_UNIT_WEBER: str¶: "Wb" – weber.

SENML_UNIT_TESLA: str¶: "T" – tesla.

SENML_UNIT_HENRY: str¶: "H" – henry.

SENML_UNIT_DEGREES_CELSIUS: str¶: "Cel" – gradi Celsius.

SENML_UNIT_LUMEN: str¶: "lm" – lumen.

SENML_UNIT_LUX: str¶: "lx" – lux.

SENML_UNIT_BECQUEREL: str¶: "Bq" – becquerel.

SENML_UNIT_GRAY: str¶: "Gy" – gray.

SENML_UNIT_SIEVERT: str¶: "Sv" – sievert.

SENML_UNIT_KATAL: str¶: "kat" – katal.

SENML_UNIT_SQUARE_METER: str¶: "m2" – metro quadrato.

SENML_UNIT_CUBIC_METER: str¶: "m3" – metro cubo.

SENML_UNIT_LITER: str¶: "l" – litro.

SENML_UNIT_VELOCITY: str¶: "m/s" – velocità.

SENML_UNIT_ACCELERATION: str¶: "m/s2" – accelerazione.

SENML_UNIT_CUBIC_METER_PER_SECOND: str¶: "m3/s" – portata volumetrica.

SENML_UNIT_LITER_PER_SECOND: str¶: "l/s" – litri al secondo.

SENML_UNIT_WATT_PER_SQUARE_METER: str¶: "W/m2" – irradianza.

SENML_UNIT_CANDELA_PER_SQUARE_METER: str¶: "cd/m2" – luminanza.

SENML_UNIT_BIT: str¶: "bit" – bit.

SENML_UNIT_BIT_PER_SECOND: str¶: "bit/s" – bit al secondo.

SENML_UNIT_DEGREES_LATITUDE: str¶: "lat" – gradi di latitudine.

SENML_UNIT_DEGREES_LONGITUDE: str¶: "lon" – gradi di longitudine.

SENML_UNIT_PH: str¶: "pH" – acidità (pH).

SENML_UNIT_DECIBEL: str¶: "db" – decibel.

SENML_UNIT_DECIBEL_RELATIVE_TO_1_W: str¶: "dBW" – decibel rispetto a 1 W.

SENML_UNIT_BEL: str¶: "Bspl" – bel (livello di pressione sonora).

SENML_UNIT_COUNTER: str¶: "count" – contatore.

SENML_UNIT_RATIO: str¶: "//" – rapporto (adimensionale).

SENML_UNIT_RELATIVE_HUMIDITY: str¶: "%RH" – umidità relativa.

SENML_UNIT_PERCENTAGE_REMAINING_BATTERY_LEVEL: str¶: "%EL" – livello residuo della batteria in percentuale.

SENML_UNIT_SECONDS_REMAINING_BATTERY_LEVEL: str¶: "EL" – livello residuo della batteria in secondi.

SENML_UNIT_EVENT_RATE_PER_SECOND: str¶: "1/s" – frequenza degli eventi al secondo.

SENML_UNIT_EVENT_RATE_PER_MINUTE: str¶: "1/min" – frequenza degli eventi al minuto.

SENML_UNIT_BPM: str¶: "beat/min" – battiti al minuto.

SENML_UNIT_BEATS: str¶: "beats" – battiti.

SENML_UNIT_SIEMENS_PER_METER: str¶: "S/m" – siemens al metro (conducibilità elettrica).

senml — Sensor Markup Language¶

Classi¶

`senml` — Sensor Markup Language¶