Devices¶

Device Data Structure¶

A device is anything that produces or consumes data in the form of packets or readings. It usually represents a physical sensor, but it can also represent a virtual device or an intermediate component such as a gateway or routing system.

Every device can have any number of interfaces attached. An interface connects the device with the driver by providing device-specific configuration parameters such as identifiers (EUIs, UUIDs) and individual per-interface configuration. This way, the platform allows hardware with multiple connectivity options (e.g. with both a LPWAN chip and Wireless LAN) to be represented by a single device.

In responses, a device looks like this:

{
  "updated_at": "2017-08-09T09:27:17.641848",
  "template_id": null,
  "type": "generic",
  "tags": [
    {
      "updated_at": "2017-08-14T08:58:58.975238",
      "slug": "air-quality",
      "name": "Air Quality",
      "mandate_id": "50e032fb-964f-440d-9b9a-47870667373c",
      "inserted_at": "2017-01-01T00:00:01.000000",
      "id": "b9a52ff7-1aad-4283-ab57-0c0b4317f586",
      "description": "Air Quality Sensors",
      "default_layers_id": null,
      "default_graph_preset_id": null,
      "color_hue": 213
    }
  ],
  "static_location": true,
  "slug": "device-1",
  "profile_data":[
    {
      "updated_at":"2017-08-09T06:33:57.181488",
      "profile_id":"3e0db966-ed82-4f1d-96d0-08d4f9696abe",
      "profile":{
         "updated_at":"2017-08-09T06:13:39.596302",
         "slug":"example_profile",
         "name":"Beispiel Profil",
         "mandate_id":"50e032fb-964f-440d-9b9a-47870667373c",
         "limit_to":"none",
         "inserted_at":"2017-08-09T06:13:39.596295",
         "id":"3e0db966-ed82-4f1d-96d0-08d4f9696abe",
         "fields":[
            {
               "type":"string",
               "required":false,
               "name":"name",
               "min":null,
               "max":null,
               "id":"11ad6ef4-645b-47f0-a552-4b09f28e93a7",
               "format":null,
               "display":"Name"
            }
         ]
      },
      "inserted_at":"2017-08-09T06:33:57.181477",
      "device_id":"a70a234e-d186-4ca8-836b-74816738939e",
      "data":{
         "name":"Example Name"
      }
    }
  ],
  "parser_id": "cee40cb2-f58c-4ca8-ae91-4ae76cba5119",
  "name": "Device #1",
  "meta": {},
  "mandate_id": "50e032fb-964f-440d-9b9a-47870667373c",
  "location": {
    "type": "Point",
    "coordinates": [
      9.959696531296402,
      53.5501216243068
    ]
  },
  "interfaces": [
    {
      "opts": {
        "network_session_key": "",
        "managed": false,
        "enabled": true,
        "duplicate_framecounter_allowed": true,
        "device_type": "otaa",
        "device_key": "",
        "device_eui": "",
        "device_address": "",
        "app_session_key": ""
      },
      "id": "0f7c53ae-4366-42dd-9ffc-158e1ccae7aa",
      "driver_instance_id": "9cf80c6a-1669-4cbf-96d0-9eefb707d294",
      "device_id": "a70a234e-d186-4ca8-836b-74816738939e"
    }
  ],
  "inserted_at": "2017-08-09T09:24:42.866589",
  "id": "a70a234e-d186-4ca8-836b-74816738939e",
  "icon":"devices",
  "fields": {
    "example_profile": {
      "name":"Example Name"
    }
  },
  "default_layers_id":null,
  "default_graph_preset_id":null
}

Key	Example	Description
`name`	`Device #1`	Name of the device
`slug`	`device-1`	URL-compatible name-based slug
`icon`	`device`	Icon name for the device
`id`	`a70a234e-d186-4ca8-836b-74816738939e`	Unique device ID (UUID4)
`type`	`generic`	Enumerated type of the device. Can be `generic`, `gateway`, `virtual` or `sensor`
`static_location`	`true`	Boolean value stating whether the device will have a fixed geolocation
`location`	`{"location": {"type": "Point", "coordinates": [40.3684324046728, 42.221249216157474]}}`	GeoJSON point of the device location
`meta`	`{}`	Freeform JSON object that may contain any data
`tags`	`[ ... tags ... ]`	An array of folders
`interfaces`	`[ ... interfaces ... ]`	An array of interfaces
`profile_data`	`[ ... profile_data ... ]`	An array of profile_data entries with connected profiles (since v2.4.0)
`fields`	`{"profile_name": {"key": "value"}}`	JSON Object for accessing the values from connected profiles (since v2.4.0)
`parser_id`	`cee40cb2-f58c-4ca8-ae91-4ae76cba5119`	Reference to a parser used for parsing packets
`mandate_id`	`50e032fb-964f-440d-9b9a-47870667373c`	Reference to the mandate this device belongs to
`template_id`	`0100ecd4-9ace-4e5b-bf8e-17e09a023f8c`	Reference to the template used for tis device
`updated_at`	`2017-08-09T09:27:17.641848`	Date of the last change to the device
`inserted_at`	`2017-08-09T09:24:42.866589`	Date of the creation to the device

