senml — Sensor Markup Language

Este módulo implementa um pequeno codificador/descodificador para o Sensor Markup Language (SenML, RFC 8428). O SenML é um tipo de media para medições de sensores e parâmetros de dispositivos: cada «pack» é uma lista de «records», onde cada record contém um nome, unidade, valor, timestamp e soma opcional.

A implementação suporta tanto as representações JSON como CBOR e permite que os packs sejam aninhados, de forma que um único pack raiz possa descrever uma gateway que suporta múltiplos dispositivos. Os payloads recebidos podem acionar callbacks de atuadores em records existentes.

Exemplo de utilização:

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 SenmlRecord e opcionalmente outros objetos SenmlPack filhos. Quando um pack contém apenas records, representa um único dispositivo; quando contém outros packs, funciona como uma gateway.

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

callback é invocado a partir de from_json / from_cbor sempre que um record recebido 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 utilizado para tratar comandos de atuadores.

As instâncias de SenmlPack são iteráveis – a iteração produz cada record por ordem de inserção – e podem ser utilizadas como gestores de contexto, de modo que ao sair, o pack se remove do 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 durante a codificação e subtraído na descodificação. Definir um valor não numérico lança 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 na construção. Pode ser reatribuído em tempo de execução.

add(item: SenmlRecord | SenmlPack) → None

Adiciona item a este pack. item deve ser um SenmlRecord ou outro SenmlPack e não deve pertencer já a um pai diferente; caso contrário, é lançada Exception.

remove(item: SenmlRecord | SenmlPack) → None

Remove item deste pack. É lançada Exception se item não for filho deste pack.

clear() → None

Remove todos os records/sub-packs deste pack e desvincula-os da referência ao pai.

from_json(data: str) → None

Analisa um documento SenML/JSON e integra os records neste pack. Os records que já existem (correspondidos pelo nome) acionam SenmlRecord.do_actuate(); os novos records são adicionados e o callback ao nível do pack é invocado.

to_json() → str

Converte o pack e os seus filhos numa string SenML/JSON.

from_cbor(data: bytes) → None

Analisa uma string de bytes SenML/CBOR e integra os records neste pack.

to_cbor() → bytes

Converte o pack e os seus filhos numa string de bytes SenML/CBOR.

do_actuate(raw: dict, naming_map: dict, device: SenmlPack | None = None) → None

Auxiliar interno invocado durante a análise de dados recebidos quando nenhum record existente corresponde a uma entrada. Adiciona um novo SenmlRecord a device (ou a este pack) e reencaminha-o 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).

São aceites os seguintes argumentos de palavra-chave:

• value – bool, int, float, str ou bytearray. Outros tipos lançam 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 de o sensor fornecer uma nova leitura (ut).

• callback – função invocada quando um payload recebido atualiza este record. Recebe o SenmlRecord como único argumento.

SenmlRecord pode ser utilizado como gestor de contexto, de modo que ao sair, remove-se do 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 aceites. Para controlar a precisão de renderização 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 de o sensor fornecer uma leitura atualizada (ut).

sum: int | float | None

Campo de soma integrada (s).

actuate

O callback fornecido na 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 recebido em bruto e, se presente, invoca o callback de atuação.

class senml.SenmlBase

Classe base comum partilhada por SenmlPack e SenmlRecord. 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 espaço de nomes cujos atributos de classe são os símbolos de unidade SenML definidos por 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" – mole.

SENML_UNIT_HERTZ: str

"Hz" – hertz.

SENML_UNIT_RADIAN: str

"rad" – radiano.

SENML_UNIT_STERADIAN: str

"sr" – esterradiano.

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" – caudal volumétrico.

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 relativamente 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

"//" – rácio (adimensional).

SENML_UNIT_RELATIVE_HUMIDITY: str

"%RH" – humidade relativa.

SENML_UNIT_PERCENTAGE_REMAINING_BATTERY_LEVEL: str

"%EL" – nível de bateria restante em percentagem.

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