`senml` — Sensor Markup Language¶

Acest modul implementează un mic encoder/decoder pentru Sensor Markup Language (SenML, RFC 8428). SenML este un tip media pentru măsurători de la senzori și parametri ai dispozitivelor: fiecare „pack” este o listă de „records”, unde fiecare înregistrare conține un nume, o unitate, o valoare, un marcaj temporal și o sumă opțională.

Implementarea acceptă atât reprezentarea JSON, cât și CBOR și permite ca pachetele să fie imbricate, astfel încât un singur pachet rădăcină să poată descrie un gateway care deservește mai multe dispozitive. Sarcinile utile primite pot declanșa funcții de retroapelare (callback) pentru actuatori pe înregistrările existente.

Exemplu de utilizare:

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())

Clase¶

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

Reprezintă un pachet SenML – o colecție de instanțe SenmlRecord și, opțional, alte obiecte SenmlPack copil. Atunci când un pachet conține doar înregistrări, reprezintă un singur dispozitiv; atunci când conține alte pachete, acționează ca un gateway.

name este numele de bază SenML (bn) folosit pentru fiecare înregistrare conținută în acest pachet.

callback este apelat din from_json / from_cbor ori de câte ori o înregistrare primită numește un senzor necunoscut anterior; noul SenmlRecord este transmis ca prim argument, iar (pentru pachetele imbricate) pachetul dispozitivului de origine este transmis ca device=.... De obicei este folosit pentru a gestiona comenzile către actuatori.

Instanțele SenmlPack sunt iterabile – iterarea returnează fiecare înregistrare în ordinea inserării – și pot fi folosite ca manager de context, astfel încât la ieșire pachetul se elimină singur din părintele său.

name: str¶: Numele de bază al pachetului (bn).

base_value: int | float | None¶: Valoarea de bază opțională (bv) adăugată la valoarea numerică a fiecărei înregistrări la codificare și scăzută la decodificare. Setarea unei valori nenumerice generează Exception.

base_time: int | float | None¶: Timpul de bază opțional (bt) adăugat la marcajul temporal al fiecărei înregistrări.

base_sum: int | float | None¶: Suma de bază opțională (bs) adăugată la câmpul sumă al fiecărei înregistrări.

base_unit: str | None¶: Unitatea de bază opțională (bu) – de obicei o valoare din SenmlUnits.

actuate¶: Funcția de retroapelare (callback) furnizată la momentul construcției. Poate fi reatribuită în timpul execuției.

add(item: SenmlRecord | SenmlPack) → None¶: Adaugă item la acest pachet. item trebuie să fie un SenmlRecord sau un alt SenmlPack și nu trebuie să aparțină deja unui alt părinte; în caz contrar se generează Exception.

remove(item: SenmlRecord | SenmlPack) → None¶: Elimină item din acest pachet. Exception este generat dacă item nu este copil al acestui pachet.

clear() → None¶: Elimină fiecare înregistrare/sub-pachet din acest pachet și le detașează de referința lor către părinte.

from_json(data: str) → None¶: Analizează un document SenML/JSON și îmbină înregistrările în acest pachet. Înregistrările care există deja (potrivite după nume) declanșează SenmlRecord.do_actuate(); înregistrările noi sunt adăugate, iar funcția callback la nivel de pachet este apelată.

to_json() → str¶: Redă pachetul și copiii săi într-un șir SenML/JSON.

from_cbor(data: bytes) → None¶: Analizează un șir de octeți SenML/CBOR și îmbină înregistrările în acest pachet.

to_cbor() → bytes¶: Redă pachetul și copiii săi într-un șir de octeți SenML/CBOR.

do_actuate(raw: dict, naming_map: dict, device: SenmlPack | None = None) → None¶: Funcție ajutătoare internă apelată în timpul analizării datelor primite atunci când nicio înregistrare existentă nu se potrivește cu o intrare. Adaugă un nou SenmlRecord la device (sau la acest pachet) și îl transmite mai departe către callback.

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

Reprezintă o singură măsurătoare în interiorul unui SenmlPack.

name este numele înregistrării SenML (n).

Sunt acceptate următoarele argumente cheie:

value – bool, int, float, str sau bytearray. Alte tipuri generează Exception.
time – marcaj temporal numeric (t).
unit – un șir de unitate, de obicei un membru al SenmlUnits.
sum – sumă integrată numerică (s).
update_time – timpul maxim înainte ca senzorul să furnizeze o citire nouă (ut).
callback – funcție apelată atunci când o sarcină utilă primită actualizează această înregistrare. Primește SenmlRecord ca unic argument.

SenmlRecord poate fi folosit ca manager de context, astfel încât la ieșire se elimină singur din pachetul său părinte.

name: str¶: Numele înregistrării (n).

