`senml` — Sensor Markup Language¶

Este módulo implementa um pequeno codificador/decodificador para a Sensor Markup Language (SenML, RFC 8428). A SenML é um media-type para medições de sensores e parâmetros de dispositivos: cada “pack” é uma lista de “records”, onde cada record carrega um nome, unidade, valor, timestamp e uma soma opcional.

A implementação suporta tanto a representação JSON quanto a CBOR e permite que packs sejam aninhados, de modo que um único pack raiz possa descrever um gateway que serve de fachada para múltiplos dispositivos. Payloads de entrada podem acionar callbacks de atuadores em records existentes.

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

Classes¶

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

Representa um pack SenML – uma coleção de instâncias de SenmlRecord e, opcionalmente, outros objetos SenmlPack filhos. Quando um pack contém apenas records, ele representa um único dispositivo; quando contém outros packs, ele atua como um gateway.

name é o nome base SenML (bn) usado para todos os records contidos neste pack.

callback é invocado a partir de from_json / from_cbor sempre que um record de entrada nomeia um sensor previamente desconhecido; o novo SenmlRecord é passado como primeiro argumento e (para packs aninhados) o pack do dispositivo de origem é passado como device=.... Tipicamente é usado para tratar comandos de atuadores.

Instâncias de SenmlPack são iteráveis – a iteração produz cada record na ordem de inserção – e podem ser usadas como gerenciador de contexto, de modo que, na saída, o pack se remove de seu pai.

name: str¶: O nome base do pack (bn).

base_value: int | float | None¶: Valor base opcional (bv) adicionado ao valor numérico de cada record na codificação e subtraído na decodificação. Definir um valor não numérico levanta Exception.

base_time: int | float | None¶: Tempo base opcional (bt) adicionado ao timestamp de cada record.

base_sum: int | float | None¶: Soma base opcional (bs) adicionada ao campo de soma de cada record.

base_unit: str | None¶: Unidade base opcional (bu) – tipicamente um valor de SenmlUnits.

actuate¶: O callback fornecido no momento da construção. Pode ser reatribuído em tempo de execução.

add(item: SenmlRecord | SenmlPack) → None¶: Anexa item a este pack. item deve ser um SenmlRecord ou outro SenmlPack e não deve já pertencer a um pai diferente; caso contrário, Exception é levantada.

remove(item: SenmlRecord | SenmlPack) → None¶: Remove item deste pack. Exception é levantada se item não for filho deste pack.

clear() → None¶: Remove todos os records/sub-packs deste pack e os desvincula de sua referência ao pai.

from_json(data: str) → None¶: Analisa um documento SenML/JSON e mescla os records neste pack. Records que já existem (correspondidos pelo nome) acionam SenmlRecord.do_actuate(); novos records são anexados e o callback de nível de pack é invocado.

to_json() → str¶: Renderiza o pack e seus filhos como uma string SenML/JSON.

from_cbor(data: bytes) → None¶: Analisa uma byte string SenML/CBOR e mescla os records neste pack.

to_cbor() → bytes¶: Renderiza o pack e seus filhos como uma byte string SenML/CBOR.

do_actuate(raw: dict, naming_map: dict, device: SenmlPack | None = None) → None¶: Auxiliar interno invocado durante a análise de dados de entrada quando nenhum record existente corresponde a uma entrada. Adiciona um novo SenmlRecord a device (ou a este pack) e o encaminha para o callback.

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

Representa uma única medição dentro de um SenmlPack.

name é o nome do record SenML (n).

Os seguintes argumentos nomeados são aceitos:

value – bool, int, float, str ou bytearray. Outros tipos levantam Exception.
time – timestamp numérico (t).
unit – uma string de unidade, tipicamente um membro de SenmlUnits.
sum – soma integrada numérica (s).
update_time – tempo máximo antes que o sensor forneça uma nova leitura (ut).
callback – função invocada quando um payload de entrada atualiza este record. Ela recebe o SenmlRecord como seu único argumento.

SenmlRecord pode ser usado como gerenciador de contexto, de modo que, na saída, ele se remove de seu pack pai.

name: str¶: Nome do record (n).

value¶: O valor atual. A reatribuição verifica o tipo; apenas bool, números, str e bytearray são aceitos. Para controlar a precisão renderizada de um valor float, arredonde antes da atribuição, por exemplo record.value = round(x, 2).

unit: str | None¶: String de unidade (u).

time: int | float | None¶: Timestamp associado a esta medição (t).

update_time: int | float | None¶: Tempo máximo antes que o sensor forneça uma leitura atualizada (ut).

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

actuate¶: O callback fornecido no momento da construção. Pode ser reatribuído em tempo de execução.

do_actuate(raw: dict, naming_map: dict) → None¶: Atualiza este record a partir de um dicionário SenML de entrada bruto e, se presente, invoca o callback de atuação.

class senml.SenmlBase¶: Classe base comum compartilhada por SenmlPack e SenmlRecord. Ela não expõe nenhuma API pública própria; existe para que SenmlPack.add() possa validar que um item pertence à hierarquia SenML.

class senml.SenmlUnits¶

Classe de namespace cujos atributos de classe são os símbolos de unidade SenML definidos pela RFC 8428. Cada atributo resolve para o código de string da unidade, adequado para atribuição a SenmlRecord.unit ou SenmlPack.base_unit.

SENML_UNIT_METER: str¶: "m" – metro.

SENML_UNIT_KILOGRAM: str¶: "kg" – quilograma.

SENML_UNIT_GRAM: str¶: "g" – grama.

SENML_UNIT_SECOND: str¶: "s" – segundo.

SENML_UNIT_AMPERE: str¶: "A" – ampere.

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

SENML_UNIT_STERADIAN: str¶: "sr" – esferorradiano.

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" – graus Celsius.

SENML_UNIT_LUMEN: str¶: "lm" – lúmen.

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 quadrado.

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

SENML_UNIT_LITER: str¶: "l" – litro.

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

SENML_UNIT_ACCELERATION: str¶: "m/s2" – aceleração.

SENML_UNIT_CUBIC_METER_PER_SECOND: str¶: "m3/s" – vazão volumétrica.

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

SENML_UNIT_WATT_PER_SQUARE_METER: str¶: "W/m2" – irradiância.

SENML_UNIT_CANDELA_PER_SQUARE_METER: str¶: "cd/m2" – luminância.

SENML_UNIT_BIT: str¶: "bit" – bit.

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

SENML_UNIT_DEGREES_LATITUDE: str¶: "lat" – graus de latitude.

SENML_UNIT_DEGREES_LONGITUDE: str¶: "lon" – graus de longitude.

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

SENML_UNIT_DECIBEL: str¶: "db" – decibel.

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

SENML_UNIT_BEL: str¶: "Bspl" – bel (nível de pressão sonora).

SENML_UNIT_COUNTER: str¶: "count" – contador.

SENML_UNIT_RATIO: str¶: "//" – razão (adimensional).

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

SENML_UNIT_PERCENTAGE_REMAINING_BATTERY_LEVEL: str¶: "%EL" – nível de bateria restante em porcentagem.

SENML_UNIT_SECONDS_REMAINING_BATTERY_LEVEL: str¶: "EL" – nível de bateria restante em segundos.

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

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

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

SENML_UNIT_BEATS: str¶: "beats" – batimentos.

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

senml — Sensor Markup Language¶

Classes¶

`senml` — Sensor Markup Language¶