senml — Sensor Markup Language

Denna modul implementerar en liten kodare/avkodare för Sensor Markup Language (SenML, RFC 8428). SenML är en medietyp för sensormätningar och enhetsparametrar: varje ”pack” är en lista av ”records”, där varje record bär ett namn, en enhet, ett värde, en tidsstämpel och en valfri summa.

Implementeringen stöder både JSON- och CBOR-representationerna och tillåter att pack nästlas så att ett enda rotpack kan beskriva en gateway som fronter flera enheter. Inkommande nyttolaster kan driva aktuatoråteranrop på befintliga records.

Exempel på användning:

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

Klasser

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

Representerar ett SenML-pack – en samling av SenmlRecord-instanser och eventuellt andra underordnade SenmlPack-objekt. När ett pack endast innehåller records representerar det en enskild enhet; när det innehåller andra pack fungerar det som en gateway.

name är SenML-basnamnet (bn) som används för varje record i detta pack.

callback anropas från from_json / from_cbor närhelst ett inkommande record namnger en tidigare okänd sensor; det nya SenmlRecord skickas som det första argumentet och (för nästlade pack) skickas det ursprungliga enhetspacket som device=.... Det används vanligtvis för att hantera aktuatorkommandon.

SenmlPack-instanser är itererbara – iteration ger varje record i insättningsordning – och kan användas som en kontexthanterare så att packet vid utträde tar bort sig självt från sin förälder.

name: str

Packets basnamn (bn).

base_value: int | float | None

Valfritt basvärde (bv) som läggs till varje records numeriska värde vid kodning och subtraheras vid avkodning. Att ange ett icke-numeriskt värde ger upphov till Exception.

base_time: int | float | None

Valfri bastid (bt) som läggs till varje records tidsstämpel.

base_sum: int | float | None

Valfri bassumma (bs) som läggs till varje records summafält.

base_unit: str | None

Valfri basenhet (bu) – vanligtvis ett värde från SenmlUnits.

actuate

Det återanrop som angavs vid konstruktionstillfället. Kan tilldelas på nytt under körning.

add(item: SenmlRecord | SenmlPack) → None

Lägg till item i detta pack. item måste vara ett SenmlRecord eller ett annat SenmlPack och får inte redan tillhöra en annan förälder; annars ges Exception upphov.

remove(item: SenmlRecord | SenmlPack) → None

Ta bort item från detta pack. Exception ges upphov om item inte är ett barn till detta pack.

clear() → None

Ta bort varje record/under-pack från detta pack och koppla loss dem från deras förälderreferens.

from_json(data: str) → None

Tolka ett SenML/JSON-dokument och slå samman dess records med detta pack. Records som redan finns (matchade på namn) utlöser SenmlRecord.do_actuate(); nya records läggs till och packets callback anropas.

to_json() → str

Rendera packet och dess barn till en SenML/JSON-sträng.

from_cbor(data: bytes) → None

Tolka en SenML/CBOR-bytesträng och slå samman dess records med detta pack.

to_cbor() → bytes

Rendera packet och dess barn till en SenML/CBOR-bytesträng.

do_actuate(raw: dict, naming_map: dict, device: SenmlPack | None = None) → None

Internt hjälpmedel som anropas vid tolkning av inkommande data när inget befintligt record matchar en post. Lägger till ett nytt SenmlRecord i device (eller i detta pack) och vidarebefordrar det till callback.

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

Representerar en enskild mätning inuti ett SenmlPack.

name är SenML-recordnamnet (n).

Följande nyckelordsargument accepteras:

• value – bool, int, float, str eller bytearray. Andra typer ger upphov till Exception.

• time – numerisk tidsstämpel (t).

• unit – en enhetssträng, vanligtvis en medlem av SenmlUnits.

• sum – numerisk integrerad summa (s).

• update_time – maximal tid innan sensorn kommer att ge en ny avläsning (ut).

• callback – funktion som anropas när en inkommande nyttolast uppdaterar detta record. Den tar emot SenmlRecord som sitt enda argument.

SenmlRecord kan användas som en kontexthanterare så att det vid utträde tar bort sig självt från sitt förälderpack.

name: str

Recordnamn (n).

value

