Skip to main content

Device Management API

Each device in myDevices has a unique Hardware Id and a device template associated with it. The device template defines the device type and its capabilities. The capabilities denote a set of sensor measurements the device supports. Additionally, the device template provides default use cases, alert definitions, and other metadata.

Deriving Device Template ID​

To add a device, the device template id should be derived from the hardware ID.

GET /things/meta/{hardwareId}​

This endpoint retrieves the device template id and minimal information based on the hardware ID.

Request​

Parameters:

  • {hardwareId}: Unique hardware ID of the device.

Response​

200 OK

Returns the device template details.

{
    "broadcast_interval": "1440",
    "device_type": "Camera AI",
    "device_type_id": "aebb6fd0-fbe7-11ed-9d54-717ad8a605ca",
    // ... [truncated for brevity]
    "device_use": {
        "count": 2,
        "limit": 100,
        "page": 0,
        "rows": [
            // ... [truncated for brevity]
        ]
    }
}

This response contains the device_type_id, also known as the device template id.

Get Device Template​

To add a device, the device template id should be derived from the hardware ID.

GET /v1.0/things/types/{device_type_id}​

This endpoint retrieves the device template information based on the hardware ID.

Request​

Parameters:

  • {device_type_id}: Unique device template/type ID of the device.

Response​

200 OK

Returns the device template details.

{
  "id": "121f6268-e52b-11e7-80c1-9a214cf093ae",
  "name": "Netvox Window/Door Open/Close",
  "description": "Netvox’s wireless door/window sensor utilizes a magnetic switch to detect when a door or window is opened. Ideal for areas where access needs to be monitored, the wireless sensor sends an alert message to a centralised monitoring system via the LoRaWAN protocol when a window or door is opened.",
  // ... [truncated for brevity]
  "application_id": null,
  "meta": [
    {
      "id": 68,
      "key": "device_type",
      "value": "Open/Close",
      "device_type_id": "121f6268-e52b-11e7-80c1-9a214cf093ae"
    },
    {
      "id": 78,
      "key": "instructions",
      "value": "Push any button, check that the status light blinks green",
      "device_type_id": "121f6268-e52b-11e7-80c1-9a214cf093ae"
    },
    // ... [truncated for brevity]
  ],
  "channels": [
    {
      "data": null,
      "id": 70,
      "name": "battery",
      "datatype": "BATTERY",
      "data_types_id": 11,
      "channel": "5",
      "ipso": null,
      "order": 1,
      "device_type_id": "121f6268-e52b-11e7-80c1-9a214cf093ae"
    },
    // ... [truncated for brevity]
  ],
  "device_use": [
    {
      "settings": null,
      "id": 109,
      "name": "Door",
      "default": false,
      "alert_min": null,
      "alert_max": null,
      "alert_readings": null,
      "device_type_id": "121f6268-e52b-11e7-80c1-9a214cf093ae"
    },
    // ... [truncated for brevity]
  ]
}

This response contains the device_type_id, also known as the device template id.

Adding a Device​

Once the device template id has been retrieved, you can proceed to add a device to the application.

POST /companies/{company_id}/locations/{location_id}/things/sensors​

This endpoint is used to add a new device.

Request​

Parameters:

  • {company_id}: Company ID of the company to which the device belongs.
  • {location_id}: Location ID of the location to which the device belongs.

Headers (if any, not mentioned in the given text):

  • Authorization: Your authorization token (example)

Payload:

The device_id is actually the hardware_id of the device.

{
  "name": "Smart Buildings",
  "device_id": "vid-8011-4309",
  "sensor_use": "Smart Buildings",
  "sensor_type": "Camera AI",
  "properties": {
  }
}

Response​

200 OK

Indicates that the device was successfully added.

409 CONFLICT