List all Devices¶

Method: GET, Endpoint: /devices/

To filter with a selector, use this endpoint:

/devices/by-:type/:identifier/

Example Requests¶

GET https://element-iot.com/api/v1/devices?auth=46cb688e2c0b468e26e914235d4b73ea

GET https://element-iot.com/api/v1/devices/by-eui/F05FEFEC6488E9C6?auth=46cb688e2c0b468e26e914235d4b73ea

Example Response¶

{
  "status": 200,
  "retrieve_after_id": "a70a234e-d186-4ca8-836b-74816738939e",
  "ok": true,
  "body": [
    // Contains an array of devices
  ]
}

This endpoint returns a paginated list of devices.

If you want to configure the sort order or restrict the results to a specific time interval, please refer to the Pagination section of this documentation.

The data from profiles is not included by default in the device listing. Adding the profile and data can be done using the parameter &with_profile=1 (since v2.4.0).

You can preload between 0 and 20 of the last readings of each device by passing the parameter last_readings=x where x is the desired amount of readings. If a value greater than 0 is passed, each device will have an additional field called last_readings which contains a list of the readings, ordered from newest to oldest.

Filtering¶

By using selectors, the device list can be filtered by certain identifiers, such as EUIs of interfaces.

The device list can also be filtered by supplying an AbacusSql expression with the filter query parameter. Since the language contains special characters, make sure to URI encode the filters.

The root schema of the filter is a device.

Both ways of supplying filters can be used at the same time, which will mean that both conditions must be met for a device to appear in the list.

Show a single Device¶

Method: GET, Endpoint: /devices/:id_or_slug

Example Request¶

GET https://element-iot.com/api/v1/devices/test-1?auth=46cb688e2c0b468e26e914235d4b73ea

Example Response¶

{
  "status": 200,
  "ok": true,
  "body": {
    // Contains the device
  }
}

The device ID may be either the id or the slug of the device.

Create a new Device¶

Method: POST, Endpoint: /devices

Example Request¶

POST https://element-iot.com/api/v1/devices?auth=46cb688e2c0b468e26e914235d4b73ea
{
  "device": {
    "name": "New Name",
    "type": "sensor",
    "tags": [
      {
        "id": "9e5121d8-dbb7-42d9-ba46-1bc95af3a350"
      },
      {
        "action": "create",
        "name": "New Folder",
        "color_hue": 100
      }
      ]
  }
}

Example Response¶

{
  "status": 200,
  "ok": true,
  "body": {
    // Contains the new device
  }
}

Important

At least one tag must be provided!

Parameters

Encapsulate all parameters to be changed in a device object in the request body.

To save a device with folders, there are two options, both usable at the same time. You can use existing folders by referencing their ID as in the "tags": [{"id": "9e5121d8-dbb7-42d9-ba46-1bc95af3a350"}] notation. You can also instruct ELEMENT to create a new folder prior to creating the device by using the action: create property, as in "tags": [{"action": "create", "name": "That new folder", "color_hue": 100}]. Make sure you supply the name and color hue to be used in the frontend.

Edit single Device¶

Method: PUT or PATCH, Endpoint: /devices/:device_id

Example Request¶

PUT https://element-iot.com/api/v1/devices/test-1?auth=46cb688e2c0b468e26e914235d4b73ea
{
  "device": {
    "name": "New Name",
    "type": "sensor"
  }
}

Example Response¶

{
  "status": 200,
  "ok": true,
  "body": {
    // Contains the changed device
  }
}

Parameters

Encapsulate all parameters to be changed in a device object in the request body.

The device ID may be either the id or the slug of the device.

Delete single Device¶

Method: DELETE, Endpoint: /devices/:device_id

Example Request¶

DELETE https://element-iot.com/api/v1/devices/test-1?auth=46cb688e2c0b468e26e914235d4b73ea

Example Response¶

{
  "status": 200,
  "ok": true,
  "body": {
    // Contains the deleted device
  }
}

The device ID may be either the id or the slug of the device.

Show Interfaces for Device¶

Method: GET, Endpoint: /devices/:device_id/interfaces

Example Request¶

GET https://element-iot.com/api/v1/devices/test-1/interfaces?auth=46cb688e2c0b468e26e914235d4b73ea

Example Response¶

{
  "status": 200,
  "ok": true,
  "body": {
    // Contains a list of the interfaces attached to the device
  }
}

