`senml` — Sensor Markup Language¶

Ten moduł implementuje niewielki koder/dekoder dla języka Sensor Markup Language (SenML, RFC 8428). SenML to typ medialny służący do reprezentowania pomiarów z sensorów i parametrów urządzeń: każdy „pack” jest listą „rekordów”, przy czym każdy rekord zawiera nazwę, jednostkę, wartość, znacznik czasu oraz opcjonalną sumę.

Implementacja obsługuje zarówno reprezentację JSON, jak i CBOR oraz pozwala zagnieżdżać packi, dzięki czemu jeden pack główny może opisywać bramę pośredniczącą dla wielu urządzeń. Przychodzące dane mogą wyzwalać wywołania zwrotne aktuatorów na istniejących rekordach.

Przykład użycia:

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

Klasy¶

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

Reprezentuje pack SenML – kolekcję instancji SenmlRecord oraz opcjonalnie innych podrzędnych obiektów SenmlPack. Gdy pack zawiera wyłącznie rekordy, reprezentuje pojedyncze urządzenie; gdy zawiera inne packi, działa jako brama.

name to bazowa nazwa SenML (bn) używana dla każdego rekordu zawartego w tym packu.

callback jest wywoływane z from_json / from_cbor zawsze, gdy przychodzący rekord nazywa wcześniej nieznany sensor; nowy SenmlRecord jest przekazywany jako pierwszy argument, a (w przypadku packów zagnieżdżonych) źródłowy pack urządzenia jest przekazywany jako device=.... Zwykle służy do obsługi poleceń dla aktuatorów.

Instancje SenmlPack są iterowalne – iteracja zwraca każdy rekord w kolejności wstawiania – i mogą być używane jako menedżer kontekstu, dzięki czemu przy wyjściu pack usuwa się ze swojego rodzica.

name: str¶: Bazowa nazwa packu (bn).

base_value: int | float | None¶: Opcjonalna wartość bazowa (bv) dodawana do liczbowej wartości każdego rekordu podczas kodowania i odejmowana podczas dekodowania. Ustawienie wartości nieliczbowej zgłasza Exception.

base_time: int | float | None¶: Opcjonalny czas bazowy (bt) dodawany do znacznika czasu każdego rekordu.

base_sum: int | float | None¶: Opcjonalna suma bazowa (bs) dodawana do pola sumy każdego rekordu.

base_unit: str | None¶: Opcjonalna jednostka bazowa (bu) – zwykle wartość z SenmlUnits.

actuate¶: Wywołanie zwrotne dostarczone w momencie konstrukcji. Może zostać ponownie przypisane w czasie działania.

add(item: SenmlRecord | SenmlPack) → None¶: Dołącza item do tego packu. item musi być obiektem SenmlRecord lub innym SenmlPack i nie może już należeć do innego rodzica; w przeciwnym razie zgłaszany jest Exception.

remove(item: SenmlRecord | SenmlPack) → None¶: Usuwa item z tego packu. Exception jest zgłaszany, jeśli item nie jest elementem podrzędnym tego packu.

clear() → None¶: Usuwa każdy rekord/podrzędny pack z tego packu i odłącza je od odniesienia do rodzica.

from_json(data: str) → None¶: Parsuje dokument SenML/JSON i scala rekordy z tym packiem. Rekordy, które już istnieją (dopasowane po nazwie), wyzwalają SenmlRecord.do_actuate(); nowe rekordy są dołączane, a wywołane zostaje callback na poziomie packu.

to_json() → str¶: Renderuje pack i jego elementy podrzędne do łańcucha znaków SenML/JSON.

from_cbor(data: bytes) → None¶: Parsuje łańcuch bajtów SenML/CBOR i scala rekordy z tym packiem.

to_cbor() → bytes¶: Renderuje pack i jego elementy podrzędne do łańcucha bajtów SenML/CBOR.

do_actuate(raw: dict, naming_map: dict, device: SenmlPack | None = None) → None¶: Wewnętrzna funkcja pomocnicza wywoływana podczas parsowania przychodzących danych, gdy żaden istniejący rekord nie pasuje do wpisu. Dodaje nowy SenmlRecord do device (lub do tego packu) i przekazuje go do callback.

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

Reprezentuje pojedynczy pomiar wewnątrz SenmlPack.

name to nazwa rekordu SenML (n).

Akceptowane są następujące argumenty nazwane:

value – bool, int, float, str lub bytearray. Inne typy zgłaszają Exception.
time – liczbowy znacznik czasu (t).
unit – łańcuch jednostki, zwykle element SenmlUnits.
sum – liczbowa suma scałkowana (s).
update_time – maksymalny czas, zanim sensor dostarczy nowy odczyt (ut).
callback – funkcja wywoływana, gdy przychodzące dane aktualizują ten rekord. Otrzymuje SenmlRecord jako jedyny argument.

SenmlRecord może być używany jako menedżer kontekstu, dzięki czemu przy wyjściu usuwa się ze swojego packu nadrzędnego.

name: str¶: Nazwa rekordu (n).

value¶: Bieżąca wartość. Ponowne przypisanie sprawdza typ; akceptowane są tylko bool, liczby, str oraz bytearray. Aby kontrolować renderowaną precyzję wartości zmiennoprzecinkowej, zaokrąglij ją przed przypisaniem, np. record.value = round(x, 2).

unit: str | None¶: Łańcuch jednostki (u).

time: int | float | None¶: Znacznik czasu powiązany z tym pomiarem (t).

update_time: int | float | None¶: Maksymalny czas, zanim sensor dostarczy zaktualizowany odczyt (ut).

