Основы взаимодействия контроллера с сервисом

Ключ API

Для того, чтобы контроллер мог взаимодействовать с сервисом, существует понятие - ключ API: это сочетание букв и цифр, которое автоматически генерируется при добавлении контроллера. Добавив контроллер в сервис, вы сразу увидите этот ключ. Далее всё, что вам будет нужно - это запустить конфигуратор, соединиться с контроллером, нажать кнопку Настройки прошивки - и вписать в соответствующее поле ключ API, не забыв при этом указать правильный часовой пояс, в котором расположен контроллер. После нажатия кнопки Сохранить контроллер будет готов к работе с сервисом.

Интервал опроса

Минимальный интервал опроса сервиса контроллером составляет 5 минут, если контроллер опрашивает сервис чаще - он будет заблокирован в рамках сервиса.

Что передаёт контроллер на сервис

При опросе на входящие задачи контроллер передаёт своё локальное время, часовой пояс, и слепок показаний всех видов датчиков (если вы не хотите отправлять показания датчиков из контроллера - есть опция отключения в конфигураторе, окно Настройки прошивки). После передачи всех данных контроллер получает входящие задачи, если они есть. Если задача выполнена - контроллер уведомляет сервис о её выполнении путём очередного запроса, в котором уже не передаются показания датчиков, а только лишь дата/время и часовой пояс.

Обязательно ли пользоваться нашей прошивкой для доступа к сервису?

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

Формат общения

Данные запрашиваются по HTTP методом POST, от контроллера приходит:
  

• k = (key) ключ для доступа к API;
• s = (status) текущее состояние контроллера (показания датчиков);
• r = (report) - если эта переменная установлена - то это ответ на выполнение команды;
• c = (command) - содержит идентификатор выполненной команды (только если r установлена!).

    
При обращении к сервису контроллер передаёт локальные дату и время, а также таймзону:
      

• d - дата контроллера, в формате DD.MM.YYYY
• t - время контроллера, в формате HH:MM:SS
• z - смещение в минутах от UTC, например, -180 или 120

Формат отсыла команд от сервиса контроллеру

Команды приходят в теле ответа по протоколу HTTP, и имеют следующую структуру:

1. Каждая команда начинается префиксом [~] и заканчивается переводом строки (\r\n)
2. После префикса идёт идентификатор команды на сервисе, после идентификатора - символ #
3. После символа # идёт текст команды, который может быть как прямым текстом команды (CTSET=...), так и известным контроллеру внутренним идентификатором команды;
4. В случае, если используется внутренний идентификатор команды, то перед ним идёт символ ?
5. Если используется внутренний идентификатор команды, то она может содержать дополнительные параметры, следующие после символа ? (например, номер канала полива для включения);
6. По завершению списка команд к выполнению сервер отсылает строку [CMDEND]\r\n

Примеры команд

• [~]1234#CTSET=WATER|ON - команда с ID на сервисе = 1234, значение - включить полив;
• [~]1235#?1 - команда с ID на сервисе = 1235, значение - открыть все окна;
• [~]1236#?7?2 - команда с ID на сервисе = 1236, значение - включить полив на третьем канале.

Список внутренних идентификаторов команд

• 1 - открыть все окна;
• 2 - закрыть все окна;
• 3 - открыть определённое окно (дополнительный параметр - номер окна, нумерация с 0);
• 4 - закрыть определённое окно (дополнительный параметр - номер окна, нумерация с 0);
• 5 - включить полив на всех каналах;
• 6 - выключить полив на всех каналах;
• 7 - включить полив на определённом канале (дополнительный параметр - номер канала полива, нумерация с 0);
• 8 - выключить полив на определённом канале (дополнительный параметр - номер канала полива, нумерация с 0);
• 9 - включить досветку;
• 10 - выключить досветку;
• 11 - включить пин (дополнительный параметр - номер пина);
• 12 - выключить пин (дополнительный параметр - номер пина).

После принятия команды в обработку контроллер запрашивает скрипт, передавая ему идентификатор выполненной команды (полученный от сервера первым параметром команды). Сервер помечает команду как выполненную, только если он получит ответ от контроллера о её успешном выполнении.

Адрес скрипта

Всё просто: http://gardenboss.ru/check