`senml` --- Sensor Markup Language¶

โมดูลนี้ใช้งานตัวเข้ารหัส/ถอดรหัสขนาดเล็กสำหรับ Sensor Markup Language (SenML, RFC 8428) SenML เป็น media-type สำหรับการวัดค่าจากเซนเซอร์และพารามิเตอร์ของอุปกรณ์ โดย "pack" แต่ละชุดประกอบด้วยรายการ "record" ซึ่งแต่ละ record บรรจุชื่อ หน่วย ค่า เวลาประทับ และผลรวมเสริม

การใช้งานรองรับทั้งรูปแบบ JSON และ CBOR และอนุญาตให้ซ้อน pack ได้ เพื่อให้ root pack เดียวสามารถอธิบาย gateway ที่รองรับหลายอุปกรณ์ เพย์โหลดขาเข้าสามารถเรียก actuator callback บน 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 อื่นจะทำหน้าที่เป็น gateway

name คือ SenML base name (bn) ที่ใช้กับทุก record ใน pack นี้

callback จะถูกเรียกจาก from_json / from_cbor เมื่อใดก็ตามที่ record ขาเข้ากล่าวถึงเซนเซอร์ที่ไม่รู้จักมาก่อน โดยจะส่ง SenmlRecord ใหม่เป็นอาร์กิวเมนต์แรก และ (สำหรับ pack ที่ซ้อนกัน) จะส่ง device pack ต้นทางเป็น device=... มักใช้เพื่อจัดการคำสั่ง actuator

อินสแตนซ์ SenmlPack สามารถวนซ้ำได้ -- การวนซ้ำจะให้แต่ละ record ตามลำดับที่แทรก -- และอาจใช้เป็น context manager เพื่อให้เมื่อออก pack จะลบตัวเองออกจาก parent

name: str¶: base name ของ pack (bn)

base_value: int | float | None¶: base value เสริม (bv) ที่จะบวกเข้ากับค่าตัวเลขของแต่ละ record เมื่อเข้ารหัส และลบออกเมื่อถอดรหัส การกำหนดค่าที่ไม่ใช่ตัวเลขจะ raise Exception

base_time: int | float | None¶: base time เสริม (bt) ที่จะบวกเข้ากับเวลาประทับของแต่ละ record

base_sum: int | float | None¶: base sum เสริม (bs) ที่จะบวกเข้ากับฟิลด์ผลรวมของแต่ละ record

base_unit: str | None¶: base unit เสริม (bu) -- โดยทั่วไปเป็นค่าจาก SenmlUnits

actuate¶: callback ที่ระบุในขณะสร้าง สามารถกำหนดค่าใหม่ได้ในขณะ runtime

add(item: SenmlRecord | SenmlPack) → None¶: เพิ่ม item เข้า pack นี้ item ต้องเป็น SenmlRecord หรือ SenmlPack อื่น และต้องไม่ได้เป็นของ parent อื่นอยู่แล้ว มิเช่นนั้นจะ raise Exception

remove(item: SenmlRecord | SenmlPack) → None¶: ลบ item ออกจาก pack นี้ จะ raise Exception หาก item ไม่ได้เป็น child ของ pack นี้

clear() → None¶: ลบทุก record/sub-pack ออกจาก pack นี้และตัดการอ้างอิง parent ของพวกมัน

from_json(data: str) → None¶: แยกวิเคราะห์เอกสาร SenML/JSON และรวม record เข้า pack นี้ Record ที่มีอยู่แล้ว (จับคู่ด้วยชื่อ) จะเรียก SenmlRecord.do_actuate() ส่วน record ใหม่จะถูกเพิ่มเข้าและเรียก callback ระดับ pack

to_json() → str¶: แสดงผล pack และ child ของมันเป็น SenML/JSON string

from_cbor(data: bytes) → None¶: แยกวิเคราะห์ byte string SenML/CBOR และรวม record เข้า pack นี้

to_cbor() → bytes¶: แสดงผล pack และ child ของมันเป็น byte string 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 ประเภทอื่นจะ raise Exception
time -- เวลาประทับตัวเลข (t)
unit -- string หน่วย โดยทั่วไปเป็น member ของ SenmlUnits
sum -- ผลรวมสะสมตัวเลข (s)
update_time -- เวลาสูงสุดก่อนที่เซนเซอร์จะให้ค่าใหม่ (ut)
callback -- ฟังก์ชันที่เรียกเมื่อเพย์โหลดขาเข้าอัปเดต record นี้ รับ SenmlRecord เป็นอาร์กิวเมนต์เดียว

SenmlRecord อาจใช้เป็น context manager เพื่อให้เมื่อออกจะลบตัวเองออกจาก parent pack

name: str¶: ชื่อ record (n)

value¶: ค่าปัจจุบัน การกำหนดค่าใหม่จะตรวจสอบประเภท รับเฉพาะ bool ตัวเลข str และ bytearray เท่านั้น หากต้องการควบคุมความแม่นยำในการแสดงผลของค่า float ให้ปัดเศษก่อนกำหนด เช่น record.value = round(x, 2)

unit: str | None¶: string หน่วย (u)

time: int | float | None¶: เวลาประทับที่เกี่ยวข้องกับการวัดค่านี้ (t)

update_time: int | float | None¶: เวลาสูงสุดก่อนที่เซนเซอร์จะให้ค่าที่อัปเดต (ut)

sum: int | float | None¶: ฟิลด์ผลรวมสะสม (s)

actuate¶: callback ที่ระบุในขณะสร้าง สามารถกำหนดค่าใหม่ได้ในขณะ runtime

do_actuate(raw: dict, naming_map: dict) → None¶: อัปเดต record นี้จาก SenML dictionary ขาเข้าดิบ และหากมี จะเรียก actuate callback

class senml.SenmlBase¶: คลาสฐานร่วมที่ SenmlPack และ SenmlRecord ใช้ร่วมกัน ไม่มี public API เป็นของตัวเอง มีอยู่เพื่อให้ SenmlPack.add() สามารถตรวจสอบว่า item อยู่ใน SenML hierarchy

class senml.SenmlUnits¶

คลาส namespace ที่มี class attribute เป็น SenML unit symbol ตามที่กำหนดใน RFC 8428 แต่ละ attribute จะแปลงเป็น string code ของหน่วยนั้น เหมาะสำหรับกำหนดให้กับ 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¶