sum: int | float | None¶: Pole sumy scałkowanej (s).

actuate¶: Wywołanie zwrotne dostarczone w momencie konstrukcji. Może zostać ponownie przypisane w czasie działania.

do_actuate(raw: dict, naming_map: dict) → None¶: Aktualizuje ten rekord na podstawie surowego przychodzącego słownika SenML i, jeśli istnieje, wywołuje wywołanie zwrotne aktuatora.

class senml.SenmlBase¶: Wspólna klasa bazowa współdzielona przez SenmlPack i SenmlRecord. Nie udostępnia własnego publicznego API; istnieje po to, aby SenmlPack.add() mogła zweryfikować, że element należy do hierarchii SenML.

class senml.SenmlUnits¶

Klasa przestrzeni nazw, której atrybuty klasowe są symbolami jednostek SenML zdefiniowanymi przez RFC 8428. Każdy atrybut zwraca kod łańcuchowy jednostki, odpowiedni do przypisania do SenmlRecord.unit lub 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" – amper.

SENML_UNIT_KELVIN: str¶: "K" – kelwin.

SENML_UNIT_CANDELA: str¶: "cd" – kandela.

SENML_UNIT_MOLE: str¶: "mol" – mol.

SENML_UNIT_HERTZ: str¶: "Hz" – herc.

SENML_UNIT_RADIAN: str¶: "rad" – radian.

SENML_UNIT_STERADIAN: str¶: "sr" – steradian.

SENML_UNIT_NEWTON: str¶: "N" – niuton.

SENML_UNIT_PASCAL: str¶: "Pa" – paskal.

SENML_UNIT_JOULE: str¶: "J" – dżul.

SENML_UNIT_WATT: str¶: "W" – wat.

SENML_UNIT_COULOMB: str¶: "C" – kulomb.

SENML_UNIT_VOLT: str¶: "V" – wolt.

SENML_UNIT_FARAD: str¶: "F" – farad.

SENML_UNIT_OHM: str¶: "Ohm" – om.

SENML_UNIT_SIEMENS: str¶: "S" – simens.

SENML_UNIT_WEBER: str¶: "Wb" – weber.

SENML_UNIT_TESLA: str¶: "T" – tesla.

SENML_UNIT_HENRY: str¶: "H" – henr.

SENML_UNIT_DEGREES_CELSIUS: str¶: "Cel" – stopnie Celsjusza.

SENML_UNIT_LUMEN: str¶: "lm" – lumen.

SENML_UNIT_LUX: str¶: "lx" – luks.

SENML_UNIT_BECQUEREL: str¶: "Bq" – bekerel.

SENML_UNIT_GRAY: str¶: "Gy" – grej.

SENML_UNIT_SIEVERT: str¶: "Sv" – siwert.

SENML_UNIT_KATAL: str¶: "kat" – katal.

SENML_UNIT_SQUARE_METER: str¶: "m2" – metr kwadratowy.

SENML_UNIT_CUBIC_METER: str¶: "m3" – metr sześcienny.

SENML_UNIT_LITER: str¶: "l" – litr.

SENML_UNIT_VELOCITY: str¶: "m/s" – prędkość.

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

SENML_UNIT_CUBIC_METER_PER_SECOND: str¶: "m3/s" – objętościowe natężenie przepływu.

SENML_UNIT_LITER_PER_SECOND: str¶: "l/s" – litr na sekundę.

SENML_UNIT_WATT_PER_SQUARE_METER: str¶: "W/m2" – natężenie napromieniowania.

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

SENML_UNIT_BIT: str¶: "bit" – bit.

SENML_UNIT_BIT_PER_SECOND: str¶: "bit/s" – bit na sekundę.

SENML_UNIT_DEGREES_LATITUDE: str¶: "lat" – stopnie szerokości geograficznej.

SENML_UNIT_DEGREES_LONGITUDE: str¶: "lon" – stopnie długości geograficznej.

SENML_UNIT_PH: str¶: "pH" – kwasowość (pH).

SENML_UNIT_DECIBEL: str¶: "db" – decybel.

SENML_UNIT_DECIBEL_RELATIVE_TO_1_W: str¶: "dBW" – decybel względem 1 W.

SENML_UNIT_BEL: str¶: "Bspl" – bel (poziom ciśnienia akustycznego).

SENML_UNIT_COUNTER: str¶: "count" – licznik.

SENML_UNIT_RATIO: str¶: "//" – stosunek (bezwymiarowy).

SENML_UNIT_RELATIVE_HUMIDITY: str¶: "%RH" – wilgotność względna.

SENML_UNIT_PERCENTAGE_REMAINING_BATTERY_LEVEL: str¶: "%EL" – pozostały poziom naładowania baterii w procentach.

SENML_UNIT_SECONDS_REMAINING_BATTERY_LEVEL: str¶: "EL" – pozostały poziom naładowania baterii w sekundach.

SENML_UNIT_EVENT_RATE_PER_SECOND: str¶: "1/s" – częstość zdarzeń na sekundę.

SENML_UNIT_EVENT_RATE_PER_MINUTE: str¶: "1/min" – częstość zdarzeń na minutę.

SENML_UNIT_BPM: str¶: "beat/min" – uderzenia na minutę.

SENML_UNIT_BEATS: str¶: "beats" – uderzenia.

SENML_UNIT_SIEMENS_PER_METER: str¶: "S/m" – simens na metr (przewodność elektryczna).

senml — Sensor Markup Language¶

Klasy¶

`senml` — Sensor Markup Language¶