Подключение при помощи Device API

POST http://host:port/api/v1/$ACCESS_TOKEN/telemetry

Пример тела запроса:

1
{
2
  "stringKey": "value1",
3
  "booleanKey": true,
4
  "doubleKey": 42.0,
5
  "longKey": 73,
6
  "jsonKey": {
7
    "someNumber": 42,
8
    "someArray": [1,2,3],
9
    "someNestedObject": {"key": "value"}
10
  }
11
}

Формат сообщений, поддерживаемый платформой при передачи телеметрии от устройства:

• {"key1":"value1", "key2":"value2"}
  или
• [{"key1":"value1"}, {"key2":"value2"}]
  или
• {"ts":1451649600512, "values":{"key1":"value1", "key2":"value2"}}

POST http://host:port/api/v1/$ACCESS_TOKEN/attributes

Пример тела запроса:

1
{
2
  "attribute1": "value1",
3
  "attribute2": true,
4
  "attribute3": 42.0,
5
  "attribute4": 73,
6
  "attribute5": {
7
    "someNumber": 42,
8
    "someArray": [1,2,3],
9
    "someNestedObject": {"key": "value"}
10
  }
11
}

GET http://host:port/api/v1/$ACCESS_TOKEN/attributes?clientKeys=attribute1,attribute2&sharedKeys=shared1,shared2

Пример ответа:

1
{
2
   "client":{
3
      "attribute1":"value1",
4
      "attribute2":true
5
   }
6
}

GET http://host:port/api/v1/$ACCESS_TOKEN/attributes/updates?timeout=20000

Пример ответа:

1
{
2
   "client":{
3
      "attribute1":"value1",
4
      "attribute2":true
5
   }
6
}

GET http://host:port/api/v1/$ACCESS_TOKEN/rpc?timeout=20000

Пример ответа:

1
{
2
  "id": "1",
3
  "method": "setGpio",
4
  "params": {
5
    "pin": "23",
6
    "value": 1
7
  }
8
}

где:

• id - request id, integer request identifier
• method - RPC method name, string
• params - RPC method params, custom json object

Для ответа устройство должно использовать метод POST http://host:port/api/v1/$ACCESS_TOKEN/rpc/$id, где $id - идентификатор из запроса выше. Тело запроса:

1
{
2
   "result":"ok"
3
}

POST http://host:port/api/v1/$ACCESS_TOKEN/rpc

Пример тела запроса:

1
{
2
   "method":"getCurrentTime",
3
   "params":{
4

5
   }
6
}

Пример ответа:

1
{
2
   "time":"2016 11 21 12:54:44.287"
3
}

POST coap://host/api/v1/$ACCESS_TOKEN/telemetry

Пример тела запроса:

1
{
2
    "ts": 1451649600512,
3
    "values": {
4
        "stringKey": "value1",
5
        "booleanKey": true,
6
        "doubleKey": 42.0,
7
        "longKey": 73,
8
        "jsonKey": {
9
            "someNumber": 42,
10
            "someArray": [
11
                1,
12
                2,
13
                3
14
            ],
15
            "someNestedObject": {
16
                "key": "value"
17
            }
18
        }
19
    }
20
}

Формат сообщений, поддерживаемый платформой при передачи телеметрии от устройства:

1
{
2
    "key1": "value1",
3
    "key2": "value2"
4
}

или

1
[
2
    {
3
        "key1": "value1"
4
    },
5
    {
6
        "key2": "value2"
7
    }
8
]

POST coap://host/api/v1/$ACCESS_TOKEN/attributes

Пример тела запроса:

1
{
2
    "attribute1": "value1",
3
    "attribute2": true,
4
    "attribute3": 42.0,
5
    "attribute4": 73,
6
    "attribute5": {
7
        "someNumber": 42,
8
        "someArray": [
9
            1,
10
            2,
11
            3
12
        ],
13
        "someNestedObject": {
14
            "key": "value"
15
        }
16
    }
17
}

GET coap://host/api/v1/$ACCESS_TOKEN/attributes?clientKeys=attribute1,attribute2&sharedKeys=shared1,shared2

Пример ответа:

