API Documentation

Object types

Sensor types:

ANALOG

Accepts any values that can be expressed as a float number.

Example value:

{
  "value": 42.55
}

DIGITAL

Accepts only 0 or 1.

Example value:

{
  "value": 0
}

LOCATION

Accepts GeoJSON features containing only one point.

Note that according to the GeoJSON standard coordinates are supposed to be [longitude, latitude ] ([E-W, N-S], in the [-180 - 180, -90 - 90] range). Some other services (such as Google Maps) use coordinate representation in a [latitude, longitude] format and care must be taken to flip the coordinates when interfacing with such services.

Example value:

{
  "value": {
    "type": "Feature",
    "properties": {},
    "geometry": {
    "type": "Point",
    "coordinates": [
       -0.12685775756835938,
       51.43809241973026
       ]
    }
  }
}

STRING

Accepts any string input, up to a maximum length of 256 characters.
Example value:

{
  "value": "Device booted up successfully."
}

Actuator types:

ANALOG

Accepts any values that can be expressed as a float number.

Example value:

{
  "state": 52.2
}

DIGITAL

Accepts only 0 or 1.

Example value:

{
  "state": 1
}

Endpoints

REST JSON

The REST JSON APIs use JSON documents for data exchange. These APIs are better suited for devices with a comfortable amount of memory or for mobile and web applications.

REST JSON - Authentication

All requests must contain a valid project ApiKey as part of the X-ApiKey header.
Additionally, all POST requests must contain the proper Content-Type: application/json header.

Example GET request:

curl -H "X-ApiKey: 1f3dc5c-3f05-47bd-836b-cb0b85d11545" -i "request_url"

Example POST request:

curl -H "X-ApiKey: 1f3dc5c-3f05-47bd-836b-cb0b85d11545" -H "Content-Type: appplication/json" -i "request_url" -d '{request_payload}'

REST JSON - Get historic sensor values

GET api.devicehub.net/v2/project:/[project_id]/device/[device_id]/sensor/[sensor_name]/data?limit=[limit]&from=[from_timestamp]&to=[to_timestamp]

URL Parameters

Parameter Description
limit Optional. Number of data entries to return. If it is omitted, it defaults to 1.
from Optional. POSIX timestamp (without microsecond decimals) from which to filter the data entries.
to Optional. POSIX timestamp (without microsecond decimals) up to which to filter the data entries.

Example Usage

curl -H "X-ApiKey: 1f3dc5c-3f05-47bd-836b-cb0b85d11545" -i "https://api.devicehub.net/v2/project/370/device/d3f94cb1-3f34-4f7b-9044-26cc0c10b29e/sensor/mr_sensor/data?limit=2&from=1430905196"

Response

[
  {
    "protocol":"http",
    "timestamp":1430905196.0,
    "value":"62",
    "timestamp_iso":"2015-05-06T09:39:56Z",
    "meta":{
      "protocol":"http"
    },
    "server_timestamp":"2015-05-06T09:41:03.227Z"
  },
  {
    "protocol":"http",
    "timestamp":null,
    "value":"55",
    "timestamp_iso":null,
    "meta":{
      "protocol":"http"
    },
    server_timestamp":"2015-05-06T09:26:21.294Z"
  }
]

Response Parameters

Field name Data type Notes
value varies sensor value, as was submitted
timestamp POSIX timestamp is null if it wasn’t specified when the data was submitted
timestamp_iso ISO 8601 the ISO 8601 equivalent of the above timestamp. null if timestamp wasn’t specified
server_timestamp ISO 8601 The ISO 8601 timestamp of when the server received the data
protocol text protocol used when the data was submitted
meta JSON metadata field supplied by the user, appended with protocol by the server if it wasn’t supplied

REST JSON - Send sensor value

POST v2/project:/[project_id]/device/[device_id]/sensor/[sensor_name]/data

Headers
Aside from the X-ApiKey header, all JSON POST requests must also have Content-Type: application/json in their headers.

Example Usage

curl -H "X-ApiKey: 1f3dc5c-3f05-47bd-836b-cb0b85d11545" -H "Content-Type: application/json" -i "https://api.devicehub.net/v2/project/370/device/d3f94cb1-3f34-4f7b-9044-26cc0c10b29e/sensor/mr_sensor/data" -d '{"value":34}'

JSON Data Example

