`senml` — Sensor Markup Language¶

Tämä moduuli toteuttaa pienen kooderin/dekooderin Sensor Markup Languagelle (SenML, RFC 8428). SenML on mediatyyppi sensorimittauksille ja laiteparametreille: jokainen ”pack” on lista ”recordeja”, joista jokainen sisältää nimen, yksikön, arvon, aikaleiman ja valinnaisen summan.

Toteutus tukee sekä JSON- että CBOR-esitysmuotoja ja sallii pakkien sisäkkäisyyden, jolloin yksittäinen juuripack voi kuvata yhdyskäytävää, joka toimii useiden laitteiden edustana. Saapuvat hyötykuormat voivat laukaista toimilaitteen takaisinkutsuja olemassa oleville recordeille.

Esimerkki käytöstä:

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

Luokat¶

class senml.SenmlPack(name: str, callback=None)¶

Edustaa SenML-packia – kokoelmaa SenmlRecord-ilmentymiä ja valinnaisesti muita lapsi-SenmlPack-objekteja. Kun pack sisältää vain recordeja, se edustaa yksittäistä laitetta; kun se sisältää muita packeja, se toimii yhdyskäytävänä.

name on SenML-perusnimi (bn), jota käytetään jokaiselle tähän packiin sisältyvälle recordille.

callback kutsutaan funktioista from_json / from_cbor aina, kun saapuva record nimeää aiemmin tuntemattoman sensorin; uusi SenmlRecord välitetään ensimmäisenä argumenttina ja (sisäkkäisille packeille) alkuperäinen laitepack välitetään muodossa device=.... Sitä käytetään tyypillisesti toimilaitekomentojen käsittelyyn.

SenmlPack-ilmentymät ovat iteroitavissa – iterointi tuottaa kunkin recordin lisäysjärjestyksessä – ja niitä voidaan käyttää kontekstinhallintana siten, että poistuttaessa pack irrottaa itsensä emostaan.

name: str¶: Packin perusnimi (bn).

base_value: int | float | None¶: Valinnainen perusarvo (bv), joka lisätään kunkin recordin numeeriseen arvoon koodattaessa ja vähennetään dekoodattaessa. Ei-numeerisen arvon asettaminen nostaa Exception-poikkeuksen.

base_time: int | float | None¶: Valinnainen perusaika (bt), joka lisätään kunkin recordin aikaleimaan.

base_sum: int | float | None¶: Valinnainen perussumma (bs), joka lisätään kunkin recordin summakenttään.

base_unit: str | None¶: Valinnainen perusyksikkö (bu) – tyypillisesti arvo luokasta SenmlUnits.

actuate¶: Luonnin yhteydessä annettu takaisinkutsu. Voidaan asettaa uudelleen ajon aikana.

add(item: SenmlRecord | SenmlPack) → None¶: Lisää item tähän packiin. item on oltava SenmlRecord tai toinen SenmlPack, eikä se saa jo kuulua toiseen emoon; muutoin nostetaan Exception.

remove(item: SenmlRecord | SenmlPack) → None¶: Poista item tästä packista. Exception nostetaan, jos item ei ole tämän packin lapsi.

clear() → None¶: Poista jokainen record/alipack tästä packista ja irrota ne emoviittauksestaan.

from_json(data: str) → None¶: Jäsennä SenML/JSON-dokumentti ja yhdistä recordit tähän packiin. Recordit, jotka ovat jo olemassa (täsmättyinä nimen perusteella), laukaisevat SenmlRecord.do_actuate()-metodin; uudet recordit lisätään ja pack-tason callback kutsutaan.

to_json() → str¶: Renderöi pack ja sen lapset SenML/JSON-merkkijonoksi.

from_cbor(data: bytes) → None¶: Jäsennä SenML/CBOR-tavumerkkijono ja yhdistä recordit tähän packiin.

to_cbor() → bytes¶: Renderöi pack ja sen lapset SenML/CBOR-tavumerkkijonoksi.