The device ID may be either the id or the slug of the device.

This endpoint returns a paginated list of interfaces for this particular device. Please refer to the interfaces documentation for the contents of the response.

Show Packets for Device¶

Method: GET, Endpoint: /devices/:id_or_slug/packets

To use a selector instead of :id_or_slug, use this endpoint:

/devices/by-:type/:identifier/packets

Streaming variants:

/devices/:id_or_slug/packets/stream
/devices/by-:type/:identifier/packets/stream

Example Requests¶

GET https://element-iot.com/api/v1/devices/test-1/packets?auth=46cb688e2c0b468e26e914235d4b73ea

GET https://element-iot.com/api/v1/devices/by-eui/587410B576AAAE9F/packets?auth=46cb688e2c0b468e26e914235d4b73ea

Example Response¶

{
  "status": 200,
  "ok": true,
  "body": {
    // Contains a list of the packets attached to the device
  }
}

The device ID may be either the id or the slug of the device.

The optional parameter packet_type can be used to filter packets by type. For example when only up packets are needed.

The sorting is fixed to transceived_at and can not be changed.

This endpoint returns a paginated list of packets for this particular device. Please refer to the packets documentation for the contents of the response.

Filtering¶

Similarly to the device list, the packets list can be filtered with AbacusSql expressions by supplying it with the filter query parameter.

The root schema for this filter is a packet.

Show Readings for Device¶

Method: GET, Endpoint: /devices/:id_or_slug/readings

To use a selector instead of :id_or_slug, use this endpoint:

/devices/by-:type/:identifier/readings

Streaming variants:

/devices/:id_or_slug/readings/stream
/devices/by-:type/:identifier/readings/stream

Parameters¶

Query Parameter	Description
`auth` String *****	API Key or JWT
`retrieve_after` UUID	To go to the next page, pass the ID of the last reading from the result list here. Read more about pagination
`sort` `measured_at`	Column to sort the readings by (default `measured_at`)
`sort_direction` `asc` or `desc`	Switch the sort direction (default `desc`)
`limit` Integer 1-100	Control how many readings are loaded per page (default `10`)
`before` ISO8601	Only show readings measured before this date
`after` ISO8601	Only show readings measured after this date
`filter` AbacusSql	Expression that filters the readings. The root schema of the filter is a reading.

Example Requests¶

GET https://element-iot.com/api/v1/devices/test-1/readings?auth=46cb688e2c0b468e26e914235d4b73ea

GET https://element-iot.com/api/v1/devices/by-eui/587410B576AAAE9F/readings?auth=46cb688e2c0b468e26e914235d4b73ea

Example Response¶

{
  "status": 200,
  "ok": true,
  "body": {
    // Contains a list of the readings attached to the device
  }
}

The device ID may be either the id or the slug of the device.

The sorting is fixed to measured_at and can not be changed.

This endpoint returns a paginated list of readings for this particular device. Please refer to the readings documentation for the contents of the response.

If you want to configure the sort order or restrict the results to a specific time interval, please refer to the Pagination section of this documentation.

Filtering¶

Similarly to the device list, the readings list can be filtered with AbacusSql expressions by supplying it with the filter query parameter.

The root schema for this filter is a reading.

Create Action for Device¶

Create packet for device

If you just want to create a packet for a device, use the resource Create a Packet for Device

Method: POST, Endpoint: /devices/:id_or_slug/interfaces/:interface_id/actions/:action_name

The device ID may be either the id or the slug of the device.

The needed fields in opts can be found in the detail view of a action.

Example Request¶

POST https://element-iot.com/api/v1/devices/c2cb74b9-a615-47bc-a013-7c3408abb5da/interfaces/4e1de447-9f89-4bbc-ab11-874982e97005/actions/send_down_frame?auth=46cb688e2c0b468e26e914235d4b73ea
{
  "opts": {
    "port": 1,
    "payload": "CAFE",
    "immediately": true,
    "acknowledge": false
  }
}

Example Response¶

{
  "id": "4aaaa220-41bb-4bb1-b26a-447b35087ef7",
  "type": "send_down_frame",
  "state": "pending",
  "result": null,
  "order": null,
  "opts": {
    "port": 1,
    "payload": "CAFE",
    "immediately": true,
    "acknowledge": false
  },
  "device_id": "c2cb74b9-a615-47bc-a013-7c3408abb5da",
  "mandate_id": "6c11c072-fe80-4491-a22f-2e65670b0a5d",
  "interface_id": "3ae83c57-6c28-4292-87ca-c570924d3365",
  "executed_at": null,
  "inserted_at": "2019-08-06T07:29:23.343062Z",
  "updated_at": "2019-08-06T07:29:23.352383Z"
}

Websocket¶

The packets and readings of a device can be pushed using a websocket.