{
  "value": 62,
  "timestamp": 1430905196.0,
  "meta":{
    "user_meta_key1": "user_meta_value1",
    "user_meta_key2": "user_meta_value2",
    "protocol": "custom_user_protocol",
  }
}

Requests Parameters

Field name Data Type Notes
value varies Required. The sensor value to be sent. Its type and value varies depending on the sensor’s type.
timestamp POSIX timestamp Optional. A user-selectable timestamp attached to the data entry.
meta JSON Optional. A meta field created by the user. If it is included and contains a protocol field, it shall be attached to the data entry. If it is omitted or does not contain a protocol field, the server will generate the field automatically.

Response

{"request_status":1}

REST JSON - Get current actuator state

GET api.devicehub.net/v2/project:/[project_id]/device/[device_id]/actuator/[actuator_name]/state

Example Usage

curl -H "X-ApiKey: 1f3dc5c-3f05-47bd-836b-cb0b85d11545" -i "https://api.devicehub.net/v2/project/370/device/d3f94cb1-3f34-4f7b-9044-26cc0c10b29e/actuator/mrs_actuator/state"

Response

[
  {
    "state":1,
    "server_timestamp":"2015-05-06T10:23:01.652Z",
    "timestamp":null,
    "timestamp_iso":null,
    "meta":{
      "protocol":"http"
    },
    "protocol":"http"
  }
]

Response Parameters

Field name Data type Notes
state integer actuator state, as was submitted
timestamp POSIX timestamp is null if it wasn’t specified when the data was submitted
timestamp_iso ISO 8601 the ISO 8601 equivalent of the above timestamp. null if timestamp wasn’t specified
server_timestamp ISO 8601 The ISO 8601 timestamp of when the server received the data
protocol text protocol used when the data was submitted
meta JSON metadata field supplied by the user, appended with protocol by the server if it wasn’t supplied

REST JSON - Get historic actuator states

GET api.devicehub.net/v2/project:/[project_id]/device/[device_id]/actuator/[actuator_name]/state?limit=[limit]

URL Parameters

Parameter Description
limit Optional. Number of data entries to return. If it is omitted, it defaults to 1.
from Optional. POSIX timestamp (without microsecond decimals) from which to filter the data entries.
to Optional. POSIX timestamp (without microsecond decimals) up to which to filter the data entries.

Example Usage

curl -H "X-ApiKey: 1f3dc5c-3f05-47bd-836b-cb0b85d11545" -i "https://api.devicehub.net/v2/project/370/device/d3f94cb1-3f34-4f7b-9044-26cc0c10b29e/actuator/mrs_actuator/state?limit=2&from=1430905196"

Response

[
  {
    "state":0,
    "server_timestamp":"2015-05-06T10:43:54.580Z",
    "timestamp":null,
    "timestamp_iso":null,
    "protocol":"http",
    "meta":{
      "protocol":"http"
    },
  },
  {
    "state":1,
    "server_timestamp":"2015-05-06T10:35:06.265Z",
    "timestamp":null,
    "timestamp_iso":null,
    "protocol":"http",
    "meta":{
      "protocol":"http"
    },
  }
]

Response Parameters

Field name Data type Notes
state integer actuator state, as was submitted
timestamp POSIX timestamp is null if it wasn’t specified when the data was submitted
timestamp_iso ISO 8601 the ISO 8601 equivalent of the above timestamp. null if timestamp wasn’t specified
server_timestamp ISO 8601 The ISO 8601 timestamp of when the server received the data
protocol text protocol used when the data was submitted
meta JSON metadata field supplied by the user, appended with protocol by the server if it wasn’t supplied

REST JSON - Send actuator state

POST api.devicehub.net/v2/project:/[project_id]/device/[device_id]/actuator/[actuator_name]/state

Headers
Aside from the X-ApiKey header, all JSON POST requests must also have Content-Type: application/json in their headers.

Example Usage

curl -H "X-ApiKey: 1f3dc5c-3f05-47bd-836b-cb0b85d11545" -H "Content-Type: application/json" -i "https://api.devicehub.net/v2/project/370/device/d3f94cb1-3f34-4f7b-9044-26cc0c10b29e/actuator/mrs_actuator/state" -d '{"state":1}'

JSON Data Example