1
{
2
    "client": {
3
        "attribute1": "value1",
4
        "attribute2": true
5
    }
6
}

GET coap://host/api/v1/$ACCESS_TOKEN/attributes с флагом Observe

Пример ответа:

1
{
2
    "client": {
3
        "attribute1": "value1",
4
        "attribute2": true
5
    }
6
}

GET coap://host/api/v1/$ACCESS_TOKEN/rpc с флагом Observe

Пример ответа:

1
{
2
  "id": "1",
3
  "method": "setGpio",
4
  "params": {
5
    "pin": "23",
6
    "value": 1
7
  }
8
}

где:

• id - request id, integer request identifier
• method - RPC method name, string
• params - RPC method params, custom json object

Для ответа устройство должно использовать метод POST coap://host:port/api/v1/$ACCESS_TOKEN/rpc/$id, где $id - идентификатор из запроса выше. Тело запроса:

1
{
2
   "result":"ok"
3
}

POST coap://host/api/v1/$ACCESS_TOKEN/rpc

Пример тела запроса:

1
{
2
   "method":"getCurrentTime",
3
   "params":{
4

5
   }
6
}

Пример ответа:

1
{
2
   "time":"2016 11 21 12:54:44.287"
3
}

При помощи MQTT Device API обеспечивается возможность передавать запросы от сторонних коннекторов (устройств, присоединенных по различным протоколам) в IoT платформу.

Для авторизации необходимо отправить сообщение типа MQTT connect с указанием в payload следующих данных:

Пример кода на JS:

1
import org.eclipse.paho.client.mqttv3.*;
2
public class App {
3
    public static void main(String[] args) throws Exception {
4
      // client, user and device details
5
        final String serverUrl = "tcp://mqtt.mts.ru"; // пример значения
6
        final String username = "$ACCESS_TOKEN"; // пример значения
7
        // MQTT connection options
8
        final MqttConnectOptions options = new MqttConnectOptions();
9
        options.setUserName(username);
10
      // connect the client to platform
11
        final MqttClient client = new MqttClient(serverUrl);
12
        client.connect(options);
13
    }
14

15
}

В примере выше для $ACCESS_TOKEN необходимо подставить значение токена, полученного на шаге создания устройства (содержится в поле “token”, например generatedToken-e53d7b39-11c8-4ae4-8363-474df9325262).

• Path: v1/devices/me/telemetry
• Описание: отправка телеметрии от устройств

Чтобы устройство могло передавать на платформу значения собираемой телеметрии, необходимо:

1. убедиться что сервис, после успешной авторизации устройства, может принимать телеметрию в MQQT-топик v1/devices/me/telemetry;
2. проверить корректность формата;
3. дополнить временной меткой (timestamp), если она не передана;
4. передать сообщение в kafka брокер, топик NETWORK.TOPIC.TELEMETRY.IN.

Ожидаемые форматы сообщений:

1
{
2
  "ts": 1451649600512,
3
  "values": [{"key1":"value1"}, {"key2":"value2"}]
4
}

или

1
{
2
  "ts": 1451649600512,
3
  "values": {"key1":"value1", "key2":"value2"}
4
}

В случае, если не передан timestamp (поле ts), необходимо дополнить JSON:

1
{
2
  "ts": <ts значение в UNIX EPOCH формате>,
3
  "values": {"key1":"value1", "key2":"value2"}
4
}

• Path: v1/devices/me/attributes
• Описание: отправка обновлений атрибутов устройств

Чтобы устройство могло передавать на платформу значения собственных атрибутов, необходимо:

1. убедиться что сервис, после успешной авторизации устройства, может принимать телеметрию в MQQT-топик v1/devices/me/attributes;
2. проверить корректность формата;
3. передать сообщение в Kafka брокер, топик NETWORK.TOPIC.ATTRIBUTES.IN.

Ожидаемые форматы сообщений:

1
{
2
  "attribute1": "value1",
3
  "attribute2": true,
4
  "attribute3": 42.0,
5
  "attribute4": 73,
6
  "attribute5": {
7
    "someNumber": 42,
8
    "someArray": [1,2,3],
9
    "someNestedObject": {"key": "value"}
10
  }
11
}