`senml` — Sensor Markup Language¶

Este módulo implementa un pequeño codificador/decodificador para el Sensor Markup Language (SenML, RFC 8428). SenML es un tipo de medio para mediciones de sensores y parámetros de dispositivos: cada «pack» es una lista de «records», donde cada record lleva un nombre, una unidad, un valor, una marca de tiempo y una suma opcional.

La implementación admite tanto la representación JSON como la CBOR y permite anidar los packs, de modo que un único pack raíz pueda describir una pasarela que actúe como frente de múltiples dispositivos. Las cargas útiles entrantes pueden activar funciones de retorno (callbacks) de actuadores sobre records existentes.

Ejemplo de uso:

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

Clases¶

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

Representa un pack SenML, es decir, una colección de instancias SenmlRecord y, opcionalmente, otros objetos SenmlPack hijos. Cuando un pack solo contiene records, representa un único dispositivo; cuando contiene otros packs, actúa como pasarela.

name es el nombre base de SenML (bn) usado para cada record contenido en este pack.

callback se invoca desde from_json / from_cbor cada vez que un record entrante nombra un sensor previamente desconocido; el nuevo SenmlRecord se pasa como primer argumento y (para packs anidados) el pack del dispositivo de origen se pasa como device=.... Normalmente se usa para gestionar comandos de actuadores.

Las instancias de SenmlPack son iterables – la iteración produce cada record en orden de inserción – y pueden usarse como gestor de contexto, de modo que al salir el pack se elimina a sí mismo de su padre.

name: str¶: El nombre base del pack (bn).

base_value: int | float | None¶: Valor base opcional (bv) que se suma al valor numérico de cada record al codificar y se resta al decodificar. Asignar un valor no numérico genera Exception.

base_time: int | float | None¶: Tiempo base opcional (bt) que se suma a la marca de tiempo de cada record.

base_sum: int | float | None¶: Suma base opcional (bs) que se suma al campo de suma de cada record.

base_unit: str | None¶: Unidad base opcional (bu) – normalmente un valor de SenmlUnits.

actuate¶: La función de retorno (callback) proporcionada en el momento de la construcción. Puede reasignarse en tiempo de ejecución.

add(item: SenmlRecord | SenmlPack) → None¶: Añade item a este pack. item debe ser un SenmlRecord u otro SenmlPack y no debe pertenecer ya a un padre distinto; de lo contrario se genera Exception.

remove(item: SenmlRecord | SenmlPack) → None¶: Elimina item de este pack. Se genera Exception si item no es hijo de este pack.

clear() → None¶: Elimina todos los records/sub-packs de este pack y los desvincula de su referencia al padre.

from_json(data: str) → None¶: Analiza un documento SenML/JSON y combina los records en este pack. Los records que ya existen (emparejados por nombre) activan SenmlRecord.do_actuate(); los nuevos records se añaden y se invoca el callback a nivel de pack.

to_json() → str¶: Renderiza el pack y sus hijos a una cadena SenML/JSON.

from_cbor(data: bytes) → None¶: Analiza una cadena de bytes SenML/CBOR y combina los records en este pack.

to_cbor() → bytes¶: Renderiza el pack y sus hijos a una cadena de bytes SenML/CBOR.

do_actuate(raw: dict, naming_map: dict, device: SenmlPack | None = None) → None¶: Función auxiliar interna que se invoca al analizar datos entrantes cuando ningún record existente coincide con una entrada. Añade un nuevo SenmlRecord a device (o a este pack) y lo reenvía al callback.

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

Representa una sola medición dentro de un SenmlPack.

name es el nombre del record SenML (n).

Se aceptan los siguientes argumentos por palabra clave:

value – bool, int, float, str o bytearray. Otros tipos generan Exception.
time – marca de tiempo numérica (t).
unit – una cadena de unidad, normalmente un miembro de SenmlUnits.
sum – suma integrada numérica (s).
update_time – tiempo máximo antes de que el sensor proporcione una lectura nueva (ut).
callback – función que se invoca cuando una carga útil entrante actualiza este record. Recibe el SenmlRecord como único argumento.

SenmlRecord puede usarse como gestor de contexto, de modo que al salir se elimina a sí mismo de su pack padre.

name: str¶: Nombre del record (n).

value¶: El valor actual. La reasignación comprueba el tipo; solo se aceptan bool, números, str y bytearray. Para controlar la precisión renderizada de un valor de tipo float, redondéalo antes de la asignación, p. ej. record.value = round(x, 2).

unit: str | None¶: Cadena de unidad (u).

time: int | float | None¶: Marca de tiempo asociada a esta medición (t).

update_time: int | float | None¶: Tiempo máximo antes de que el sensor proporcione una lectura actualizada (ut).

sum: int | float | None¶: Campo de suma integrada (s).