{
  "state": 1,
  "timestamp": 1430905326.2,
  "meta":{
    "user_meta_key1": "user_meta_value1",
    "user_meta_key2": "user_meta_value2",
    "protocol": "custom_user_protocol",
  }
}

Requests Parameters

Field name Data Type Notes
state integer Required. The actuator state to be sent. Its type and value varies depending on the actuator’s type.
timestamp POSIX timestamp Optional. A user-selectable timestamp attached to the data entry.
meta JSON Optional. A meta field created by the user. If it is included and contains a protocol field, it shall be attached to the data entry. If it is omitted or does not contain a protocol field, the server will generate the field automatically.

Response

{"request_status":1}

MQTT - Actuator state endpoint

Host: mqtt.devicehub.net
Topic: /a/[api_key]/p/[project_id]/d/[device_id]/actuator/[actuator_name]/state

Sending Actuator state

Sending the current actuator state is done by publishing a JSON message using the same format as the one used for the REST endpoints.

Example Usage

mosquitto_pub -h mqtt.devicehub.net -p 1883 -t "/a/1f3dc5c-3f05-47bd-836b-cb0b85d11545/p/370/d/d3f94cb1-3f34-4f7b-9044-26cc0c10b29e/actuator/mrs_actuator/state" -m '{"state":1}' -r

Note that if you are not using the official devicehub libraries (ie, if you’re using mosquitto_pub as in the above example) you must mark the message for retention (in the above example, the -r parameter), otherwise the message will not be stored on the MQTT broker for new subscribers (your data will still reach the api servers, though).

JSON Data Example
The data format is identical to the one used for the REST JSON endpoint and mai contain a metadata field.

{
  "state": 1,
  "timestamp": 1430905326.2
}

Requests Parameters

Field name Data Type Notes
state integer Required. The actuator state to be sent. Its type and value varies depending on the actuator’s type.
timestamp POSIX timestamp Optional. A user-selectable timestamp attached to the data entry.

Receiving Actuator state

Receiving actuator state changes is done simply by subscribing to the topic and listening for messages as they are sent. Note that newly-subscribed clients will only receive the last state that was sent marked for retention (this is only an issue for messages published by means other than the official devicehub libraries).

Example Usage

mosquitto_sub -h mqtt.devicehub.net -p 1883 -t "/a/1f3dc5c-3f05-47bd-836b-cb0b85d11545/p/370/d/d3f94cb1-3f34-4f7b-9044-26cc0c10b29e/actuator/mrs_actuator/state"

Example message
An example message as sent by the MQTT broker.

{"state": 1,"timestamp": 1430905326.2}

MQTT - Sensor data endpoint

Host: mqtt.devicehub.net
Topic: /a/[api_key]/p/[project_id]/d/[device_id]/sensor/[sensor_name]/data

Sending Sensor data

Sending sensor data is done by publishing a JSON message using the same format as the one used for the REST endpoints.

Example Usage

mosquitto_pub -h mqtt.devicehub.net -p 1883 -t "/a/1f3dc5c-3f05-47bd-836b-cb0b85d11545/p/370/d/d3f94cb1-3f34-4f7b-9044-26cc0c10b29e/sensor/mr_sensor/data" -m '{"value":1}' -r

Note that if you are not using the official devicehub libraries (ie, if you’re using mosquitto_pub as in the above example) you must mark the message for retention (in the above example, the -r parameter), otherwise the message will not be stored on the MQTT broker for new subscribers (your data will still reach the api servers, though).

JSON Data Example
The data format is identical to the one used for the REST JSON endpoint and mai contain a metadata field.

{
  "value": 1,
  "timestamp": 1430905326.2
}

Requests Parameters

Field name Data Type Notes
value varies Required. The sensor value to be sent. Its type and value varies depending on the sensor’s type.
timestamp POSIX timestamp Optional. A user-selectable timestamp attached to the data entry.

Receiving Sensor data

Receiving sensor data is done by subscribing to the topic and listening for messages as they are sent.
Note that currently only data sent via MQTT is published to this topic (data sent via REST is currently only available on the REST endpoints).

Example Usage

mosquitto_sub -h mqtt.devicehub.net -p 1883 -t "/a/1f3dc5c-3f05-47bd-836b-cb0b85d11545/p/370/d/d3f94cb1-3f34-4f7b-9044-26cc0c10b29e/sensor/mr_sensor/data"

Example Message

{"value": 1, "timestamp": 1430905326.2}