`senml` --- لغة ترميز المستشعرات (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. لا يكشف عن أي واجهة برمجية عامة خاصة به؛ وهو موجود حتى تتمكن 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 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)¶