`senml` — Sensor Markup Language¶

Ce module implémente un petit encodeur/décodeur pour le Sensor Markup Language (SenML, RFC 8428). SenML est un type de média pour les mesures de capteurs et les paramètres de périphériques : chaque « pack » est une liste d”« enregistrements », où chaque enregistrement porte un nom, une unité, une valeur, un horodatage et une somme facultative.

L’implémentation prend en charge à la fois les représentations JSON et CBOR et permet d’imbriquer les packs afin qu’un unique pack racine puisse décrire une passerelle desservant plusieurs périphériques. Les charges utiles entrantes peuvent déclencher des fonctions de rappel d’actionneur sur des enregistrements existants.

Exemple d’utilisation

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

Classes¶

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

Représente un pack SenML – une collection d’instances SenmlRecord et éventuellement d’autres objets SenmlPack enfants. Lorsqu’un pack ne contient que des enregistrements, il représente un seul périphérique ; lorsqu’il contient d’autres packs, il agit comme une passerelle.

name est le nom de base SenML (bn) utilisé pour chaque enregistrement contenu dans ce pack.

callback est invoquée depuis from_json / from_cbor chaque fois qu’un enregistrement entrant nomme un capteur précédemment inconnu ; le nouveau SenmlRecord est passé comme premier argument et (pour les packs imbriqués) le pack périphérique d’origine est passé via device=.... Elle est généralement utilisée pour traiter les commandes d’actionneur.

Les instances SenmlPack sont itérables – l’itération produit chaque enregistrement dans l’ordre d’insertion – et peuvent être utilisées comme gestionnaire de contexte de sorte qu’à la sortie le pack se retire lui-même de son parent.

name: str¶: Le nom de base du pack (bn).

base_value: int | float | None¶: Valeur de base facultative (bv) ajoutée à la valeur numérique de chaque enregistrement lors de l’encodage et soustraite lors du décodage. L’attribution d’une valeur non numérique lève Exception.

base_time: int | float | None¶: Temps de base facultatif (bt) ajouté à l’horodatage de chaque enregistrement.

base_sum: int | float | None¶: Somme de base facultative (bs) ajoutée au champ somme de chaque enregistrement.

base_unit: str | None¶: Unité de base facultative (bu) – généralement une valeur issue de SenmlUnits.

actuate¶: La fonction de rappel fournie au moment de la construction. Peut être réassignée à l’exécution.

add(item: SenmlRecord | SenmlPack) → None¶: Ajoute item à ce pack. item doit être un SenmlRecord ou un autre SenmlPack et ne doit pas déjà appartenir à un parent différent ; sinon Exception est levée.

remove(item: SenmlRecord | SenmlPack) → None¶: Retire item de ce pack. Exception est levée si item n’est pas un enfant de ce pack.

clear() → None¶: Retire chaque enregistrement/sous-pack de ce pack et les détache de leur référence parente.

from_json(data: str) → None¶: Analyse un document SenML/JSON et fusionne les enregistrements dans ce pack. Les enregistrements qui existent déjà (appariés par nom) déclenchent SenmlRecord.do_actuate() ; les nouveaux enregistrements sont ajoutés et la fonction de rappel callback au niveau du pack est invoquée.

to_json() → str¶: Rend le pack et ses enfants sous la forme d’une chaîne SenML/JSON.

from_cbor(data: bytes) → None¶: Analyse une chaîne d’octets SenML/CBOR et fusionne les enregistrements dans ce pack.

to_cbor() → bytes¶: Rend le pack et ses enfants sous la forme d’une chaîne d’octets SenML/CBOR.

do_actuate(raw: dict, naming_map: dict, device: SenmlPack | None = None) → None¶: Assistant interne invoqué lors de l’analyse des données entrantes lorsqu’aucun enregistrement existant ne correspond à une entrée. Ajoute un nouveau SenmlRecord à device (ou à ce pack) et le transmet à callback.

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

Représente une mesure unique au sein d’un SenmlPack.

name est le nom d’enregistrement SenML (n).

Les arguments nommés suivants sont acceptés :

value – bool, int, float, str ou bytearray. Les autres types lèvent Exception.
time – horodatage numérique (t).
unit – une chaîne d’unité, généralement un membre de SenmlUnits.
sum – somme intégrée numérique (s).
update_time – temps maximal avant que le capteur fournisse une nouvelle lecture (ut).
callback – fonction invoquée lorsqu’une charge utile entrante met à jour cet enregistrement. Elle reçoit le SenmlRecord comme unique argument.

