`senml` — Sensor Markup Language¶

Tento modul implementuje malý kodér/dekodér pro jazyk Sensor Markup Language (SenML, RFC 8428). SenML je mediální typ pro měření ze senzorů a parametry zařízení: každý „pack“ je seznam „records“ (záznamů), kde každý záznam nese název, jednotku, hodnotu, časové razítko a volitelný součet.

Implementace podporuje reprezentaci jak v JSON, tak v CBOR a umožňuje vnořování packů, takže jediný kořenový pack může popisovat bránu zaštiťující více zařízení. Příchozí payloady mohou spouštět callbacky aktuátorů u existujících záznamů.

Příklad použití:

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

Třídy¶

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

Reprezentuje SenML pack – kolekci instancí SenmlRecord a volitelně dalších podřízených objektů SenmlPack. Když pack obsahuje pouze záznamy, reprezentuje jediné zařízení; když obsahuje další packy, funguje jako brána.

name je základní název SenML (bn) použitý pro každý záznam obsažený v tomto packu.

callback je voláno z from_json / from_cbor, kdykoli příchozí záznam pojmenuje dříve neznámý senzor; nový SenmlRecord je předán jako první argument a (u vnořených packů) je původní pack zařízení předán jako device=.... Typicky se používá ke zpracování příkazů aktuátorů.

Instance SenmlPack jsou iterovatelné – iterace vrací jednotlivé záznamy v pořadí vložení – a mohou být použity jako kontextový manažer, takže při ukončení se pack sám odebere ze svého rodiče.

name: str¶: Základní název packu (bn).

base_value: int | float | None¶: Volitelná základní hodnota (bv) přičtená k numerické hodnotě každého záznamu při kódování a odečtená při dekódování. Nastavení nenumerické hodnoty vyvolá Exception.

base_time: int | float | None¶: Volitelný základní čas (bt) přičtený k časovému razítku každého záznamu.

base_sum: int | float | None¶: Volitelný základní součet (bs) přičtený k poli součtu každého záznamu.

base_unit: str | None¶: Volitelná základní jednotka (bu) – typicky hodnota z SenmlUnits.

actuate¶: Callback dodaný při konstrukci. Lze ho znovu přiřadit za běhu.

add(item: SenmlRecord | SenmlPack) → None¶: Připojí item k tomuto packu. item musí být SenmlRecord nebo jiný SenmlPack a nesmí již patřit jinému rodiči; jinak je vyvolána Exception.

remove(item: SenmlRecord | SenmlPack) → None¶: Odebere item z tohoto packu. Exception je vyvolána, pokud item není potomkem tohoto packu.

clear() → None¶: Odebere každý záznam/podřízený pack z tohoto packu a odpojí je od jejich referenci na rodiče.

from_json(data: str) → None¶: Naparsuje dokument SenML/JSON a sloučí záznamy do tohoto packu. Záznamy, které již existují (porovnané podle názvu), spustí SenmlRecord.do_actuate(); nové záznamy jsou připojeny a je vyvoláno callback na úrovni packu.

to_json() → str¶: Vykreslí pack a jeho potomky do řetězce SenML/JSON.

from_cbor(data: bytes) → None¶: Naparsuje bajtový řetězec SenML/CBOR a sloučí záznamy do tohoto packu.

to_cbor() → bytes¶: Vykreslí pack a jeho potomky do bajtového řetězce SenML/CBOR.

do_actuate(raw: dict, naming_map: dict, device: SenmlPack | None = None) → None¶: Interní pomocná funkce volaná během parsování příchozích dat, když žádný existující záznam neodpovídá položce. Přidá nový SenmlRecord do device (nebo do tohoto packu) a předá ho dál callbacku.

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

Reprezentuje jediné měření uvnitř SenmlPack.

name je název SenML záznamu (n).

Přijímány jsou následující klíčové argumenty:

value – bool, int, float, str nebo bytearray. Ostatní typy vyvolají Exception.
time – numerické časové razítko (t).
unit – řetězec jednotky, typicky člen SenmlUnits.
sum – numerický integrovaný součet (s).
update_time – maximální čas, než senzor poskytne čerstvé čtení (ut).
callback – funkce volaná, když příchozí payload aktualizuje tento záznam. Přijímá SenmlRecord jako svůj jediný argument.

SenmlRecord lze použít jako kontextový manažer, takže při ukončení se sám odebere ze svého rodičovského packu.

name: str¶: Název záznamu (n).

value¶: Aktuální hodnota. Při novém přiřazení se kontroluje typ; přijímány jsou pouze bool, čísla, str a bytearray. Pro řízení vykreslované přesnosti hodnoty typu float zaokrouhlete před přiřazením, např. record.value = round(x, 2).