value¶: Valoarea curentă. Reatribuirea verifică tipul; sunt acceptate doar bool, numere, str și bytearray. Pentru a controla precizia redată a unei valori float, rotunjiți înainte de atribuire, de ex. record.value = round(x, 2).

unit: str | None¶: Șirul de unitate (u).

time: int | float | None¶: Marcajul temporal asociat cu această măsurătoare (t).

update_time: int | float | None¶: Timpul maxim înainte ca senzorul să furnizeze o citire actualizată (ut).

sum: int | float | None¶: Câmpul sumă integrată (s).

actuate¶: Funcția de retroapelare (callback) furnizată la momentul construcției. Poate fi reatribuită în timpul execuției.

do_actuate(raw: dict, naming_map: dict) → None¶: Actualizează această înregistrare dintr-un dicționar SenML brut primit și, dacă este prezent, apelează funcția de retroapelare pentru actuator.

class senml.SenmlBase¶: Clasă de bază comună partajată de SenmlPack și SenmlRecord. Nu expune niciun API public propriu; există pentru ca SenmlPack.add() să poată valida faptul că un element aparține ierarhiei SenML.

class senml.SenmlUnits¶

Clasă spațiu de nume ale cărei atribute de clasă sunt simbolurile de unitate SenML definite de RFC 8428. Fiecare atribut se rezolvă la codul de tip șir al unității, potrivit pentru atribuire la SenmlRecord.unit sau SenmlPack.base_unit.

SENML_UNIT_METER: str¶: "m" – metru.

SENML_UNIT_KILOGRAM: str¶: "kg" – kilogram.

SENML_UNIT_GRAM: str¶: "g" – gram.

SENML_UNIT_SECOND: str¶: "s" – secundă.

SENML_UNIT_AMPERE: str¶: "A" – amper.

SENML_UNIT_KELVIN: str¶: "K" – kelvin.

SENML_UNIT_CANDELA: str¶: "cd" – candelă.

SENML_UNIT_MOLE: str¶: "mol" – mol.

SENML_UNIT_HERTZ: str¶: "Hz" – hertz.

SENML_UNIT_RADIAN: str¶: "rad" – radian.

SENML_UNIT_STERADIAN: str¶: "sr" – steradian.

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" – grade 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" – metru pătrat.

SENML_UNIT_CUBIC_METER: str¶: "m3" – metru cub.

SENML_UNIT_LITER: str¶: "l" – litru.

SENML_UNIT_VELOCITY: str¶: "m/s" – viteză.

SENML_UNIT_ACCELERATION: str¶: "m/s2" – accelerație.

SENML_UNIT_CUBIC_METER_PER_SECOND: str¶: "m3/s" – debit volumetric.

SENML_UNIT_LITER_PER_SECOND: str¶: "l/s" – litru pe secundă.

SENML_UNIT_WATT_PER_SQUARE_METER: str¶: "W/m2" – iradianță.

SENML_UNIT_CANDELA_PER_SQUARE_METER: str¶: "cd/m2" – luminanță.

SENML_UNIT_BIT: str¶: "bit" – bit.

SENML_UNIT_BIT_PER_SECOND: str¶: "bit/s" – bit pe secundă.

SENML_UNIT_DEGREES_LATITUDE: str¶: "lat" – grade de latitudine.

SENML_UNIT_DEGREES_LONGITUDE: str¶: "lon" – grade de longitudine.

SENML_UNIT_PH: str¶: "pH" – aciditate (pH).

SENML_UNIT_DECIBEL: str¶: "db" – decibel.

SENML_UNIT_DECIBEL_RELATIVE_TO_1_W: str¶: "dBW" – decibel raportat la 1 W.

SENML_UNIT_BEL: str¶: "Bspl" – bel (nivel de presiune acustică).

SENML_UNIT_COUNTER: str¶: "count" – contor.

SENML_UNIT_RATIO: str¶: "//" – raport (adimensional).

SENML_UNIT_RELATIVE_HUMIDITY: str¶: "%RH" – umiditate relativă.

SENML_UNIT_PERCENTAGE_REMAINING_BATTERY_LEVEL: str¶: "%EL" – nivel rămas al bateriei ca procent.

SENML_UNIT_SECONDS_REMAINING_BATTERY_LEVEL: str¶: "EL" – nivel rămas al bateriei în secunde.

SENML_UNIT_EVENT_RATE_PER_SECOND: str¶: "1/s" – rată de evenimente pe secundă.

SENML_UNIT_EVENT_RATE_PER_MINUTE: str¶: "1/min" – rată de evenimente pe minut.

SENML_UNIT_BPM: str¶: "beat/min" – bătăi pe minut.

SENML_UNIT_BEATS: str¶: "beats" – bătăi.

SENML_UNIT_SIEMENS_PER_METER: str¶: "S/m" – siemens pe metru (conductivitate electrică).

senml — Sensor Markup Language¶

Clase¶

`senml` — Sensor Markup Language¶