actuate¶: La función de retorno (callback) proporcionada en el momento de la construcción. Puede reasignarse en tiempo de ejecución.

do_actuate(raw: dict, naming_map: dict) → None¶: Actualiza este record a partir de un diccionario SenML entrante en bruto y, si está presente, invoca la función de retorno de actuación.

class senml.SenmlBase¶: Clase base común compartida por SenmlPack y SenmlRecord. No expone ninguna API pública propia; existe para que SenmlPack.add() pueda validar que un elemento pertenece a la jerarquía de SenML.

class senml.SenmlUnits¶

Clase de espacio de nombres cuyos atributos de clase son los símbolos de unidad SenML definidos por RFC 8428. Cada atributo se resuelve al código de cadena de la unidad, adecuado para asignarlo a SenmlRecord.unit o a SenmlPack.base_unit.

SENML_UNIT_METER: str¶: "m" – metro.

SENML_UNIT_KILOGRAM: str¶: "kg" – kilogramo.

SENML_UNIT_GRAM: str¶: "g" – gramo.

SENML_UNIT_SECOND: str¶: "s" – segundo.

SENML_UNIT_AMPERE: str¶: "A" – amperio.

SENML_UNIT_KELVIN: str¶: "K" – kelvin.

SENML_UNIT_CANDELA: str¶: "cd" – candela.

SENML_UNIT_MOLE: str¶: "mol" – mol.

SENML_UNIT_HERTZ: str¶: "Hz" – hercio.

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

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

SENML_UNIT_NEWTON: str¶: "N" – newton.

SENML_UNIT_PASCAL: str¶: "Pa" – pascal.

SENML_UNIT_JOULE: str¶: "J" – julio.

SENML_UNIT_WATT: str¶: "W" – vatio.

SENML_UNIT_COULOMB: str¶: "C" – culombio.

SENML_UNIT_VOLT: str¶: "V" – voltio.

SENML_UNIT_FARAD: str¶: "F" – faradio.

SENML_UNIT_OHM: str¶: "Ohm" – ohmio.

SENML_UNIT_SIEMENS: str¶: "S" – siemens.

SENML_UNIT_WEBER: str¶: "Wb" – weber.

SENML_UNIT_TESLA: str¶: "T" – tesla.

SENML_UNIT_HENRY: str¶: "H" – henrio.

SENML_UNIT_DEGREES_CELSIUS: str¶: "Cel" – grados 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" – metro cuadrado.

SENML_UNIT_CUBIC_METER: str¶: "m3" – metro cúbico.

SENML_UNIT_LITER: str¶: "l" – litro.

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

SENML_UNIT_ACCELERATION: str¶: "m/s2" – aceleración.

SENML_UNIT_CUBIC_METER_PER_SECOND: str¶: "m3/s" – caudal volumétrico.

SENML_UNIT_LITER_PER_SECOND: str¶: "l/s" – litro por segundo.

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

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

SENML_UNIT_BIT: str¶: "bit" – bit.

SENML_UNIT_BIT_PER_SECOND: str¶: "bit/s" – bit por segundo.

SENML_UNIT_DEGREES_LATITUDE: str¶: "lat" – grados de latitud.

SENML_UNIT_DEGREES_LONGITUDE: str¶: "lon" – grados de longitud.

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

SENML_UNIT_DECIBEL: str¶: "db" – decibelio.

SENML_UNIT_DECIBEL_RELATIVE_TO_1_W: str¶: "dBW" – decibelio relativo a 1 W.

SENML_UNIT_BEL: str¶: "Bspl" – belio (nivel de presión sonora).

SENML_UNIT_COUNTER: str¶: "count" – contador.

SENML_UNIT_RATIO: str¶: "//" – proporción (adimensional).

SENML_UNIT_RELATIVE_HUMIDITY: str¶: "%RH" – humedad relativa.

SENML_UNIT_PERCENTAGE_REMAINING_BATTERY_LEVEL: str¶: "%EL" – nivel de batería restante en forma de porcentaje.

SENML_UNIT_SECONDS_REMAINING_BATTERY_LEVEL: str¶: "EL" – nivel de batería restante en segundos.

SENML_UNIT_EVENT_RATE_PER_SECOND: str¶: "1/s" – tasa de eventos por segundo.

SENML_UNIT_EVENT_RATE_PER_MINUTE: str¶: "1/min" – tasa de eventos por minuto.

SENML_UNIT_BPM: str¶: "beat/min" – latidos por minuto.

SENML_UNIT_BEATS: str¶: "beats" – latidos.

SENML_UNIT_SIEMENS_PER_METER: str¶: "S/m" – siemens por metro (conductividad eléctrica).

senml — Sensor Markup Language¶

Clases¶

`senml` — Sensor Markup Language¶