unit: str | None¶: Řetězec jednotky (u).

time: int | float | None¶: Časové razítko spojené s tímto měřením (t).

update_time: int | float | None¶: Maximální čas, než senzor poskytne aktualizované čtení (ut).

sum: int | float | None¶: Pole integrovaného součtu (s).

actuate¶: Callback dodaný při konstrukci. Lze ho znovu přiřadit za běhu.

do_actuate(raw: dict, naming_map: dict) → None¶: Aktualizuje tento záznam ze surového příchozího SenML slovníku a, je-li přítomen, vyvolá actuate callback.

class senml.SenmlBase¶: Společná základní třída sdílená SenmlPack a SenmlRecord. Nevystavuje žádné vlastní veřejné API; existuje proto, aby SenmlPack.add() mohla ověřit, že položka patří do hierarchie SenML.

class senml.SenmlUnits¶

Třída jmenného prostoru, jejíž atributy třídy jsou symboly jednotek SenML definované v RFC 8428. Každý atribut se rozliší na řetězcový kód jednotky vhodný pro přiřazení do SenmlRecord.unit nebo SenmlPack.base_unit.

SENML_UNIT_METER: str¶: "m" – metr.

SENML_UNIT_KILOGRAM: str¶: "kg" – kilogram.

SENML_UNIT_GRAM: str¶: "g" – gram.

SENML_UNIT_SECOND: str¶: "s" – sekunda.

SENML_UNIT_AMPERE: str¶: "A" – ampér.

SENML_UNIT_KELVIN: str¶: "K" – kelvin.

SENML_UNIT_CANDELA: str¶: "cd" – kandela.

SENML_UNIT_MOLE: str¶: "mol" – mol.

SENML_UNIT_HERTZ: str¶: "Hz" – hertz.

SENML_UNIT_RADIAN: str¶: "rad" – radián.

SENML_UNIT_STERADIAN: str¶: "sr" – steradián.

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" – stupně Celsia.

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" – metr čtvereční.

SENML_UNIT_CUBIC_METER: str¶: "m3" – metr krychlový.

SENML_UNIT_LITER: str¶: "l" – litr.

SENML_UNIT_VELOCITY: str¶: "m/s" – rychlost.

SENML_UNIT_ACCELERATION: str¶: "m/s2" – zrychlení.

SENML_UNIT_CUBIC_METER_PER_SECOND: str¶: "m3/s" – objemový průtok.

SENML_UNIT_LITER_PER_SECOND: str¶: "l/s" – litr za sekundu.

SENML_UNIT_WATT_PER_SQUARE_METER: str¶: "W/m2" – ozáření.

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

SENML_UNIT_BIT: str¶: "bit" – bit.

SENML_UNIT_BIT_PER_SECOND: str¶: "bit/s" – bit za sekundu.

SENML_UNIT_DEGREES_LATITUDE: str¶: "lat" – stupně zeměpisné šířky.

SENML_UNIT_DEGREES_LONGITUDE: str¶: "lon" – stupně zeměpisné délky.

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

SENML_UNIT_DECIBEL: str¶: "db" – decibel.

SENML_UNIT_DECIBEL_RELATIVE_TO_1_W: str¶: "dBW" – decibel vztažený k 1 W.

SENML_UNIT_BEL: str¶: "Bspl" – bel (hladina akustického tlaku).

SENML_UNIT_COUNTER: str¶: "count" – čítač.

SENML_UNIT_RATIO: str¶: "//" – poměr (bezrozměrný).

SENML_UNIT_RELATIVE_HUMIDITY: str¶: "%RH" – relativní vlhkost.

SENML_UNIT_PERCENTAGE_REMAINING_BATTERY_LEVEL: str¶: "%EL" – zbývající úroveň baterie v procentech.

SENML_UNIT_SECONDS_REMAINING_BATTERY_LEVEL: str¶: "EL" – zbývající úroveň baterie v sekundách.

SENML_UNIT_EVENT_RATE_PER_SECOND: str¶: "1/s" – četnost událostí za sekundu.

SENML_UNIT_EVENT_RATE_PER_MINUTE: str¶: "1/min" – četnost událostí za minutu.

SENML_UNIT_BPM: str¶: "beat/min" – údery za minutu.

SENML_UNIT_BEATS: str¶: "beats" – údery.

SENML_UNIT_SIEMENS_PER_METER: str¶: "S/m" – siemens na metr (elektrická vodivost).

senml — Sensor Markup Language¶

Třídy¶

`senml` — Sensor Markup Language¶