Device

Device #

Device (api/v1/device) #

Access to device object. For accessing list of devices see Multiple Devices section.

curl -H "X-API-Key: <api key>" https://api.nr.iotready.no/api/v1/device/123

Device object fields:

Field Type Description
created timestamp UTC time of device object creation
updated timestamp UTC time of device object update
dev_id string Unique device ID
product string Product ID. To differentiate between different products
variant string Non-functional variations within same product
hw_version string Device hardware version
status object Current status. See Status Object for details
modem object Modem details
sim object SIM details
external object External data to be assigned to device. See External Object for details
services object Services supported by device

Some of these fields are only shown if they are requested with the comma-separated query parameter named fields. Supported values are:

Value Field
* All fields
** Recursive all fields
status status
modem modem
sim sim
services services 
curl -H "X-API-Key: <api key>" \
    https://api.nr.iotready.no/api/v1/device/123?fields=status,services

Provision #

To claim administrative access to device by dev_id:

curl -H "X-API-Key: <api key>" -X PUT \
    https://api.nr.iotready.no/api/v1/device/123

See Device Life Cycle for details.

Deprovision #

Release administrative access to device:

curl -H "X-API-Key: <api key>" -X DELETE \
    https://api.nr.iotready.no/api/v1/device/123

See Device Life Cycle for details.

Status #

Device status not directly tied to a service.

api/v1/device/<dev_id>/status

Field Type Description
first timestamp UTC Time of first contact
last timestamp UTC Time of last contact
modules object array Module status (see below)

Module status object:

Field Type Description
name string Name of module
firmware string Firmware version
error_time timestamp UTC time of last error
error string Last reported error
reset_time timestamp UTC time of last reset
reset_reason string Last reset reason

External #

External is for API integrator to store own data. Can be anything json with some rules:

  • Limited in total size to 1kiB

Set external:

curl -H "X-API-Key: <api key>" -X PUT -H "Content-Type: application/json" \
    -d '{"name":"my name"}' https://api.nr.iotready.no/api/v1/device/123/external

Modify external with JSON merge patch (RFC7396):

curl -H "X-API-Key: <api key>" -X PATCH -H "Content-Type: application/merge-patch+json" \
    -d '{"name":"my name"}' https://api.nr.iotready.no/api/v1/device/123/external

Services #

Services available is a part of the device object, but can also be queried directly:

curl -H "X-API-Key: <api key>" \
    https://api.nr.iotready.no/api/v1/device/123/services

[
  {
    "name": "serviceA"
  }
]

Details on services are found in the Service chapter.

Message Stream #

Stored device messages can be queried, and this will by default give the last 100 messages:

curl -H "X-API-Key: <api key>" https://api.nr.iotready.no/api/v1/device/123/stream

This query can be customized by these query parameters:

Name Default Description
module Module name
service Service name
name Message name
after Get messages coming after this unique id
from Get messages from and including this ISO timestamp
to Get messages to this ISO timestamp
series tail unless from or after is specified head or tail of stream
count 100 Maximum number of devices to be returned

Multiple Devices (api/v1/devices) #

To fetch to 100 first devices use the following:

curl -H "X-API-Key: <api key>" https://api.nr.iotready.no/api/v1/devices

Following up the initial query, these query parameters can be used:

Name Default Description
previous Get devices after this device id
count 100 Maximum number of devices to be returned 
curl -H "X-API-Key: <api key>" \
    "https://api.nr.iotready.no/api/v1/devices?previous=123&count=10"

Devices can also be listed for a given product by the product query parameter:

Name Default Description
product Get only devices for given product. See Product API for details 
curl -H "X-API-Key: <api key>" \
    "https://api.nr.iotready.no/api/v1/devices?product=product1"