`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)#