SenmlRecord peut être utilisé comme gestionnaire de contexte de sorte qu’à la sortie il se retire de son pack parent.

name: str¶: Nom de l’enregistrement (n).

value¶: La valeur actuelle. La réassignation vérifie le type ; seuls bool, les nombres, str et bytearray sont acceptés. Pour contrôler la précision de rendu d’une valeur flottante, arrondissez avant l’assignation, par exemple record.value = round(x, 2).

unit: str | None¶: Chaîne d’unité (u).

time: int | float | None¶: Horodatage associé à cette mesure (t).

update_time: int | float | None¶: Temps maximal avant que le capteur fournisse une lecture mise à jour (ut).

sum: int | float | None¶: Champ de somme intégrée (s).

actuate¶: La fonction de rappel fournie au moment de la construction. Peut être réassignée à l’exécution.

do_actuate(raw: dict, naming_map: dict) → None¶: Met à jour cet enregistrement à partir d’un dictionnaire SenML entrant brut et, le cas échéant, invoque la fonction de rappel d’actionnement.

class senml.SenmlBase¶: Classe de base commune partagée par SenmlPack et SenmlRecord. Elle n’expose aucune API publique propre ; elle existe afin que SenmlPack.add() puisse valider qu’un élément appartient à la hiérarchie SenML.

class senml.SenmlUnits¶

Classe d’espace de noms dont les attributs de classe sont les symboles d’unité SenML définis par la RFC 8428. Chaque attribut se résout en le code de chaîne de l’unité, adapté à l’assignation à SenmlRecord.unit ou SenmlPack.base_unit.

SENML_UNIT_METER: str¶: "m" – mètre.

SENML_UNIT_KILOGRAM: str¶: "kg" – kilogramme.

SENML_UNIT_GRAM: str¶: "g" – gramme.

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

SENML_UNIT_HERTZ: str¶: "Hz" – hertz.

SENML_UNIT_RADIAN: str¶: "rad" – radian.

SENML_UNIT_STERADIAN: str¶: "sr" – stéradian.

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" – degrés 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" – mètre carré.

SENML_UNIT_CUBIC_METER: str¶: "m3" – mètre cube.

SENML_UNIT_LITER: str¶: "l" – litre.

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

SENML_UNIT_ACCELERATION: str¶: "m/s2" – accélération.

SENML_UNIT_CUBIC_METER_PER_SECOND: str¶: "m3/s" – débit volumique.

SENML_UNIT_LITER_PER_SECOND: str¶: "l/s" – litre par seconde.

SENML_UNIT_WATT_PER_SQUARE_METER: str¶: "W/m2" – éclairement énergétique.

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

SENML_UNIT_BIT: str¶: "bit" – bit.

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

SENML_UNIT_DEGREES_LATITUDE: str¶: "lat" – degrés de latitude.

SENML_UNIT_DEGREES_LONGITUDE: str¶: "lon" – degrés de longitude.

SENML_UNIT_PH: str¶: "pH" – acidité (pH).

SENML_UNIT_DECIBEL: str¶: "db" – décibel.

SENML_UNIT_DECIBEL_RELATIVE_TO_1_W: str¶: "dBW" – décibel par rapport à 1 W.

SENML_UNIT_BEL: str¶: "Bspl" – bel (niveau de pression acoustique).

SENML_UNIT_COUNTER: str¶: "count" – compteur.

SENML_UNIT_RATIO: str¶: "//" – rapport (sans dimension).

SENML_UNIT_RELATIVE_HUMIDITY: str¶: "%RH" – humidité relative.

SENML_UNIT_PERCENTAGE_REMAINING_BATTERY_LEVEL: str¶: "%EL" – niveau de batterie restant en pourcentage.

SENML_UNIT_SECONDS_REMAINING_BATTERY_LEVEL: str¶: "EL" – niveau de batterie restant en secondes.

SENML_UNIT_EVENT_RATE_PER_SECOND: str¶: "1/s" – taux d’événements par seconde.

SENML_UNIT_EVENT_RATE_PER_MINUTE: str¶: "1/min" – taux d’événements par minute.

SENML_UNIT_BPM: str¶: "beat/min" – battements par minute.

SENML_UNIT_BEATS: str¶: "beats" – battements.

SENML_UNIT_SIEMENS_PER_METER: str¶: "S/m" – siemens par mètre (conductivité électrique).

senml — Sensor Markup Language¶

Classes¶

`senml` — Sensor Markup Language¶