do_actuate(raw: dict, naming_map: dict, device: SenmlPack | None = None) → None¶: Sisäinen apufunktio, joka kutsutaan saapuvaa dataa jäsennettäessä, kun mikään olemassa oleva record ei täsmää merkintään. Lisää uuden SenmlRecord-ilmentymän kohteeseen device (tai tähän packiin) ja välittää sen edelleen callback-funktiolle.

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

Edustaa yksittäistä mittausta SenmlPack-objektin sisällä.

name on SenML-recordin nimi (n).

Seuraavat avainsana-argumentit hyväksytään:

value – bool, int, float, str tai bytearray. Muut tyypit nostavat Exception-poikkeuksen.
time – numeerinen aikaleima (t).
unit – yksikkömerkkijono, tyypillisesti luokan SenmlUnits jäsen.
sum – numeerinen integroitu summa (s).
update_time – enimmäisaika, ennen kuin sensori tarjoaa tuoreen lukeman (ut).
callback – funktio, joka kutsutaan, kun saapuva hyötykuorma päivittää tämän recordin. Se vastaanottaa SenmlRecord-objektin ainoana argumenttinaan.

SenmlRecord-objektia voidaan käyttää kontekstinhallintana siten, että poistuttaessa se irrottaa itsensä emopackistaan.

name: str¶: Recordin nimi (n).

value¶: Nykyinen arvo. Uudelleenasettaminen tarkistaa tyypin; vain bool, numerot, str ja bytearray hyväksytään. Liukuluvun renderöidyn tarkkuuden hallitsemiseksi pyöristä ennen asettamista, esim. record.value = round(x, 2).

unit: str | None¶: Yksikkömerkkijono (u).

time: int | float | None¶: Tähän mittaukseen liittyvä aikaleima (t).

update_time: int | float | None¶: Enimmäisaika, ennen kuin sensori tarjoaa päivitetyn lukeman (ut).

sum: int | float | None¶: Integroitu summakenttä (s).

actuate¶: Luonnin yhteydessä annettu takaisinkutsu. Voidaan asettaa uudelleen ajon aikana.

do_actuate(raw: dict, naming_map: dict) → None¶: Päivitä tämä record raa’asta saapuvasta SenML-sanakirjasta ja, jos läsnä, kutsu toimilaitteen takaisinkutsua.

class senml.SenmlBase¶: Yhteinen kantaluokka, jonka SenmlPack ja SenmlRecord jakavat. Se ei paljasta omaa julkista APIa; se on olemassa, jotta SenmlPack.add() voi varmistaa, että kohde kuuluu SenML-hierarkiaan.

class senml.SenmlUnits¶

Nimiavaruusluokka, jonka luokka-attribuutit ovat RFC 8428 -määrittelemiä SenML-yksikkösymboleja. Jokainen attribuutti resolvoituu yksikön merkkijonokoodiksi, joka soveltuu asetettavaksi attribuutteihin SenmlRecord.unit tai SenmlPack.base_unit.

SENML_UNIT_METER: str¶: "m" – metri.

SENML_UNIT_KILOGRAM: str¶: "kg" – kilogramma.

SENML_UNIT_GRAM: str¶: "g" – gramma.

SENML_UNIT_SECOND: str¶: "s" – sekunti.

SENML_UNIT_AMPERE: str¶: "A" – ampeeri.

SENML_UNIT_KELVIN: str¶: "K" – kelvin.

SENML_UNIT_CANDELA: str¶: "cd" – kandela.

SENML_UNIT_MOLE: str¶: "mol" – mooli.

SENML_UNIT_HERTZ: str¶: "Hz" – hertsi.

SENML_UNIT_RADIAN: str¶: "rad" – radiaani.

SENML_UNIT_STERADIAN: str¶: "sr" – steradiaani.

SENML_UNIT_NEWTON: str¶: "N" – newton.

SENML_UNIT_PASCAL: str¶: "Pa" – pascal.

SENML_UNIT_JOULE: str¶: "J" – joule.

SENML_UNIT_WATT: str¶: "W" – watti.