Det aktuella värdet. Vid omtilldelning kontrolleras typen; endast bool, tal, str och bytearray accepteras. För att styra den renderade precisionen för ett flyttalsvärde, avrunda före tilldelningen, t.ex. record.value = round(x, 2).

unit: str | None

Enhetssträng (u).

time: int | float | None

Tidsstämpel kopplad till denna mätning (t).

update_time: int | float | None

Maximal tid innan sensorn kommer att ge en uppdaterad avläsning (ut).

sum: int | float | None

Integrerat summafält (s).

actuate

Det återanrop som angavs vid konstruktionstillfället. Kan tilldelas på nytt under körning.

do_actuate(raw: dict, naming_map: dict) → None

Uppdatera detta record från en rå inkommande SenML-ordbok och, om det finns, anropa aktueringsåteranropet.

class senml.SenmlBase

Gemensam basklass som delas av SenmlPack och SenmlRecord. Den exponerar inget eget publikt API; den existerar så att SenmlPack.add() kan validera att ett objekt tillhör SenML-hierarkin.

class senml.SenmlUnits

Namnrymdsklass vars klassattribut är de SenML-enhetssymboler som definieras av RFC 8428. Varje attribut motsvarar enhetens strängkod, lämplig för tilldelning till SenmlRecord.unit eller SenmlPack.base_unit.

SENML_UNIT_METER: str

"m" – meter.

SENML_UNIT_KILOGRAM: str

"kg" – kilogram.

SENML_UNIT_GRAM: str

"g" – gram.

SENML_UNIT_SECOND: str

"s" – sekund.

SENML_UNIT_AMPERE: str

"A" – ampere.

SENML_UNIT_KELVIN: str

"K" – kelvin.

SENML_UNIT_CANDELA: str

"cd" – candela.

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" – grader 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" – kvadratmeter.

SENML_UNIT_CUBIC_METER: str

"m3" – kubikmeter.

SENML_UNIT_LITER: str

"l" – liter.

SENML_UNIT_VELOCITY: str

"m/s" – hastighet.

SENML_UNIT_ACCELERATION: str

"m/s2" – acceleration.

SENML_UNIT_CUBIC_METER_PER_SECOND: str

"m3/s" – volymetriskt flöde.

SENML_UNIT_LITER_PER_SECOND: str

"l/s" – liter per sekund.

SENML_UNIT_WATT_PER_SQUARE_METER: str

"W/m2" – irradians.

SENML_UNIT_CANDELA_PER_SQUARE_METER: str

"cd/m2" – luminans.

SENML_UNIT_BIT: str

"bit" – bit.

SENML_UNIT_BIT_PER_SECOND: str

"bit/s" – bit per sekund.

SENML_UNIT_DEGREES_LATITUDE: str

"lat" – grader latitud.

SENML_UNIT_DEGREES_LONGITUDE: str

"lon" – grader longitud.

SENML_UNIT_PH: str

"pH" – surhet (pH).

SENML_UNIT_DECIBEL: str

"db" – decibel.

SENML_UNIT_DECIBEL_RELATIVE_TO_1_W: str

"dBW" – decibel relativt 1 W.

SENML_UNIT_BEL: str

"Bspl" – bel (ljudtrycksnivå).

SENML_UNIT_COUNTER: str

"count" – räknare.

SENML_UNIT_RATIO: str

"//" – förhållande (dimensionslöst).

SENML_UNIT_RELATIVE_HUMIDITY: str

"%RH" – relativ luftfuktighet.

SENML_UNIT_PERCENTAGE_REMAINING_BATTERY_LEVEL: str

"%EL" – återstående batterinivå i procent.

SENML_UNIT_SECONDS_REMAINING_BATTERY_LEVEL: str

"EL" – återstående batterinivå i sekunder.

SENML_UNIT_EVENT_RATE_PER_SECOND: str

"1/s" – händelsefrekvens per sekund.

SENML_UNIT_EVENT_RATE_PER_MINUTE: str

"1/min" – händelsefrekvens per minut.

SENML_UNIT_BPM: str

"beat/min" – slag per minut.

SENML_UNIT_BEATS: str

"beats" – slag.

SENML_UNIT_SIEMENS_PER_METER: str

"S/m" – siemens per meter (elektrisk konduktivitet).