`senml` — שפת סימון לחיישנים (Sensor Markup Language)¶

מודול זה מממש מקודד/מפענח קטן עבור Sensor Markup Language (SenML, RFC 8428). SenML הוא סוג מדיה למדידות חיישנים ולפרמטרים של התקנים: כל ”pack“ הוא רשימה של ”records“, כאשר כל record נושא שם, יחידה, ערך, חותמת זמן וסכום אופציונלי.

המימוש תומך הן בייצוג JSON והן בייצוג CBOR, ומאפשר לקנן packs כך ש-pack שורש יחיד יכול לתאר שער (gateway) שמייצג מספר התקנים. מטענים נכנסים יכולים להפעיל פונקציות callback של מפעילים על records קיימים.

דוגמה לשימוש:

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 מכיל records בלבד הוא מייצג התקן יחיד; כאשר הוא מכיל packs אחרים הוא משמש כשער (gateway).

name הוא שם הבסיס של SenML (bn) שבו משתמש כל record שמכיל pack זה.

callback מופעלת מתוך from_json / from_cbor בכל פעם שרשומה נכנסת מציינת חיישן שלא היה ידוע קודם; ה-SenmlRecord החדש מועבר כארגומנט הראשון, ו(עבור packs מקוננים) ה-pack של ההתקן המקורי מועבר כ-device=.... בדרך כלל היא משמשת לטיפול בפקודות למפעילים.

מופעי SenmlPack ניתנים לאיטרציה – האיטרציה מחזירה כל record בסדר ההכנסה – וניתן להשתמש בהם כמנהל הקשר (context manager) כך שביציאה ה-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¶: ה-callback שסופקה בזמן הבנייה. ניתן להקצותה מחדש בזמן ריצה.

add(item: SenmlRecord | SenmlPack) → None¶: מצרף את item ל-pack זה. item חייב להיות SenmlRecord או SenmlPack אחר ואסור שכבר ישתייך להורה אחר; אחרת מועלה Exception.

remove(item: SenmlRecord | SenmlPack) → None¶: מסיר את item מ-pack זה. Exception מועלה אם item אינו בן של pack זה.

clear() → None¶: מסיר כל record/sub-pack מ-pack זה ומנתק אותם מהפניית ההורה שלהם.

from_json(data: str) → None¶: מנתח מסמך SenML/JSON וממזג את ה-records ל-pack זה. records שכבר קיימים (תואמים לפי שם) מפעילים את SenmlRecord.do_actuate(); records חדשים מצורפים וה-callback ברמת ה-pack מופעלת.

to_json() → str¶: מעבד את ה-pack ואת בניו למחרוזת SenML/JSON.

from_cbor(data: bytes) → None¶: מנתח מחרוזת בייטים של SenML/CBOR וממזג את ה-records ל-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 הוא שם ה-record של SenML (n).

הארגומנטים הבאים, מסוג מילת מפתח, מתקבלים:

value – bool, int, float, str או bytearray. סוגים אחרים מעלים Exception.
time – חותמת זמן מספרית (t).
unit – מחרוזת יחידה, בדרך כלל חבר ב-SenmlUnits.
sum – סכום משולב מספרי (s).
update_time – הזמן המרבי לפני שהחיישן יספק קריאה חדשה (ut).
callback – פונקציה המופעלת כאשר מטען נכנס מעדכן record זה. היא מקבלת את ה-SenmlRecord כארגומנט היחיד שלה.

ניתן להשתמש ב-SenmlRecord כמנהל הקשר (context manager) כך שביציאה הוא מסיר את עצמו מה-pack ההורה שלו.

name: str¶: שם ה-record (n).

value¶: הערך הנוכחי. הקצאה מחדש בודקת את הסוג; מתקבלים רק bool, מספרים, str ו-bytearray. כדי לשלוט בדיוק המעובד של ערך float, עגלו לפני ההקצאה, למשל 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¶: ה-callback שסופקה בזמן הבנייה. ניתן להקצותה מחדש בזמן ריצה.

do_actuate(raw: dict, naming_map: dict) → None¶: מעדכן record זה ממילון SenML גולמי נכנס, ואם קיימת, מפעיל את פונקציית ה-actuate callback.

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" – בהירות (luminance).

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