In the Web of Things (WoT), a Binding provides guidance for implementing a specific IoT protocol/platform by defining vocabulary terms that can be used in a TD and rules describing how WoT operations map to protocol interactions. This document proposes a binding for LoRaWAN, defining vocabulary and rules for describing interactions with LoRaWAN end devices and gateways via a LoRaWAN “network-facing interface” (typically a local Network Server, gateway bridge, or compatible service endpoint).

More specifically, this document defines a set of vocabulary terms that can be used inside a Thing Description or Thing Model document, and associated rules which allow description of WoT operations using LoRaWAN over the network. Additionally, relevant examples are provided to showcase different vocabulary terms and the associated behavior.

Introduction

LoRaWAN is commonly used in asynchronous telemetry scenarios: devices emit uplinks periodically or on change, while downlinks are scheduled (often with delivery constraints). This proposed binding therefore emphasizes observeproperty/subscribeevent for uplinks and invokeaction/writeproperty for downlinks. A TD using this LoRaWAN binding conforms if all of the following are true:

This document is a work in progress

URI format

This binding defines the URI scheme with following Augmented Backus-Naur Form (ABNF) [[RFC5234]]:

      "lorawan://" lorav:deviceEui "/" ("{lorav:appKey}/device") / ( lorav:gatewayModel "/routerconfig" )

A device URI looks like lorawan://{lorav:deviceEui}/{lorav:appKey}/device, whereas the gateway/router URI looks like lorawan://{lorav:deviceEui}/{lorav:gatewayModel}/routerconfig. The device URI includes the device EUI and application key, while the gateway/router URI includes the gateway model. Device and gateway identification are expressed in forms via vocabulary terms (Section 4.1), rather than being forced into the URI path.

LoRaWAN Vocabulary

This section defines vocabulary terms usable inside TDs.

URI terms

Vocabulary term Description Assignment Type
lorav:deviceEui LoRaWAN Device EUI (end device identifier) required string
lorav:gatewayModel LoRaWAN Gateway identifier (e.g., configured ID) required string
lorav:appKey Application key that is supplied via the security definitions mechanism required string

Form terms

End-device Specific Terms

The following terms are specific to forms describing LoRaWAN end device interactions (e.g., reading sensor data).

Vocabulary term Description Assignment Type
lorav:mostSignificantByte When true, it describes that the byte order of the data in the LoRaWAN message is the most significant byte first (i.e., Big-Endian). When false, it describes the least significant byte first (i.e., Little-Endian). optional boolean
lorav:bitmask Bitmask masking the returned device byte blob to extract the value optional hex string
lorav:multiplier Multiplier to multiply the returned device byte blob with to extract the true value optional float

Router Specific Terms

The following terms are specific to forms describing LoRaWAN router configuration parameters.

Vocabulary term Description Assignment Type
lorav:msgtype Must be “router_config” required string
lorav:NetID Network identifier required Array of integers
lorav:JoinEui Range of join EUIs accepted by the router required 2-dimensional Array of integers
lorav:region Region code required string
lorav:hwspec Chip type and version required string
lorav:freq_range Frequency range of the region required Array of integers
lorav:DRs Data rates array containing [spreading factor, bandwidth, and downlink flag] triples required 2-dimensional Array of integers
lorav:<chipName>_conf region-specific radio frequencies for a specific LoRaWAN transceiver chip required Array
lorav:nocca Disable Clear Channel Assessment flag required boolean
lorav:nodc Disable duty-cycle limitations flag required boolean
lorav:nodwell Disable dwell time limitations flag required boolean

Payload DataType

The PayloadDataType class within a LoRaWAN binding instance serves as value for the lorav:type property to specify the expected data types of payload content in LoRaWAN messages. It offers a set of terms taken from XML Schema [[XMLSCHEMA11-2-20120405]] to cover the most common data types used in LoRaWAN messages. Note that the PayloadDataType entity is designed for describing established conventions in the LoRaWAN ecosystem; future development might remove this functionality or add new terms. Currently, the PayloadDataType class contains the following data types:

Mappings

This section describes the strategies and default values to use protocol specific concepts within the WoT Interaction model.

Default mappings

Map WoT Interaction model verbs to default values if any

Operation Default Binding

Possible mappings

TODO: This section should describe other mappings that can be used by TD designers. It is meant to be informative but it provides guidelines for implementers.

Examples

