`senml` — Sensor Markup Language¶

Deze module implementeert een kleine encoder/decoder voor de Sensor Markup Language (SenML, RFC 8428). SenML is een mediatype voor sensormetingen en apparaatparameters: elke “pack” is een lijst van “records”, waarbij elk record een naam, eenheid, waarde, tijdstempel en optionele som bevat.

De implementatie ondersteunt zowel de JSON- als de CBOR-representatie en staat toe dat packs genest worden, zodat een enkel root-pack een gateway kan beschrijven die meerdere apparaten ontsluit. Inkomende payloads kunnen actuator-callbacks op bestaande records aansturen.

Voorbeeldgebruik:

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

Klassen¶

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

Vertegenwoordigt een SenML-pack – een verzameling van SenmlRecord-instanties en optioneel andere onderliggende SenmlPack-objecten. Wanneer een pack alleen records bevat, vertegenwoordigt het een enkel apparaat; wanneer het andere packs bevat, fungeert het als een gateway.

name is de SenML-basisnaam (bn) die voor elk record in dit pack wordt gebruikt.

callback wordt aangeroepen vanuit from_json / from_cbor telkens wanneer een inkomend record een eerder onbekende sensor benoemt; het nieuwe SenmlRecord wordt als eerste argument doorgegeven en (voor geneste packs) wordt het oorspronkelijke apparaat-pack doorgegeven als device=.... Het wordt doorgaans gebruikt om actuatorcommando’s af te handelen.

SenmlPack-instanties zijn itereerbaar – iteratie levert elk record op in invoegvolgorde – en kunnen worden gebruikt als een context manager zodat het pack zichzelf bij het afsluiten uit zijn ouder verwijdert.

name: str¶: De basisnaam van het pack (bn).

base_value: int | float | None¶: Optionele basiswaarde (bv) die bij het coderen wordt toegevoegd aan de numerieke waarde van elk record en bij het decoderen wordt afgetrokken. Het instellen van een niet-numerieke waarde veroorzaakt Exception.

base_time: int | float | None¶: Optionele basistijd (bt) die wordt toegevoegd aan de tijdstempel van elk record.

base_sum: int | float | None¶: Optionele basissom (bs) die wordt toegevoegd aan het som-veld van elk record.

base_unit: str | None¶: Optionele basiseenheid (bu) – doorgaans een waarde uit SenmlUnits.

actuate¶: De callback die bij de constructie is opgegeven. Kan tijdens runtime opnieuw worden toegewezen.

add(item: SenmlRecord | SenmlPack) → None¶: Voeg item toe aan dit pack. item moet een SenmlRecord of een ander SenmlPack zijn en mag nog niet tot een andere ouder behoren; anders wordt Exception veroorzaakt.

remove(item: SenmlRecord | SenmlPack) → None¶: Verwijder item uit dit pack. Exception wordt veroorzaakt als item geen kind van dit pack is.

clear() → None¶: Verwijder elk record/sub-pack uit dit pack en koppel ze los van hun ouderreferentie.

from_json(data: str) → None¶: Parseer een SenML/JSON-document en voeg de records samen in dit pack. Records die al bestaan (gematcht op naam) activeren SenmlRecord.do_actuate(); nieuwe records worden toegevoegd en de callback op pack-niveau wordt aangeroepen.

to_json() → str¶: Render het pack en zijn kinderen naar een SenML/JSON-string.

from_cbor(data: bytes) → None¶: Parseer een SenML/CBOR-bytestring en voeg de records samen in dit pack.

to_cbor() → bytes¶: Render het pack en zijn kinderen naar een SenML/CBOR-bytestring.

do_actuate(raw: dict, naming_map: dict, device: SenmlPack | None = None) → None¶: Interne helper die wordt aangeroepen tijdens het parseren van inkomende data wanneer geen bestaand record overeenkomt met een vermelding. Voegt een nieuw SenmlRecord toe aan device (of aan dit pack) en stuurt het door naar de callback.

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

Vertegenwoordigt een enkele meting binnen een SenmlPack.

name is de SenML-recordnaam (n).

De volgende keyword-argumenten worden geaccepteerd:

value – bool, int, float, str of bytearray. Andere typen veroorzaken Exception.
time – numerieke tijdstempel (t).
unit – een eenheidsstring, doorgaans een lid van SenmlUnits.
sum – numerieke geïntegreerde som (s).
update_time – maximale tijd voordat de sensor een nieuwe meting levert (ut).
callback – functie die wordt aangeroepen wanneer een inkomende payload dit record bijwerkt. Het ontvangt het SenmlRecord als enige argument.

