Статьи / KA064 / API Ke-Облака: Управляем модулем URL ссылкой

Напомним, что технология 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 C^o.

URL ссылку можно в том числе сохранить в заметках смартфона:

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

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