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 to describe 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:

• It includes the LoRaWAN binding context in @context (Section 4), and
• Any form using LoRaWAN terms follows the constraints in this document (Sections 3–5), and
• It validates against the JSON Schema in Appendix (Section A)

This document is a work in progress

URI format

This binding defines these URI schemes:

• lorawan://{deviceEui}/{appKey}/device A LoRaWAN device endpoint.
• lorawan://{deviceEui}/{gatewayModel}/routerconfig A LoRaWAN router endpoint.

Device and gateway identification are expressed in forms via vocabulary terms (Section 4.1), rather than being forced into the URL path.

LoRaWAN Vocabulary

This section defines vocabulary terms usable inside TDs.

Payload DataType

The PayloadDataType class within a LoRaWAN binding instance serves as value for the modv: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:

• xsd:integer
• xsd:boolean
• xsd:string
• xsd:float
• xsd:decimal
• xsd:byte
• xsd:short
• xsd:int
• xsd:long
• xsd:unsignedByte
• xsd:unsignedShort
• xsd:unsignedInt
• xsd:unsignedLong
• xsd:double
• xsd:hexBinary

Mappings

Examples

{
  "@context": [
    "https://www.w3.org/2022/wot/td/v1.1"
  ],
  "id": "urn:dragino-lht-65n-e3",
  "securityDefinitions": {
    "nosec_sc": {
      "scheme": "nosec"
    }
  },
  "security": [
    "nosec_sc"
  ],
  "@type": [
    "Thing"
  ],
  "name": "Dragino LHT65N-E3 A84041B98D5CB233",
  "base": "lorawan://A84041B98D5CB233/569F632C48146DBB92E7ECA0859F12A7/device",
  "title": "Dragino LHT65N-E3",
  "properties": {
    "batteryLevel": {
      "type": "number",
      "uav:mapToNodeId": "s=A84041B98D5CB233_BatteryLevel",
      "readOnly": true,
      "observable": true,
      "forms": [
        {
          "href": "A84041B98D5CB233/0?quantity=2",
          "type": "xsd:short",
          "lorav:mostSignificantByte": true,
          "lorav:bitmask": "0x3FFF",
          "lorav:multiplier": 0.001
        }
      ]
    },
    "temperature": {
      "type": "number",
      "uav:mapToNodeId": "s=A84041B98D5CB233_Temperature",
      "readOnly": true,
      "observable": true,
      "forms": [
        {
          "href": "A84041B98D5CB233/2?quantity=2",
          "type": "xsd:short",
          "lorav:mostSignificantByte": true,
          "lorav:multiplier": 0.01
        }
      ]
    },
    "humidity": {
      "type": "number",
      "uav:mapToNodeId": "s=A84041B98D5CB233_Humidity",
      "readOnly": true,
      "observable": true,
      "forms": [
        {
          "href": "A84041B98D5CB233/4?quantity=2",
          "type": "xsd:short",
          "lorav:mostSignificantByte": true,
          "lorav:multiplier": 0.1
        }
      ]
    },
    "extTemperature": {
      "type": "number",
      "uav:mapToNodeId": "s=A84041B98D5CB233_ExternalTemperature",
      "readOnly": true,
      "observable": true,
      "forms": [
        {
          "href": "A84041B98D5CB233/7?quantity=2",
          "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",
      "uav:mapToNodeId": "s=2CCF67FFFEFB3C8F_RouterConfig",
      "readOnly": true,
      "forms": [
        {
          "msgtype": "router_config",
          "NetID": [ 1 ],
          "JoinEui": [ [ 0, -1 ] ],
          "region": "EU863",
          "hwspec": "sx1301/1",
          "freq_range": [ 863000000, 870000000 ],
          "DRs": [
            [ 12, 125, 0 ],
            [ 11, 125, 0 ],
            [ 10, 125, 0 ],
            [ 9, 125, 0 ],
            [ 8, 125, 0 ],
            [ 7, 125, 0 ],
            [ 7, 250, 0 ]
          ],
          "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
              }
            }
          ],
          "nocca": true,
          "nodc": true,
          "nodwell": true
        }
      ]
    }
  }
}