SenmlRecord kan worden gebruikt als een context manager zodat het zichzelf bij het afsluiten uit zijn ouder-pack verwijdert.

name: str¶: Recordnaam (n).

value¶: De huidige waarde. Bij hertoewijzing wordt het type gecontroleerd; alleen bool, getallen, str en bytearray worden geaccepteerd. Om de gerenderde precisie van een float-waarde te bepalen, rond je af vóór de toewijzing, bijvoorbeeld record.value = round(x, 2).

unit: str | None¶: Eenheidsstring (u).

time: int | float | None¶: Tijdstempel die bij deze meting hoort (t).

update_time: int | float | None¶: Maximale tijd voordat de sensor een bijgewerkte meting levert (ut).

sum: int | float | None¶: Geïntegreerd som-veld (s).

actuate¶: De callback die bij de constructie is opgegeven. Kan tijdens runtime opnieuw worden toegewezen.

do_actuate(raw: dict, naming_map: dict) → None¶: Werk dit record bij vanuit een ruwe inkomende SenML-dictionary en roep, indien aanwezig, de actuate-callback aan.

class senml.SenmlBase¶: Gemeenschappelijke basisklasse die gedeeld wordt door SenmlPack en SenmlRecord. Het stelt geen eigen publieke API beschikbaar; het bestaat zodat SenmlPack.add() kan valideren dat een item tot de SenML-hiërarchie behoort.

class senml.SenmlUnits¶

Namespace-klasse waarvan de klasse-attributen de SenML-eenheidssymbolen zijn die zijn gedefinieerd door RFC 8428. Elk attribuut resolveert naar de stringcode van de eenheid, geschikt voor toewijzing aan SenmlRecord.unit of 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" – seconde.

SENML_UNIT_AMPERE: str¶: "A" – ampère.

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" – radiaal.

SENML_UNIT_STERADIAN: str¶: "sr" – steradiaal.

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" – graden 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" – vierkante meter.

SENML_UNIT_CUBIC_METER: str¶: "m3" – kubieke meter.

SENML_UNIT_LITER: str¶: "l" – liter.

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

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

SENML_UNIT_CUBIC_METER_PER_SECOND: str¶: "m3/s" – volumetrisch debiet.

SENML_UNIT_LITER_PER_SECOND: str¶: "l/s" – liter per seconde.

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

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

SENML_UNIT_BIT: str¶: "bit" – bit.

SENML_UNIT_BIT_PER_SECOND: str¶: "bit/s" – bit per seconde.

SENML_UNIT_DEGREES_LATITUDE: str¶: "lat" – graden breedtegraad.

SENML_UNIT_DEGREES_LONGITUDE: str¶: "lon" – graden lengtegraad.

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

SENML_UNIT_DECIBEL: str¶: "db" – decibel.

SENML_UNIT_DECIBEL_RELATIVE_TO_1_W: str¶: "dBW" – decibel ten opzichte van 1 W.

SENML_UNIT_BEL: str¶: "Bspl" – bel (geluidsdrukniveau).

SENML_UNIT_COUNTER: str¶: "count" – teller.

SENML_UNIT_RATIO: str¶: "//" – verhouding (dimensieloos).

SENML_UNIT_RELATIVE_HUMIDITY: str¶: "%RH" – relatieve luchtvochtigheid.

SENML_UNIT_PERCENTAGE_REMAINING_BATTERY_LEVEL: str¶: "%EL" – resterend batterijniveau als percentage.

SENML_UNIT_SECONDS_REMAINING_BATTERY_LEVEL: str¶: "EL" – resterend batterijniveau in seconden.

SENML_UNIT_EVENT_RATE_PER_SECOND: str¶: "1/s" – gebeurtenisfrequentie per seconde.

SENML_UNIT_EVENT_RATE_PER_MINUTE: str¶: "1/min" – gebeurtenisfrequentie per minuut.

SENML_UNIT_BPM: str¶: "beat/min" – slagen per minuut.

SENML_UNIT_BEATS: str¶: "beats" – slagen.

SENML_UNIT_SIEMENS_PER_METER: str¶: "S/m" – siemens per meter (elektrische geleidbaarheid).

senml — Sensor Markup Language¶

Klassen¶

`senml` — Sensor Markup Language¶