{
  "@context": [
    "https://www.w3.org/2022/wot/td/v1.1"
  ],
  "id": "urn:dragino-lht-65n-e3",
  "securityDefinitions": {
    "apikey_sc": {
      "scheme": "apikey",
      "in": "uri",
      "name": "appKey"
    }
  },
  "security": [
    "apikey_sc"
  ],
  "@type": [
    "Thing"
  ],
  "name": "Dragino LHT65N-E3 A84041B98D5CB233",
  "base": "lorawan://A84041B98D5CB233/{appKey}/device",
  "title": "Dragino LHT65N-E3",
  "properties": {
    "batteryLevel": {
      "type": "number",
      "readOnly": true,
      "observable": true,
      "forms": [
        {
          "href": "A84041B98D5CB233/0?quantity=2",
          "lorav:type": "xsd:short",
          "lorav:mostSignificantByte": true,
          "lorav:bitmask": "0x3FFF",
          "lorav:multiplier": 0.001
        }
      ]
    },
    "temperature": {
      "type": "number",
      "readOnly": true,
      "observable": true,
      "forms": [
        {
          "href": "A84041B98D5CB233/2?quantity=2",
          "lorav:type": "xsd:short",
          "lorav:mostSignificantByte": true,
          "lorav:multiplier": 0.01
        }
      ]
    },
    "humidity": {
      "type": "number",
      "readOnly": true,
      "observable": true,
      "forms": [
        {
          "href": "A84041B98D5CB233/4?quantity=2",
          "lorav:type": "xsd:short",
          "lorav:mostSignificantByte": true,
          "lorav:multiplier": 0.1
        }
      ]
    },
    "extTemperature": {
      "type": "number",
      "readOnly": true,
      "observable": true,
      "forms": [
        {
          "href": "A84041B98D5CB233/7?quantity=2",
          "lorav:type": "xsd:short",
          "lorav:mostSignificantByte": true,
          "lorav:multiplier": 0.01
        }
      ]
    }
  }
}
        
{
  "@context": [
    "https://www.w3.org/2019/wot/td/v1"
  ],
  "id": "urn:dev:ops:lorawan:router:eu868:sx1301",
  "securityDefinitions": {
    "nosec_sc": {
      "scheme": "nosec"
    }
  },
  "security": [
    "nosec_sc"
  ],
  "@type": [
    "Thing"
  ],
  "name": "SX1301 EU868 2CCF67FFFEFB3C8F",
  "base": "lorawan://2CCF67FFFEFB3C8F/SX1301EU/routerconfig",
  "title": "LoRaWAN Router Config - EU868 SX1301",
  "properties": {
    "routerConfig": {
      "type": "object",
      "readOnly": true,
      "forms": [
        {
          "lorav:msgtype": "router_config",
          "lorav:NetID": [ 1 ],
          "lorav:JoinEui": [ [ 0, -1 ] ],
          "lorav:region": "EU863",
          "lorav:hwspec": "sx1301/1",
          "lorav:freq_range": [ 863000000, 870000000 ],
          "lorav:DRs": [
            [ 12, 125, 0 ],
            [ 11, 125, 0 ],
            [ 10, 125, 0 ],
            [ 9, 125, 0 ],
            [ 8, 125, 0 ],
            [ 7, 125, 0 ],
            [ 7, 250, 0 ]
          ],
          "lorav:sx1301_conf": [
            {
              "radio_0": {
                "enable": true,
                "freq": 867500000
              },
              "radio_1": {
                "enable": true,
                "freq": 868500000
              },
              "chan_FSK": {
                "enable": true,
                "radio": 1,
                "if": 300000
              },
              "chan_Lora_std": {
                "enable": true,
                "radio": 1,
                "if": -200000,
                "bandwidth": 250000,
                "spread_factor": 7
              },
              "chan_multiSF_0": {
                "enable": true,
                "radio": 1,
                "if": -400000
              },
              "chan_multiSF_1": {
                "enable": true,
                "radio": 1,
                "if": -200000
              },
              "chan_multiSF_2": {
                "enable": true,
                "radio": 1,
                "if": 0
              },
              "chan_multiSF_3": {
                "enable": true,
                "radio": 0,
                "if": -400000
              },
              "chan_multiSF_4": {
                "enable": true,
                "radio": 0,
                "if": -200000
              },
              "chan_multiSF_5": {
                "enable": true,
                "radio": 0,
                "if": 0
              },
              "chan_multiSF_6": {
                "enable": true,
                "radio": 0,
                "if": 200000
              },
              "chan_multiSF_7": {
                "enable": true,
                "radio": 0,
                "if": 400000
              }
            }
          ],
          "lorav:nocca": true,
          "lorav:nodc": true,
          "lorav:nodwell": true
        }
      ]
    }
  }
}
Deploys by Netlify