Thing Description ABP 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": "",
  "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"
    },
    "activate": {
      "title": "Activate",
      "description": "Activate ABP device",
      "input": {
        "type": "object",
        "properties": {
          "dev_addr": {
            "type": "string"
          },
          "app_s_key": {
            "type": "string"
          },
          "nwk_s_key": {
            "type": "string"
          }
        }
      }
    },
    "deactivate": {
      "title": "Deactivate",
      "description": "Deactivate ABP 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"
          },
          "object": {
            "type": "string"
          },
          "is_pending": {
            "type": "boolean"
          },
          "is_encrypted": {
            "type": "boolean"
          },
          "expires_at": {
            "type": "string"
          }
        }
      }
    }
  },
  "events": {
    "getActivation": {
      "title": "getActivation request is done",
      "description": "response of getActivation request",
      "data": {
        "type": "object"
      }
    },
    "activate": {
      "title": "activate request is done",
      "description": "response of activate 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 ABP 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.

Configuration Using Thing Properties

Instead of adding the required configuration parameters to the @type, the configuration can be set using properties on the thing schema.

"properties": {
	"config": {
		"properties": {
			"devEUI": {
                                "title": "Device EUI",
				"type": "string"
			},
			"deviceProfileID": {
                                "title": "Device Profile ID",
				"type": "string"
			}
		},
                "title": "LoRa Configuration",
		"type": "object"
	},
	"enabled": {
		"title": "Enabled",
		"type": "boolean"
	},
	"skipFrameCountCheck": {
                "title": "Skip Frame Counter Validation",
		"type": "boolean"
	},

The devEUI and deviceProfileID are part of the config property (object).

Note: When using properties to configure the LoRaWAN device make sure to only use swx:lorawan as the @type.

Available Actions

activate

An ABP device needs to have DevAddr, AppSKey and NwkSKey set in both the LoRa Server Stack and the device to allow join and activation. The DevAddr, AppSKey and NwkSKey can be set (create or update) using the activate Action.

The device address (dev_addr) is most likely set by the manufacturer and, if so, needs to be obtained from the end device. The application session key (app_s_key) and the network session key (nwk_s_key) are 128 bits AES-128 keys and need to be set both at the application server and the end devices.

Any (or all) of these three keys 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 that can then be used at the end device too.

deactivate

The deactivate Action will deactivate 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 "object" 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/object conversion takes place, this is "raw"):

POST /drivers/lorawan/tenants/{tenant-id}/applications/{application-id}/devices/{device-id}/queue

listDeviceQueueItems

This will list all outstanding, queued items.

Note: equivalent API endpoint:

GET /drivers/lorawan/tenants/{tenant-id}/applications/{application-id}/devices/{device-id}/queue

flushDeviceQueue

This will flush (delete) all outstanding, queued items.

Note: equivalent API endpoint:

DELETE /drivers/lorawan/tenants/{tenant-id}/applications/{application-id}/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
    },