Thing Description OTAA Device

Example Thing Description

See Things documentation on how to manage Things in Altair IoT Studio.

A Thing for this device driver uses a schema as described on this page.

Once it exists in Studio it can be synced to the Cluster (Asset) as shown on the Sync Things page.

{
  "@type": [
    "swx:lorawan,devEUI=,deviceProfileID="
  ],
  "id": "<leave blank when creating a thing>",
  "title": "LoRaWAN Test Device",
  "properties": {
    "myReadProperty": {
      "title": "My Read Property",
      "type": "number",
      "readOnly": true
    },
    "myWriteProperty": {
      "title": "My Write Property",
      "type": "number",
      "@type": [
          "swx:lorawan,f_port=1"
      ],
      "readOnly": false
    },
    "enabled": {
      "title": "Enabled",
      "type": "boolean",
      "readOnly": false
    }
  },
  "actions": {
    "getActivation": {
      "title": "Get activation",
      "description": "Get activation details for device"
    },
    "getDeviceKeys": {
      "title": "Get device keys",
      "description": "Get device keys for OTAA device"
    },
    "setDeviceKeys": {
      "title": "Set device keys",
      "description": "Set device keys for OTAA device",
      "input": {
        "type": "object",
        "properties": {
          "nwk_key": {
            "type": "string"
          }
        }
      }
    },
    "deleteDeviceKeys": {
      "title": "Delete device keys",
      "description": "Delete device keys for OTAA device"
    },
    "listDeviceQueueItems": {
      "title": "List deviceQueue items",
      "description": "List deviceQueue items",
      "input": {
        "type": "object",
        "properties": {
          "countOnly": {
            "type": "boolean"
          }
        }
      }
    },
    "flushDeviceQueue": {
      "title": "Flush deviceQueue",
      "description": "Flush deviceQueue"
    },
    "enqueue": {
      "title": "Add item to deviceQueue",
      "description": "Add item to deviceQueue",
      "input": {
        "type": "object",
        "properties": {
          "f_port": {
            "type": "integer"
          },
          "data": {
            "type": "string"
          },
          "jsonObject": {
            "type": "string"
          }
        }
      }
    }
  },
  "events": {
    "getActivation": {
      "title": "getActivation request is done",
      "description": "response of getActivation request",
      "data": {
        "type": "object"
      }
    },
    "getDeviceKeys": {
      "title": "getDeviceKeys request is done",
      "description": "response of getDeviceKeys request",
      "data": {
        "type": "object"
      }
    },
    "setDeviceKeys": {
      "title": "setDeviceKeys request is done",
      "description": "response of setDeviceKeys request",
      "data": {
        "type": "object"
      }
    },
    "listDeviceQueueItems": {
      "title": "listDeviceQueueItems request is done",
      "description": "response of listDeviceQueueItems request",
      "data": {
        "type": "object"
      }
    },
    "enqueue": {
      "title": "enqueue request is done",
      "description": "response of enqueue request",
      "data": {
        "type": "object"
      }
    }
  }
}

The device profile has the flag to mark it as an OTAA device.

Configuration Using the "@type"

The "@type" is used to set two required configuration parameters:
  • devEUI
  • deviceProfileID

The devEUI is a 64-bit globally-unique Extended Unique Identifier (EUI-64) assigned by the manufacturer, or the owner, of the end-device. It should be set in the "@type" of the Thing.

The deviceProfileID is the unique identifier for the device profile specific for this device (class). Device profiles can be managed through the API. See the appropriate help page.

There is an optional applicationID parameter. If omitted it will use the default generated application (highly recommended). However, applications can be managed through the device driver API and the Thing description can be set to use a specific application.

Available Actions

An OTAA device needs to have an AppKey set in both the LoRa Server Stack and the device to allow automatic join and activation.

setDeviceKeys
The network key (or application key) (nwk_key) is a 128 bits AES-128 key and needs to be set both at the application server and the end device. The key can be auto-generated by the LoRaWAN device driver by sending in the "generate" (string) value.
The result of the Action is sent up as an Event and will give you the (generated) values for network and application keys that can then be used at the end device too.
The generated key(s) can be retrieved using the getDeviceKeys Action.
getDeviceKeys
This retrieves the device keys.
deleteDeviceKeys
This will delete the device keys and, therefor, de-activate the device.
getActivation
The activation details can be retrieved using the getActivation Action.
enqueue
Messages to be sent to the end-device can be added to the queue by running this Action.
The f_port (frame port) needs to be specified. The message itself either needs to be specified as base64 encoded "data" or as a "jsonObject" string.
The device driver has been coded to handle both types, regardless of whether the device profile has an encryption/decryption codec set (see Chirpstack Device Profiles for more details).
The device driver will check the device profile to see if a codec is in use and "convert" from one type to another. Apart from a codec a "conversion template" can be used to convert from/to array and object formats. See the Payload Conversion page for more details.
Note: equivalent API endpoint (no data/jsonObject conversion takes place, this is "raw"):
POST /drivers/lorawan/devices/{device-id}/queue
listDeviceQueueItems
This will list all outstanding, queued items.
Note: equivalent API endpoint:
GET /drivers/lorawan/devices/{device-id}/queue
flushDeviceQueue
This will flush (delete) all outstanding, queued items.
Note: equivalent API endpoint:
DELETE /drivers/lorawan/devices/{device-id}/queue

Writeable Property

LoRaWAN does not have the notion of writing/setting a property (or running an Action, for that matter); it is only possible to enqueue a message that then need to be processed by the device.

There is already a (generic) Action on the Thing description to enqueue a message. Apart from the message body itself (either as binary data (i.e., base64 encoded), or as a JSON object (only if the device profile has a codec set)) this requires an fPort to be specified.

The device driver has "setProperty" functionality using the "enqueue" mechanism. Since this needs an fPort, it is possible to specify the fPort in the "@type" of the property itself. If not set, a default value of 1 is used. It is up to the end device to use (validate/verify) the fPort value.

Example of property definition:

    "thermostat": {
      "title": "Thermostat",
      "type": "number",
      "@type": [
        "swx:lorawan,f_port=1"
      ],
      "readOnly": false
    },