`senml` — Мова розмітки датчиків¶

Цей модуль реалізує невеликий кодувальник/декодувальник для Мови розмітки датчиків (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(); нові записи додаються, і викликається зворотний виклик на рівні пакета.

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 — Мова розмітки датчиків¶

Класи¶

`senml` — Мова розмітки датчиків¶