`senml` --- 感測器標記語言 (Sensor Markup Language)¶

本模組為感測器標記語言 (Sensor Markup Language，SenML，RFC 8428) 實作了一個小型的編碼器／解碼器。SenML 是用於感測器量測值與裝置參數的媒體類型：每個「pack」是一份「record」清單，每筆 record 都帶有名稱、單位、數值、時間戳記以及選用的加總值。

此實作同時支援 JSON 與 CBOR 表示法，並允許 pack 巢狀，使得單一根 pack 可以描述一個對接多個裝置的閘道。輸入的負載資料可以驅動既有 record 上的致動器回呼函式。

範例用法:

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 pack——由若干 SenmlRecord 實例所組成的集合，並可選擇性地包含其他子 SenmlPack 物件。當一個 pack 僅包含 record 時，它代表單一裝置；當它包含其他 pack 時，則扮演閘道的角色。

name 是 SenML 基底名稱 (bn)，套用於此 pack 所包含的每一筆 record。

callback 會在 from_json / from_cbor 處理過程中，每當輸入的 record 指向先前未知的感測器時被呼叫；新的 SenmlRecord 會作為第一個引數傳入，而（對於巢狀 pack）來源裝置 pack 則以 device=... 傳入。它通常用於處理致動器指令。

SenmlPack 實例是可迭代的——迭代會依插入順序產生每一筆 record——並可作為情境管理器使用，使得結束時 pack 會將自己從其父項移除。

name: str¶: 此 pack 的基底名稱 (bn)。

base_value: int | float | None¶: 選用的基底值 (bv)，編碼時加到每筆 record 的數值上，解碼時則減去。設定非數值會引發 Exception。

base_time: int | float | None¶: 選用的基底時間 (bt)，加到每筆 record 的時間戳記上。

base_sum: int | float | None¶: 選用的基底加總值 (bs)，加到每筆 record 的加總欄位上。

base_unit: str | None¶: 選用的基底單位 (bu)——通常是 SenmlUnits 中的某個值。

actuate¶: 建構時提供的回呼函式。可於執行階段重新指派。

add(item: SenmlRecord | SenmlPack) → None¶: 將 item 附加到此 pack。item 必須是 SenmlRecord 或另一個 SenmlPack，且不得已屬於其他父項；否則會引發 Exception。

remove(item: SenmlRecord | SenmlPack) → None¶: 將 item 從此 pack 移除。若 item 並非此 pack 的子項，則會引發 Exception。

clear() → None¶: 從此 pack 移除所有 record／子 pack，並解除它們對父項的參照。

from_json(data: str) → None¶: 解析 SenML/JSON 文件並將其中的 record 合併到此 pack。已存在的 record（依名稱比對）會觸發 SenmlRecord.do_actuate()；新的 record 會被附加，並呼叫 pack 層級的 callback。

to_json() → str¶: 將此 pack 及其子項算繪為 SenML/JSON 字串。

from_cbor(data: bytes) → None¶: 解析 SenML/CBOR 位元組字串並將其中的 record 合併到此 pack。

to_cbor() → bytes¶: 將此 pack 及其子項算繪為 SenML/CBOR 位元組字串。

do_actuate(raw: dict, naming_map: dict, device: SenmlPack | None = None) → None¶: 在解析輸入資料時，若沒有既有 record 與某項目相符，便會呼叫的內部輔助函式。它會將新的 SenmlRecord 加入 device（或此 pack），並轉送給 callback。

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

代表 SenmlPack 中的單一量測值。

name 是 SenML record 名稱 (n)。

可接受下列關鍵字引數：

value —— bool、int、float、str 或 bytearray。其他類型會引發 Exception。
time —— 數值時間戳記 (t)。
unit —— 單位字串，通常是 SenmlUnits 的成員。
sum —— 數值積分加總 (s)。
update_time —— 感測器提供新讀數前的最長時間 (ut)。
callback —— 當輸入負載更新此 record 時呼叫的函式。它接收 SenmlRecord 作為其唯一引數。

SenmlRecord 可作為情境管理器使用，使得結束時它會將自己從其父 pack 移除。

name: str¶: Record 名稱 (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 字典更新此 record，並在存在時呼叫致動回呼函式。

class senml.SenmlBase¶: SenmlPack 與 SenmlRecord 共用的通用基底類別。它本身不公開任何公用 API；存在的目的是讓 SenmlPack.add() 能驗證某項目是否屬於 SenML 階層。

class senml.SenmlUnits¶

命名空間類別，其類別屬性即為 RFC 8428 所定義的 SenML 單位符號。每個屬性都解析為該單位的字串代碼，適合指派給 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 W 的分貝。

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