SENML_UNIT_COULOMB: str¶: "C" – coulombi.

SENML_UNIT_VOLT: str¶: "V" – voltti.

SENML_UNIT_FARAD: str¶: "F" – faradi.

SENML_UNIT_OHM: str¶: "Ohm" – ohmi.

SENML_UNIT_SIEMENS: str¶: "S" – siemens.

SENML_UNIT_WEBER: str¶: "Wb" – weber.

SENML_UNIT_TESLA: str¶: "T" – tesla.

SENML_UNIT_HENRY: str¶: "H" – henry.

SENML_UNIT_DEGREES_CELSIUS: str¶: "Cel" – celsiusastetta.

SENML_UNIT_LUMEN: str¶: "lm" – luumen.

SENML_UNIT_LUX: str¶: "lx" – luksi.

SENML_UNIT_BECQUEREL: str¶: "Bq" – becquerel.

SENML_UNIT_GRAY: str¶: "Gy" – gray.

SENML_UNIT_SIEVERT: str¶: "Sv" – sievert.

SENML_UNIT_KATAL: str¶: "kat" – katal.

SENML_UNIT_SQUARE_METER: str¶: "m2" – neliömetri.

SENML_UNIT_CUBIC_METER: str¶: "m3" – kuutiometri.

SENML_UNIT_LITER: str¶: "l" – litra.

SENML_UNIT_VELOCITY: str¶: "m/s" – nopeus.

SENML_UNIT_ACCELERATION: str¶: "m/s2" – kiihtyvyys.

SENML_UNIT_CUBIC_METER_PER_SECOND: str¶: "m3/s" – tilavuusvirtaus.

SENML_UNIT_LITER_PER_SECOND: str¶: "l/s" – litraa sekunnissa.

SENML_UNIT_WATT_PER_SQUARE_METER: str¶: "W/m2" – säteilyteho.

SENML_UNIT_CANDELA_PER_SQUARE_METER: str¶: "cd/m2" – luminanssi.

SENML_UNIT_BIT: str¶: "bit" – bitti.

SENML_UNIT_BIT_PER_SECOND: str¶: "bit/s" – bittiä sekunnissa.

SENML_UNIT_DEGREES_LATITUDE: str¶: "lat" – leveysasteet.

SENML_UNIT_DEGREES_LONGITUDE: str¶: "lon" – pituusasteet.

SENML_UNIT_PH: str¶: "pH" – happamuus (pH).

SENML_UNIT_DECIBEL: str¶: "db" – desibeli.

SENML_UNIT_DECIBEL_RELATIVE_TO_1_W: str¶: "dBW" – desibeli suhteessa 1 W:iin.

SENML_UNIT_BEL: str¶: "Bspl" – bel (äänenpainetaso).

SENML_UNIT_COUNTER: str¶: "count" – laskuri.

SENML_UNIT_RATIO: str¶: "//" – suhde (dimensioton).

SENML_UNIT_RELATIVE_HUMIDITY: str¶: "%RH" – suhteellinen kosteus.

SENML_UNIT_PERCENTAGE_REMAINING_BATTERY_LEVEL: str¶: "%EL" – jäljellä oleva akkutaso prosentteina.

SENML_UNIT_SECONDS_REMAINING_BATTERY_LEVEL: str¶: "EL" – jäljellä oleva akkutaso sekunteina.

SENML_UNIT_EVENT_RATE_PER_SECOND: str¶: "1/s" – tapahtumataajuus sekunnissa.

SENML_UNIT_EVENT_RATE_PER_MINUTE: str¶: "1/min" – tapahtumataajuus minuutissa.

SENML_UNIT_BPM: str¶: "beat/min" – lyöntiä minuutissa.

SENML_UNIT_BEATS: str¶: "beats" – lyönnit.

SENML_UNIT_SIEMENS_PER_METER: str¶: "S/m" – siemensiä metriä kohti (sähkönjohtavuus).

senml — Sensor Markup Language¶

Luokat¶

`senml` — Sensor Markup Language¶