Введение
Добро пожаловать на страницу документации GreenPL API. Вы можете использовать наш API для доступа к нашему серверу, к примеру, получить информацию об устройствах, переменных, принятых значениях из базы данных. Кроме того, с помощью протокола MQTT вы сможете подключить устройство (Intel Edison, Arduino, Raspberry PI) к платформе GreenPL.
На текущий момент мы подготовили MQTT API с примерами использования на языке программирования JavaScript - Node.js. Вы легко сможете настроить ваш контроллер для работы по протоколу MQTT (библиотека реализована для большинства распространенных аппаратных платформ).
MQTT
Что такое MQTT?
MQTT (Message Queue Telemetry Transport) - это легковесный, упрощенный и быстродействующий протокол, разработанный специально для “Интернета вещей”. Разработчики протокола поставили цель сделать его простым, достаточно функциональным для обмена данными между устройствами и удобно внедряемым. Уже сейчас написаны библиотеки на разных языках программирования для работы с MQTT. За счет асинхронности, сжатых сообщений и простоты реализации протокол идеально подходит для использования во встроенных устройствах.
Для тестирования и отладки программ, передающих данные по MQTT мы рекомендуем воспользоваться программами и ресурсами:
- MQTT Lens: расширение для браузера Google Chrome, позволяющее подключаться к MQTT брокеру (серверу). Приложение позволяет подписаться и отправить данные на определенный топик (путь, являющихся адресом для доставки значений). Если вы используете MQTT Lens для тестирования API сервиса, то в поле password вы можете ввести любое значение (аутентификация осуществляется по username).
- MQTT Box: кроссплатформенное приложение (Windows, Linux, macOS), позволяющее подключиться к MQTT брокеру по WebSocket/MQTT. Удобные карточки для отправки и приема данных, а также высокая стабильность самого приложения - это положительный аргумент для IoT разработчика, крайне рекомендуем установить и использовать для отладки приложений и работы устройств.
Аутентификация (auth)
Чтобы авторизовать устройство, используйте этот код:
//подключаем стандартную библиотеку MQTT var mqtt = require("mqtt"); //создаем подключение к серверу GreenPL, используя имя пользователя и пароль (поля username и password следует заменить на свои данные) var client = mqtt.connect('mqtt://mqtt.greenpl.ru', {username:'g1gfg7f4fc361afcaf5bf10f', password:"1"});
Не забудьте заменить значение поля username на свой токен.
Наш MQTT брокер доступен по адресам:
mqtt://mqtt.greenpl.ru порт:1883 - для подключения по MQTT/TCP
ws://mqtt.greenpl.ru порт 80 - для подключения по WebSocket
Чтобы взаимодействовать с брокером вам понадобится токен, который необходимо использовать в качестве имени пользователя. Для получения токена перейдите в Настройки -> API -> раздел Токены. Скопируйте один из доступных токенов.
Данные для MQTT аутентификации
| Поле | Значение |
|---|---|
| username | ваш MQTT API токен |
| password | любое значение |
Если соединение установлено, вы можете публиковать или подписываться на MQTT топики, в другом случае брокер вернет ошибку и отключит клиента.
Публикация значений (publish)
// подключаем стандартную библиотеку MQTT const mqtt = require("mqtt"); // создаем подключение к серверу GreenPL, используя имя пользователя и пароль var client = mqtt.connect('mqtt://mqtt.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("/devices/API_Label_устройства", json, {"qos": 1, "retain": false}, function (error, response) { // выводим в консоль ответ сервера console.log(response); });
Публикация значений в устройство (publish to device)
Для того, чтобы отправить несколько значений в одно устройство, необходимо использовать такой вид топика:
/devices/{API Label устройства}
API Label устройства вы увидете в карточке устройства:
В качестве адреса сервера используйте mqtt://mqtt.greenpl.ru.
В качестве сообщения MQTT должен выступать JSON код, где каждый ключ соответствует уникальной метке (API Label) каждой переменной.
Значение может быть любым из следующих:
- Целое или дробное число, например:
{"temperature": 25, "humidity": 75.24}
- JSON объект, содержащий ключи: “value”, “context” и “timestamp”. Например:
{"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://mqtt.greenpl.ru', {username:'g1gfg7f4fc361afcaf5bf10f', password:"1"}); client.publish("/devices/API_Label_устройства/API_Label_переменной", '{"value": 10.3}', {"qos":1, "retain":false}, function(err, response){ console.log(response); });
Вы с легкостью можете отправлять значения лишь в одну конкретную переменную. Тогда топик MQTT слегка изменится и будет выглядеть следующим образом:
/devices/{API Label устройства}/{API Label переменной}
Запросы по прежнему следует направлять по адресу:
mqtt://mqtt.greenpl.ru
Полный топик переменной можно заполучить таким образом:
В качестве сообщения должен выступать JSON код или численное значение. Вот несколько примеров:
{"value":10}
или, например,
{"value":25, "timestamp": 1508494147000, "context" : { "state" : "active", "latitude":70.9, "longitude": 70.9}
или
25.64 - в этом случае сервер форматирует значение. Если вы подпишитесь на этот топик, тогда
вам вернется JSON вида:
{"value" : 25.64, "timestamp" : 1508494147000}
Как это работает:
Подписка на значения (subscribe)
var mqtt = require("mqtt"); var client = mqtt.connect('mqtt://mqtt.greenpl.ru', {username:'g1gfg7f4fc361afcaf5bf10f', password:"1"}); // подписываемся на получение численного значения без JSON. Гарантированная доставка. client.subscribe({"/devices/API_Label_устройства/API_Label_переменной/lv": 1}, function(err, granted) { console.log(granted); }); // подписываемся на получение объекта JSON. Доставка только в случае публикации на этот топик. client.subscribe({"/devices/API_Label_устройства/API_Label_переменной": 1}, function(err, granted) { console.log(granted); }); client.on('message', function(topic, message, packet) { // в этом месте напишите обработчик значений, отправленных вам MQTT брокером GreenPL });
После успешной аутентификации устройство успешно подпишется на изменения значений переменной, которые отправляются по этому топику.
Чтобы подписаться на изменения значений переменной, используйте следущий адрес:
mqtt://mqtt.greenpl.ru,
Есть несколько способов получить значения:
* Подписка на последнее значение (lv). Топик будет выглядить примерно так: /devices/API_Label_устройства/API_Label_переменной/lv. Самый надежный способ получить значение: на какой бы доступный топик не было бы отправлено значение, оно будет получено на топике с lv в конце.
* Подписка на топик переменной. Топик выглядит так: /devices/API_Label_устройства/API_Label_переменной. Значение будет в форматированном JSON-виде и придет только в том случае, если было отправлено в точности на этот топик.
* Подписка на /devices/API_Label_устройства. В этом случае вы получите данные только в том случае, если они были отправлены в точности на этот топик в формате, который вы задали сами. Например, {"temp" : 24, "hum" : 69}.
* Подписка на группу топиков /devices/#. Решетка в конце означает, что вы подписались на все топики, которые начинаются с “/devices”. Таким образом, вы можете подписаться и на подобные топики: /devices/API_Label_устройства/# и даже на /#.
Для чего нужно подписываться?
Если устройство подписано на какой-либо топик, оно отслеживает все данные, которые по нему передаются. Таким образом, на топик можно отправлять различные команды, а устройство будет их отслеживать и выполнять.
К примеру, если на платформе во вкладке Простые условия было сформирован сценарий, который отправляет значение {"value" : 1} по топику /devices/greenhouse_actuators/light, то устройство получит значение именно в виде {"value" : 1, "timestamp" : 1508497209000}. При этом, если устройство подписано на топик /devices/greenhouse_actuators/light/lv, тогда будет получено значение 1.
Это добавляет гибкость, так как вы можете передавать любые сообщения и подписываться на них.