NAV
javascript

Введение

Добро пожаловать на страницу документации GreenPL API. Вы можете использовать наш API для доступа к нашему серверу, к примеру, получить информацию об устройствах, переменных, принятых значениях из базы данных. Кроме того, с помощью протокола MQTT вы сможете подключить устройство (Intel Edison, Arduino, Raspberry PI) к платформе GreenPL.

На текущий момент мы подготовили MQTT API с примерами использования на языке программирования JavaScript - Node.js. Вы легко сможете настроить ваш контроллер для работы по протоколу MQTT (библиотека реализована для большинства распространенных аппаратных платформ). Вскоре появятся готовые примеры по подключению Arduino, Raspberry Pi и NodeMCU.

MQTT

Что такое MQTT?

MQTT (Message Queue Telemetry Transport) - это легковесный, упрощенный и быстродействующий протокол, разработанный специально для “Интернета вещей”. Разработчики протокола поставили цель сделать его простым, достаточно функциональным для обмена данными между устройствами и удобно внедряемым. Уже сейчас написаны библиотеки на разных языках программирования для работы с MQTT. За счет асинхронности, сжатых сообщений и простоты реализации протокол идеально подходит для использования во встроенных устройствах.

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

Аутентификация (auth)

Чтобы авторизовать устройство, используйте этот код:

//подключаем стандартную библиотеку MQTT
var mqtt = require("mqtt");
//создаем подключение к серверу GreenPL, используя имя пользователя и пароль (поля username и password следует заменить на свои данные)
var client  = mqtt.connect('mqtt://api.greenpl.ru', {username:'g1gfg7f4fc361afcaf5bf10f', password:"1"});

Не забудьте заменить значение поля username на свой токен.

Наш MQTT брокер доступен по адресу: api.greenpl.ru порт:1883

Чтобы взаимодействовать с брокером вам понадобится токен, который необходимо использовать в качестве имени пользователя. Для получения токена перейдите в Настройки -> API -> раздел Токены. Скопируйте один из доступных токенов.

Как получить токен для аутентификации

Данные для MQTT аутентификации

Поле Значение
username ваш токен
password любое значение

Если соединение установлено, вы можете публиковать или подписываться на MQTT топики, в другом случае брокер вернет ошибку и отключит клиента.

Публикация значений (publish)

// подключаем стандартную библиотеку MQTT
const mqtt = require("mqtt");

// создаем подключение к серверу GreenPL, используя имя пользователя и пароль
var client  = mqtt.connect('mqtt://api.greenpl.ru', {username:'g1gfg7f4fc361afcaf5bf10f', password:"1"});

// формируем объект, содержащий показания с датчиков
var varsPublish = {"temperature": 10, "himidity": {"value":10}, "wind_speed": {"value": 11, "timestamp":1508494147000}};

// преобразуем объект в JSON документ
var json = JSON.stringify(varsPublish);

// публикуем документ на сервер GreenPL
client.publish("/v0.2/MQTT_ID/devices/API_Label_устройства", json, {"qos": 1, "retain": false},
    function (error, response) {
    // выводим в консоль ответ сервера
        console.log(response);
    });

Публикация значений в устройство (publish to device)

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

/v0.2/{MQTT_ID}/devices/{API Label устройства}

MQTT ID вы можете получить в настройках в разделе API: Как получить MQTT ID

MQTT ID используется в топике для однозначной идентификации клиента, который собирается опубликовать сообщение или подписаться на топик. Мы используем отдельное, отличное от Токена, значение, чтобы обеспечить безопасность. Без Токена MQTT ID бесполезен.

API Label устройства вы увидете в карточке устройства: Как получить API Label устройства

В качестве адреса сервера используйте mqtt://api.greenpl.ru.

В качестве сообщения MQTT должен выступать JSON код, где каждый ключ соответствует уникальной метке (API Label) каждой переменной.

Значение может быть любым из следующих:

{"temperature": 25, "humidity": 75}

{"temperature": {"value":10, "timestamp": 1508494147000, "context":{"my-comment": "Тестируем датчик", "latitude":70.9, "longitude": 70.9}}, "humidity": 50}

Описание ключей “value”, “timestamp” и “content”:

Ключ Описание
value (обязательный) Целое или дробное значение, например: "value" : 25.7, или "value" : 15
context JSON объект с дополнительными данными в виде пары “ключ”:“значение”. К примеру, "context": { "state" : "active", "latitude":70.9, "longitude": 70.9}. Кстати, latitude и longitude - это координаты, которые можно использовать для геопозиционирования вашего устройства!
timestamp Дополнительная метка времени в миллисекундах, согласно стандарту POSIX. Можно использовать, если вы хотите отправить значение задним числом (например, не было интернета). Использование: "timestamp" : 1508497209000. Следует использовать формат timestamp с миллисекундами (13-значное число). Получить timestamp из привычных нам даты и времени можно на сайте: EpochConverter.

Публикация значений в одну переменную (to one variable)

// подключаем стандартную библиотеку MQTT
const mqtt = require("mqtt");

// создаем подключение к серверу GreenPL, используя имя пользователя и пароль
var client  = mqtt.connect('mqtt://api.greenpl.ru', {username:'g1gfg7f4fc361afcaf5bf10f', password:"1"});

client.publish("/v0.2/MQTT_ID/devices/API_Label_устройства/API_Label_переменной",
'{"value": 10.3}', {"qos":1, "retain":false},
function(err, response){
  console.log(response);
});

Вы с легкостью можете отправлять значения лишь в одну конкретную переменную. Тогда топик MQTT слегка изменится и будет выглядеть следующим образом:

/v0.2/{MQTT_ID}/devices/{API Label устройства}/{API Label переменной}

Запросы по прежнему следует направлять по адресу:

mqtt://api.greenpl.ru

API Label переменной можно заполучить таким образом: Как получить API Label переменной

В качестве сообщения должен выступать JSON код. Вот пара примеров:

{"value":10}

или, например,

{"value":25, "timestamp": 1508494147000, "context" : { "state" : "active", "latitude":70.9, "longitude": 70.9}

Как вы видете, все ключи аналогичны ключам из предыдущего примера. Подробнее о них вы можете прочитать выше.

Подписка на значения (subscribe)

var mqtt = require("mqtt");
var client  = mqtt.connect('mqtt://api.greenpl.ru', {username:'g1gfg7f4fc361afcaf5bf10f', password:"1"});
client.subscribe({"/v0.2/MQTT_ID/devices/API_Label_устройства/API_Label_переменной": 1}, function(err, granted) {
  console.log(granted);
});
client.on('message', function(topic, message, packet) {
    //в этом месте напишите обработчик значений, отправленных вам MQTT брокером GreenPL
});

После успешной аутентификации устройство успешно подпишется на изменения значений переменной, которые отправляются по этому топику.

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

mqtt://api.greenpl.ru,

используя топик:

/v0.2/{MQTT_ID}/devices/{API Label устройства}/{API Label переменной}

Если по данному топику будет передано какое-либо сообщение, оно будет получено устройством, подписанным на этот топик.

К примеру, на платформе во вкладке условия GreenPL условия было сформировано условие, которое отправляет значение {"value" : 1} по топику /v0.2/{MQTT_ID}/devices/greenhouse_actuators/light, то устройство получит значение именно в виде {"value" : 1}.

Это добавляет гибкость, так как вы можете передавать любые сообщения и подписываться на них.