`senml` — язык разметки датчиков (Sensor Markup Language)¶

Этот модуль реализует небольшой кодировщик/декодировщик для языка разметки датчиков (Sensor Markup Language, SenML, RFC 8428). SenML — это медиатип для измерений датчиков и параметров устройств: каждый «пакет» представляет собой список «записей», где каждая запись содержит имя, единицу измерения, значение, временную метку и необязательную сумму.

Реализация поддерживает представления как в формате JSON, так и в формате CBOR, и допускает вложенность пакетов, так что один корневой пакет может описывать шлюз, обслуживающий несколько устройств. Входящие данные могут вызывать функции обратного вызова исполнительных механизмов для существующих записей.

Пример использования:

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

Классы¶

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

Представляет пакет SenML — коллекцию экземпляров SenmlRecord и, при необходимости, других дочерних объектов SenmlPack. Когда пакет содержит только записи, он представляет одно устройство; когда он содержит другие пакеты, он действует как шлюз.

name — это базовое имя SenML (bn), используемое для каждой записи, содержащейся в этом пакете.

callback вызывается из from_json / from_cbor всякий раз, когда входящая запись именует ранее неизвестный датчик; новый объект SenmlRecord передаётся в качестве первого аргумента, а (для вложенных пакетов) исходный пакет устройства передаётся как device=.... Обычно используется для обработки команд исполнительным механизмам.

Экземпляры SenmlPack являются итерируемыми — итерация выдаёт каждую запись в порядке вставки — и могут использоваться как менеджер контекста, так что при выходе пакет удаляет себя из своего родителя.

name: str¶: Базовое имя пакета (bn).

base_value: int | float | None¶: Необязательное базовое значение (bv), добавляемое к числовому значению каждой записи при кодировании и вычитаемое при декодировании. Установка нечислового значения вызывает Exception.

base_time: int | float | None¶: Необязательное базовое время (bt), добавляемое к временной метке каждой записи.

base_sum: int | float | None¶: Необязательная базовая сумма (bs), добавляемая к полю суммы каждой записи.

base_unit: str | None¶: Необязательная базовая единица измерения (bu) — обычно значение из SenmlUnits.

actuate¶: Функция обратного вызова, переданная во время создания. Может быть переназначена во время выполнения.

add(item: SenmlRecord | SenmlPack) → None¶: Добавляет item в этот пакет. item должен быть объектом SenmlRecord или другим SenmlPack и не должен уже принадлежать другому родителю; в противном случае вызывается Exception.

remove(item: SenmlRecord | SenmlPack) → None¶: Удаляет item из этого пакета. Exception вызывается, если item не является дочерним элементом этого пакета.

clear() → None¶: Удаляет каждую запись/подпакет из этого пакета и отсоединяет их от ссылки на родителя.

from_json(data: str) → None¶: Разбирает документ SenML/JSON и объединяет записи в этот пакет. Уже существующие записи (сопоставленные по имени) вызывают SenmlRecord.do_actuate(); новые записи добавляются, и вызывается функция обратного вызова callback уровня пакета.

to_json() → str¶: Преобразует пакет и его дочерние элементы в строку SenML/JSON.

from_cbor(data: bytes) → None¶: Разбирает байтовую строку SenML/CBOR и объединяет записи в этот пакет.

to_cbor() → bytes¶: Преобразует пакет и его дочерние элементы в байтовую строку SenML/CBOR.

do_actuate(raw: dict, naming_map: dict, device: SenmlPack | None = None) → None¶: Внутренний вспомогательный метод, вызываемый при разборе входящих данных, когда ни одна существующая запись не соответствует элементу. Добавляет новый объект SenmlRecord в device (или в этот пакет) и передаёт его в callback.

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

Представляет одно измерение внутри SenmlPack.

name — это имя записи SenML (n).

Принимаются следующие именованные аргументы:

value — bool, int, float, str или bytearray. Другие типы вызывают Exception.
time — числовая временная метка (t).
unit — строка единицы измерения, обычно член SenmlUnits.
sum — числовая интегрированная сумма (s).
update_time — максимальное время до того, как датчик предоставит новое показание (ut).
callback — функция, вызываемая, когда входящие данные обновляют эту запись. Она получает объект SenmlRecord в качестве своего единственного аргумента.

SenmlRecord может использоваться как менеджер контекста, так что при выходе он удаляет себя из своего родительского пакета.

name: str¶: Имя записи (n).

value¶: Текущее значение. При переназначении проверяется тип; принимаются только bool, числа, str и bytearray. Чтобы управлять отображаемой точностью значения с плавающей точкой, округлите его перед присваиванием, например record.value = round(x, 2).

unit: str | None¶: Строка единицы измерения (u).

time: int | float | None¶: Временная метка, связанная с этим измерением (t).

update_time: int | float | None¶: Максимальное время до того, как датчик предоставит обновлённое показание (ut).

sum: int | float | None¶: Поле интегрированной суммы (s).

actuate¶: Функция обратного вызова, переданная во время создания. Может быть переназначена во время выполнения.

do_actuate(raw: dict, naming_map: dict) → None¶: Обновляет эту запись из необработанного входящего словаря SenML и, если присутствует, вызывает функцию обратного вызова исполнительного механизма.

class senml.SenmlBase¶: Общий базовый класс, разделяемый SenmlPack и SenmlRecord. Он не предоставляет собственного публичного API; он существует для того, чтобы SenmlPack.add() мог проверить, что элемент принадлежит иерархии SenML.

