Devices

Introduction

A device represents the physical element (communications devices, concentrators, machines, sensors, etc.) through which data is collected.

Relation between devices and assets

A device can be linked to an asset through the provision.device.related data stream, which must contain the identifier of the asset in question.

When these entities are related, the asset is able to collect data from the related device. In order to do this, it is necessary to define an available data model for the Devices and Assets resources, and then define all the data streams that you want to copy from the device. Once this has been done, the asset will then automatically start collecting these values from the device.

Comprehensive API actions

Creating a device

New devices can be created by sending a POST request that includes a correctly formatted JSON document in the body.

A device may contain or not contain subscriptions and subscribers. Furthermore, these can exist independently (please refer to create subscriptions or create subscribers for more information).

It is essential that the subscription or subscriber is located within the communication modules on the device. Consequently, there are various use cases for managing device relations, depending on whether there are existing subscriptions or subscribers.

The following options are available for creating a device:

  1. Create a device without subscriptions or subscribers.
  2. Create a device with subscriptions or subscribers that do not exist in the platform.
  3. Create a device with subscriptions or subscribers that exist in the platform. In this instance, the following steps must be completed:
  • A device must be created (please refer to the ‘Create a device without subscriptions or subscribers’ section below for further details).
  • The device must then be updated with the relevant subscriptions or subscribers that are already present on the platform (please refer to the ‘Associate a subscription or subscriber to the device’ section below for further details).

Furthermore, a device can be linked to an asset. Please refer to the section entitled [Relation between devices and assets](#relation-between-devices-and-assets) for additional details.

Updating a device

Updates can be made to the following:

  • Device data
  • Device subscription or subscriber associations
  • Device subscription or subscriber disassociations

The JSON object passed will vary depending on the desired update.

Patching a device.

It is possible to patch the following:

  • Only the device data
  • Associate a subscription or subscriber to the device The JSON object passed will be different depending on the desired patch. Furthermore, a device can be related to an asset. Please refer to the section entitled ‘Relation between devices and assets’ for more information.

Deleting a device

To delete a complete device with all associated subscriptions, send a DELETE request using the provided URL. The request should include a Boolean parameter, “full,” to indicate that you wish to delete the entire device.

Note

The default value of the field ‘full’ is set to ‘false’. In this case, if a device with a subscription or subscriber is deleted, only the device will be removed. Neither the subscription nor the subscriber will be deleted. After this, they will exist on the platform independently, without being associated with a device.

Searching device

This API enables the retrieval of a comprehensive list of devices, offering a multitude of options for:

  • Filter (See Specific Filter Fields)
  • Order (see Sorting)
  • Select Required Fields (see Selecting)
  • Summary (see Summary)

The results can be obtained in two different formats, as detailed in the HTTP Header Options.

  • JSON Format (Default)
  • CSV Format

As an alternative, the result can be obtained in a flattened format thanks to the flattened parameter (see device parameters).

API specification