Статьи / KA064 /
API Ke-Облака: Управляем модулем URL ссылкой
§ 64. API Ke-Облака: Управляем модулем URL ссылкой
|
Дмитрий Иванов, 15 Марта 2023
|
Напомним, что технология Ke-Облако позволяет удаленно взаимодействовать с модулями KernelChip
(получать показания датчиков, передавать команды управления) даже
если у модуля нет “белого” внешнего IP и прямой доступ к нему из глобальной сети отсутствует (находится за NAT).
Подробное описание того как начать работу с Облаком представлено в предыдущих статьях:
Удаленное управление модулем возможно через WEB интерфейс Ke-Облака. Однако, иногда это бывает не совсем удобно (вводить пароли, переходить по
ссылкам в интерфейсе) особенно если на руках у нас смартфон с небольшим экраном. Хотелось бы просто нажать на URL ссылку и
сделать что-то с модулем (запросить текущее показания датчика температуры или включить реле).
А как быть если есть необходимость в автоматизации работы с Облаком? Например, необходим скрипт (JavaScript или PHP) который бы
регулярно скачивал данные модулей или отправлял команды управления через Облако на модуль?
Предположим, что у нас есть модуль Kernelchip, например, Laurent-5. Он подключен к Ke-Облаку и регулярно передает на него данные.
Есть необходимость иногда проверять текущие показания датчика температуры DS18B20 подключенного к модулю а так же иногда
отправлять на него команду включения реле. При этом не хотелось бы пользоваться штатным WEB интерфейсом Облака а использовать готовые URL ссылки.
Ke-Облако предоставляет такую возможность! Это API Облака.
Помимо WEB интерфейса, Ke-Облако предоставляет API (Application Programming Interface)
позволяющий легко интегрировать управление модулями через Облако в ваш софт используя
HTTPS GET запросы.
С помощью API запросов к Облаку можно узнать текущие показания датчиков или отправить команду на
включение реле на модуль используя простую HTTPS ссылку.
HTTPS запросы позволяют управлять модулями через API Ke-Облака из любого софта / программы / скрипта
поддерживающего выполнение GET запросов вне зависимости от типа операционной системы
(Linux, Windows, Android, iOS). Более того, для мобильных ОС (например, Apple iOS) можно избежать
трудоемкой разработки приложения и использовать для этих целей кросс-платформенный HTML+JavaScript
код в виде HTML страницы сохраненной в памяти устройства.
Подробная документация с примерами: Документация API Ke-Облака
Заходим по адресу WEB сервиса Ke-облака: https://kecloud.ru и авторизуемся в нашем аккаунте.
Если у вас нет аккаунта Ke-Облака - см. предыдущие статьи где подробно описано как это можно сделать.
Отлично! Мы успешно авторизовались и вошли в WEB сервис Ke-Облака. Переходим в панель управления. Предполагаем, что в аккаунте уже есть хотя бы один
модуль который передает данные в Облако (если нет - см. ссылки на статьи выше).

В аккаунте сейчас один модуль и он находится на связи (совсем недавно передавал порцию данных). Переходим в него нажав на зеленую стрелочку.
Для того что бы мы могли управлять аппаратными ресурсами модуля необходимо создать
элемент управления
- набор Ke-команд которые будут отправлены модулю при его ближайшем сеансе связи с Облаком.
Нажимаем на ссылку “Добавить элемент управления”. Появится окно в котором нужно задать
список Ke-команд (их может быть несколько; каждая на отдельной строке) и назвать удобным образом этот элемент
управления. На иллюстрации ниже с помощью Ke-команды $KE,REL будет включено 1-ое реле на 10 секунд а потом оно автоматически вернется в выключенное состояние.
Нажимаем на кнопку “Создать”.
$KE,REL,1,1,10

В списке появился вновь созданный элемент управления. Можно проверить его в действии. Нажмем на кнопку "Добавить в очередь".

При ближайшем подключении модуля к Облаку, Ke-команды из элемента управления будут отправлены модулю.

На графике состояния 1-го реле можно удаленно увидеть его включение на 10 сек с помощью элемента управления
который мы активировали (добавили в очередь на отправку).

Теперь приступим непосредственно к решению целевой задачи а именно управлению реле и опросу датчика температуры с помощью URL ссылки.
Для этого необходимо разрешить
использование API
на данном модуле. Переходим в раздел настроек модуля в WEB интерфейсе Ke-Облака.

В настройках модуля необходимо разрешить использование API. Дополнительно, можно установить
пароль API .
В данном случае, установлен пароль "password". В конце нужно нажать на кнопку "Сохранить".

Вернувшись обратно в панель управления модулем, можно убедиться в том что изменения сохранены успешно, API разрешен к использованию.

Для управления реле модуля через API, воспользуемся API командой CMD_RUN.
Для того что бы сформировать URL ссылку нам потребуется:
- ключ модуля (l5IHMJirNW!5FRWlRMFuhgZmS8SXSd2m)
- пароль API (password)
- идентификатор AKA (ak2ZZWSQpaJnfaAz) элемента управления который мы хотим активировать (добавить в очередь)
Формируем URL ссылку с параметрами:
https://kecloud.ru/api.php?key=l5IHMJirNW!5FRWlRMFuhgZmS8SXSd2m
&act=cmd_run&aka=ak2ZZWSQpaJnfaAz&psw=password
Если открыть эту URL ссылку в WEB браузере, то API запрос будет отправлен в Облако. От Облака будет получен ответ в JSON формате (JSON - формат ответа по умолчанию),
сообщающий о том что запрос выполнен успешно, Ke-команды из элемента управления поставлены в очередь на отправку к
модулю и будут переданы ему во время его ближайшего сеанса связи с Облаком.

JSON ответ:
{
"response": {
"error": "0",
"type": "cmd_run",
"time": "1677835149"
}
}
Для того что бы узнать последние показания 1-Wire температуры датчика DS18B20 с ID=28AEB9D0622106DE подключенного к модулю, воспользуемся API командой
DATA.
Используем дополнительные параметры в запросе sns=owi_temp и sid равный ID датчика температуры.
https://kecloud.ru/api.php?key=l5IHMJirNW!5FRWlRMFuhgZmS8SXSd2m
&act=data&psw=password&sns=owi_temp&sid=28AEB9D0622106DE

JSON ответ:
{
"response": {
"error": "0",
"type": "data",
"from": "0",
"to": "0",
"sns": "owi_temp",
"sid": "28AEB9D0622106DE",
"utc": "1",
"time": "1678439494"
},
"data": [{
"t": "1678439492",
"dd": "24.25"
}]
}
В ответ на такой API запрос, Облако найдет самый "свежий" набор данных в хранилище.
На момент времени 1678439492 (UNIX UTC метка времени 10-Mar-2023 09:11:32 UTC или 10-Mar-2023 12:11:32 по Московскому времени) показания датчика
температуры составляли 24.25 Co.
URL ссылку можно в том числе сохранить в заметках смартфона:

При необходимости уточнить текущую температуру датчика со смартфона достаточно нажать на эту ссылку и мы получаем актуальный набор данных в JSON формате:

© Дмитрий Иванов
15 Марта 2023 года
https://kernelchip.ru