Searching...

Matching results

Using REST with AirVantage

This section describes the AirVantage API that can be used by devices to send data in AirVantage (southbound). If you need to use the AirVantage APIs to integrate with a Web application or enterprise software, please refer to the AirVantage northbound API here .

Introduction

This article explains the different steps to create an device application (embedded or PC) using simple HTTP REST API to send data and receive commands from AirVantage.

Specifications

Protocol Configuration

• Port: 80 or 443
• Url: http(s)://eu.airvantage.net/
• Default auth user: Serial Number (but IMEI can be used as well)
• Ressources:
  • device/messages for the communication from the device to AirVantage.
  • device/tasks for the communication from AirVantage to the device.

The content header must be defined:

‘Content-type’: ‘application/json’

Supported Data type

double, int, string, boolean, binary and date.

Json Format (New)

To use this format you need to include the HTTP header “Device-REST-Version” with the value “2”.

Data sending

{ "<timestamp>": { "<dataname>": <value>, "<dataname>": <value>}, ... }

• timestamp: nb of millisecond since 01/01/1970. Optional.
• dataname: full path starting with the asset-id
• value: string value must be quoted, boolean value must be true or false.

Example:

<asset default-label="My Machine" id="machine">
     <variable default-label="Temperature" path="temperature" type="double"/>
     <variable default-label="Humidity" path="humidity" type="double"/>

     <setting default-label="Threshold" path="threshold" type="int"/>
</asset>

{ "1349907137000": { "machine.temperature": 23.2, "machine.humidity": 70 },
  "1349908137000": { "machine.temperature": 24.5 },
  "1349909137000": { "machine.temperature": 22.9 },
  "1349907137000": { "machine.threshold": 30}
}

As the timestamp value is optional, the format can be:

{ "machine.temperature": 23.2, "machine.humidity": 70 }

When the server will received the values, it will add a timestamp.

Read or Write Tasks sending

[
   {
      "uid" : "<uid>",
      "timestamp" : <timestamp>,
      "<command>" : ["<dataname>", ...]
    }
]

• uid:job universal identifier
• timestamp: see above
• dataname: full path with asset-id to identify the setting
• command: can be read or write

A single task can be sent at the time.

Example:

[
  {
    "uid" : "3c12547b613740adb686271bdc8f097c",
    "timestamp" : 1348836320188,
    "read" : ["machine.temperature"]
  }
]

or

[
  {
    "uid": "8006cc58ba2141f69161a78f1bfdea1d",
    "timestamp": 1348836320566,
    "write" : [{"machine.threshold" : 25}}]
  }
]

Customer commands sending

[
   {
      "uid" : "<uid>",
      "timestamp" : <timestamp>,
      "command" : {"id": "<command-id",
                   "params": {"<param-name>":"<param-value", ...}
                      }
    }
]

• uid:job universal identifier
• timestamp: see above
• command-id: full path with asset-id to identify the command.
• param-name: name of the parameter.
• param-value: value of the parameter

A single command can be sent at the time.

Example:

<asset default-label="My Machine" id="machine">
     <command path="sendMessage" default-label="send Message">
          <parameter id="message" default-label="Message" type="string" />
     </command>
</asset>

[
   {
      "uid" : "e87b35c3c2e2417b902277ff9d049d70",
      "timestamp" : 1416324560869,
      "command" : {"id": "machine.sendMessage",
                   "params": {"message":"Hello World!"}
                      }
    },
    ...
]

Json Format (Old)

[ { "<dataname>": [{ "timestamp": <timestamp>, "value:" <value>}, ...], "<dataname>": ... } ]

• timestamp: nb of millisecond since 01/01/1970
• dataname: full path starting with the asset-id
• value: string value must be quoted, boolean value must be true or false.

Example:

[{
    "machine.temperature": [{
      "timestamp" : new Date().getTime(),
      "value" : "42.2"
    },
    {
      "timestamp" : new Date().getTime(),
      "value" : "24.5"
    },
    {
      "timestamp" : new Date().getTime(),
      "value" : "42.9"
    }]
  },
  {
    "machine.threshold": [{
      "timestamp" : new Date().getTime(),
      "value" : "30"
    }]
  }]

Tasks sending

See new JSON format

Samples code

Some samples are available:

• Using REST with an raspberry Pi in python, see this tutorial .
• If you don’t find your device in this list, have a look to this tutorial .