class senml.SenmlUnits¶

Класс-пространство имён, атрибуты класса которого являются символами единиц измерения SenML, определёнными в RFC 8428. Каждый атрибут разрешается в строковый код единицы измерения, подходящий для присваивания SenmlRecord.unit или SenmlPack.base_unit.

SENML_UNIT_METER: str¶: "m" — метр.

SENML_UNIT_KILOGRAM: str¶: "kg" — килограмм.

SENML_UNIT_GRAM: str¶: "g" — грамм.

SENML_UNIT_SECOND: str¶: "s" — секунда.

SENML_UNIT_AMPERE: str¶: "A" — ампер.

SENML_UNIT_KELVIN: str¶: "K" — кельвин.

SENML_UNIT_CANDELA: str¶: "cd" — кандела.

SENML_UNIT_MOLE: str¶: "mol" — моль.

SENML_UNIT_HERTZ: str¶: "Hz" — герц.

SENML_UNIT_RADIAN: str¶: "rad" — радиан.

SENML_UNIT_STERADIAN: str¶: "sr" — стерадиан.

SENML_UNIT_NEWTON: str¶: "N" — ньютон.

SENML_UNIT_PASCAL: str¶: "Pa" — паскаль.

SENML_UNIT_JOULE: str¶: "J" — джоуль.

SENML_UNIT_WATT: str¶: "W" — ватт.

SENML_UNIT_COULOMB: str¶: "C" — кулон.

SENML_UNIT_VOLT: str¶: "V" — вольт.

SENML_UNIT_FARAD: str¶: "F" — фарад.

SENML_UNIT_OHM: str¶: "Ohm" — ом.

SENML_UNIT_SIEMENS: str¶: "S" — сименс.

SENML_UNIT_WEBER: str¶: "Wb" — вебер.

SENML_UNIT_TESLA: str¶: "T" — тесла.

SENML_UNIT_HENRY: str¶: "H" — генри.

SENML_UNIT_DEGREES_CELSIUS: str¶: "Cel" — градусы Цельсия.

SENML_UNIT_LUMEN: str¶: "lm" — люмен.

SENML_UNIT_LUX: str¶: "lx" — люкс.

SENML_UNIT_BECQUEREL: str¶: "Bq" — беккерель.

SENML_UNIT_GRAY: str¶: "Gy" — грей.

SENML_UNIT_SIEVERT: str¶: "Sv" — зиверт.

SENML_UNIT_KATAL: str¶: "kat" — катал.

SENML_UNIT_SQUARE_METER: str¶: "m2" — квадратный метр.

SENML_UNIT_CUBIC_METER: str¶: "m3" — кубический метр.

SENML_UNIT_LITER: str¶: "l" — литр.

SENML_UNIT_VELOCITY: str¶: "m/s" — скорость.

SENML_UNIT_ACCELERATION: str¶: "m/s2" — ускорение.

SENML_UNIT_CUBIC_METER_PER_SECOND: str¶: "m3/s" — объёмный расход.

SENML_UNIT_LITER_PER_SECOND: str¶: "l/s" — литр в секунду.

SENML_UNIT_WATT_PER_SQUARE_METER: str¶: "W/m2" — облучённость.

SENML_UNIT_CANDELA_PER_SQUARE_METER: str¶: "cd/m2" — яркость.

SENML_UNIT_BIT: str¶: "bit" — бит.

SENML_UNIT_BIT_PER_SECOND: str¶: "bit/s" — бит в секунду.

SENML_UNIT_DEGREES_LATITUDE: str¶: "lat" — градусы широты.

SENML_UNIT_DEGREES_LONGITUDE: str¶: "lon" — градусы долготы.

SENML_UNIT_PH: str¶: "pH" — кислотность (pH).

SENML_UNIT_DECIBEL: str¶: "db" — децибел.

SENML_UNIT_DECIBEL_RELATIVE_TO_1_W: str¶: "dBW" — децибел относительно 1 Вт.

SENML_UNIT_BEL: str¶: "Bspl" — бел (уровень звукового давления).

SENML_UNIT_COUNTER: str¶: "count" — счётчик.

SENML_UNIT_RATIO: str¶: "//" — отношение (безразмерное).

SENML_UNIT_RELATIVE_HUMIDITY: str¶: "%RH" — относительная влажность.

SENML_UNIT_PERCENTAGE_REMAINING_BATTERY_LEVEL: str¶: "%EL" — оставшийся уровень заряда батареи в процентах.

SENML_UNIT_SECONDS_REMAINING_BATTERY_LEVEL: str¶: "EL" — оставшийся уровень заряда батареи в секундах.

SENML_UNIT_EVENT_RATE_PER_SECOND: str¶: "1/s" — частота событий в секунду.

SENML_UNIT_EVENT_RATE_PER_MINUTE: str¶: "1/min" — частота событий в минуту.

SENML_UNIT_BPM: str¶: "beat/min" — ударов в минуту.

SENML_UNIT_BEATS: str¶: "beats" — удары.

SENML_UNIT_SIEMENS_PER_METER: str¶: "S/m" — сименс на метр (электропроводность).

senml — язык разметки датчиков (Sensor Markup Language)¶

Классы¶

`senml` — язык разметки датчиков (Sensor Markup Language)¶