/*-------------------------------------------------------------------------------------------------------------------------------------------------------------- 15.12.2020 w5277c@gmail.com Начало 16.12.2020 w5277c@gmail.com Дополнил 17.12.2020 w5277c@gmail.com Добавил COMMAND и INFORM --------------------------------------------------------------------------------------------------------------------------------------------------------------*/ Здесь описывается API клиент-сервера на базе JSON поверх TCP, порт 5281(5277+4) Также сервер работает по внутреннему проприетарному бинарному протоколу (TCP порт 5277) Также будут доступны подключения JSON на базе HTTP(TCP порт 5277+1), HTTPS(TCP порт 5277+2) и WebSocket(TCP порт 5277+3) Кроме этого есть различные точки доступа типа Telegram, Алиса, Email и т.п., они будут описаны отдельно. Общая структура пакета: В заголовок входит: - порядковый номер запроса (размерностью в 2 байта, т.е. 0-65535) - признак запроса - код функции или ответа (см. function_and_response_codes.txt) Пример: {"SN":5,"CODE":71,"REQUEST":true,"BODY":{"SESSION_ID":2167050134516977715,"LOCATION_ID":18}} Дальнейшее описание буду приводить без заголовка, только тело. На данный момент разрешена работа на базе JSON (TCP порт 5281) на серверах: - stud.dipexlab.ru (домен будет доступен в ближайшее время) - 5277.ru -------------------------------------------------------------------------------------------------------------------------------------------------------------- LOGIN - Авторизация пользователя -------------------------------------------------------------------------------------------------------------------------------------------------------------- Запрос: {"EMAIL":"mail@mail.ru","LOGIN":"","HASH":"001122...aabbccddeeff","VERSION":"1.3|0.0.2|w","OS":"Android 10(29)","DEVICE":"HWPOT-H","MODE":1} Структура запроса: Обязательные: EMAIL - email адрес проекта LOGIN - логин пользователя, владелец проекта может оставить пустым либо указать 'admin' HASH - MD5 хеш пароля в шестнадцатеричном виде Не обязательные: VERSION - строка текста с информацией о версии клиента и основных библиотек (к примеру версия клиента | верcия основной библиотеки | тип клиента) LOCATION_ID - идентификатор(число) активной локации (сервер информирует о событиях только активной локации) DATABASE_TIMESTAMP - метка времени(число) последних модификаций БД, известной клиенту. Если данные актуальны, то сервер не будет передавать срез БД клиенту. OS - строка текста с описанием типа ОС MODE - режим работы клиента(число): 0 - асинхронный, сервер информирует клиентов по установленному соединению без задержек, используется по умолчанию. 1 - синхронный, клиент сам запрашивает у сервера всю информацию. 2 - только авторизация. Сервер не передает в ответе обновленные данные проекта, словаря и прочее (как в предыдущих пунктах) и не передает в дальнейшем ничего клиенту. Режим полезен для простых утилит выполняющих к примеру только сбор показаний и управление устройствами. Ответ: {"SN":1,"CODE":8,"BODY":{"SESSION_ID":5549539372304463122,... {"SESSION_ID":5549539372304463122,"TTL":1800000,"LANG_ID":2, "LOCATIONS":[ {"ID":18,"NAME":"Гараж","COMMENT":"","IS_LINK":false,"INTERROGATE_PERIOD_ID":4,"PLACES":[], "DEVICES":[ {"ID":243,"TYPE_ID":65539,"NAME":"Термометр","PLACE_ID":null,"COMMENT":"","INTERROGATE_PERIOD_ID":0,"DISABLED":false,"PARAMS":[]}, {"ID":244,"TYPE_ID":65543,"NAME":"Ворота","PLACE_ID":null,"COMMENT":"","INTERROGATE_PERIOD_ID":0,"DISABLED":false, "PARAMS":[ {"ID":1008,"PARAM_ID":45,"VALUE":"","SUBTYPE_ID":16777321}, {"ID":1005,"PARAM_ID":10,"VALUE":"MSwyLNCU0LLQtdGA0Yw=","SUBTYPE_ID":16777321}, {"ID":1006,"PARAM_ID":42,"VALUE":"MA==","SUBTYPE_ID":16777321}, {"ID":1007,"PARAM_ID":12,"VALUE":"NDA0MDQw","SUBTYPE_ID":16777321}]} ,{"ID":245,"TYPE_ID":589825,"NAME":"Символьный дисплей","PLACE_ID":null,"COMMENT":"","INTERROGATE_PERIOD_ID":0,"DISABLED":true, "PARAMS":[ {"ID":1009,"PARAM_ID":10,"VALUE":"0KLQtdC60YHRgg==","SUBTYPE_ID":16777320}, {"ID":1010,"PARAM_ID":42,"VALUE":"MA==","SUBTYPE_ID":16777320}, {"ID":1011,"PARAM_ID":12,"VALUE":"NDA0MDQw","SUBTYPE_ID":16777320}, {"ID":1012,"PARAM_ID":45,"VALUE":"","SUBTYPE_ID":16777320}, {"ID":1013,"PARAM_ID":41,"VALUE":"MTIwMw==","SUBTYPE_ID":null}]}]}, {"ID":12,"NAME":"Тестовая (windows)","COMMENT":"","IS_LINK":false,"INTERROGATE_PERIOD_ID":3,"PLACES":[], "DEVICES":[ {"ID":222,"TYPE_ID":131093,"NAME":"Герконовое реле х8","PLACE_ID":null,"COMMENT":"5410ecfffea09669","INTERROGATE_PERIOD_ID":0,"DISABLED":false, "PARAMS":[ {"ID":869,"PARAM_ID":7,"VALUE":"NTQxMGVjZmZmZWEwOTY2OQ==","SUBTYPE_ID":null}]}]}]} Структура ответа: SESSION_ID - идентификатор сессии, все последующие запросы должны его содержать. TTL - время жизни сессии в миллисекундах. Сессия будет закрыта, если в течении этого времени сервер не получит ни одного запроса. LANG_ID - идентификатор языка пользователя. 1 - eng 2 - rus LOCATIONS - список локаций. Структура локации: ID - идентификатор локации (число) NAME - строка текста с названием локации COMMENT - строка текста с комментарием локации IS_LINK - признак локации из другого проекта (булевое значение) INTERROGATE_PERIOD_ID - идентификатор режима опроса устройств (число) по умолчанию 0 - BY_LOCATION 1 - PER_MINUTE(60 * 1000) 2 - PER_5_MINUTE(5 * 60 * 1000) 3 - PER_10_MINUTE(10 * 60 * 1000) 4 - PER_15_MINUTE(15 * 60 * 1000) 5 - PER_HALF_HOUR(30 * 60 * 1000) 6 - PER_HOUR(1 * 60 * 60 * 1000) 7 - PER_3_HOURS(3 * 60 * 60 * 1000) 8 - PER_6_HOUR(6 * 60 * 60 * 1000) 9 - PER_12_HOUR(12 * 60 * 60 * 1000) 10 - PER_DAY(1 * 24 * 60 * 60 * 1000) PLACES - список помещений внутри локации Структура помещения: ID - идентификатор локации (число) NAME - строка текста с названием локации ICON - имя файла иконки (внутренний ресурс клиента) COMMENT - строка текста с комментарием локации DEVICES - список устройств внутри локации Структура устройства: ID - идентификатор устройства (число) TYPE_ID - идентификатор типа устройства (число, таблица e_device_types) NAME - строка текста с названием локации COMMENT - строка текста с комментарием локации PLACE_ID - идентификатор помещения (число), описанный в списке помещений данной локации INTERROGATE_PERIOD_ID - идентификатор режима опроса устройства (число) DISABLED - признак отключенной локации (булевое значение) PARAMS - список параметров устройства Структура параметра: ID - идентификатор параметра (число) PARAM_ID - идентификатор типа параметра (число, таблица e_param_types) VALUE - значение, закодировано BASE64 SUBTYPE_ID - подтип (число), формат значения зависит от PARAM_ID. Подтип используется для хранения нескольких параметров с одинаковыми типами, например для хранения пользовательских названий показаний. Чаще всего имеет вид 0xAABBBBBB, где AA - порядковый номер, BBBBBB - идентификатор типа сущности(например показания) *Также в ответе могут содержаться словари, позже рассмотрю их отдельно. -------------------------------------------------------------------------------------------------------------------------------------------------------------- LOGOUT - закрывает сессию -------------------------------------------------------------------------------------------------------------------------------------------------------------- Запрос: {"SESSION_ID":333357667467917668} Структура запроса: Обязательные: SESSION_ID - идентификатор сессии Ответ: {} -------------------------------------------------------------------------------------------------------------------------------------------------------------- ECHO - поддержка соединения, обновление времени жизни сессии -------------------------------------------------------------------------------------------------------------------------------------------------------------- Запрос: {"SESSION_ID":333357667467917668} Структура запроса: Обязательные: SESSION_ID - идентификатор сессии Ответ: {} -------------------------------------------------------------------------------------------------------------------------------------------------------------- PROJECT_REGISTRATE - регистрация нового проекта. Сервер Высылает письмо с дальнейшими действиями. -------------------------------------------------------------------------------------------------------------------------------------------------------------- Запрос: {"EMAIL":"mail@mail.ru","PROJECT_NAME":"","ADMIN_NAME":"","LANG_ID":2} Структура запроса: Обязательные: EMAIL - email адрес проекта Не обязательные: PROJECT_NAME - строка текста с описанием проекта ADMIN_NAME - строка текста, имя/ФИО админа LANG_ID - идентификатор основного языка админа (число) Ответ: {} -------------------------------------------------------------------------------------------------------------------------------------------------------------- MEASURES_GET - запрос показаний. -------------------------------------------------------------------------------------------------------------------------------------------------------------- Запрос: {"SESSION_ID":333357667467917668,"DEVICES":[240,112,49,50,243,51,244,52,54,230,247,43]} Структура запроса: Обязательные: SESSION_ID - идентификатор сессии Не обязательные: DEVICES - массив чисел, идентификаторы устройств по которым нужны показания. Может отсутствовать, тогда будут выгружены показания всех устройств текущей локации. Ответ: {"ITEMS":[ {"ID":243,"MEASURES":[ {"TYPE_ID":2,"VALUE":"0"}, {"TYPE_ID":3,"VALUE":"1"}, {"TYPE_ID":5,"VALUE":"false"}]}, {"ID":244,"MEASURES":[ {"TYPE_ID":2,"VALUE":"0"}, {"TYPE_ID":3,"VALUE":"1"}, {"TYPE_ID":5,"VALUE":"false"}]}, {"ID":247,"MEASURES":[ {"TYPE_ID":2,"VALUE":"1607916167707"}, {"TYPE_ID":3,"VALUE":"7"}, {"TYPE_ID":5,"VALUE":"true"}, {"TYPE_ID":16777320,"VALUE":"true"}, {"TYPE_ID":100,"VALUE":"9.75"}, {"TYPE_ID":4,"VALUE":"5"}, {"TYPE_ID":103,"VALUE":"4.788"}]}, ... {"ID":54,"MEASURES":[ {"TYPE_ID":2,"VALUE":"1607959440732"}, {"TYPE_ID":3,"VALUE":"7"}, {"TYPE_ID":5,"VALUE":"false"}, {"TYPE_ID":16777321,"VALUE":"true"}, {"TYPE_ID":4,"VALUE":"5"}, {"TYPE_ID":109,"VALUE":"1607944047622"}, {"TYPE_ID":110,"VALUE":"1607944068788"}]}]} Структура ответа: ITEMS - массив элементов Структура элемента: ID - число, идентификатор устройства MEASURES - массив показаний Структура показания: TYPE_ID - число, идентификатор показания, см. measure_types VALUE - значение показания Внутренние/скрытые показания (чей идентификатор менее 100): 1. DEVICE_ID - идентификатор устройства (скорее всего уже артефакт) 2. SHOT_TIMESTAMP - временная метка снимка показаний (миллисекунды) 3. NETWORK_STATUS - сетевое состояние устройства 4. MODE - режим управления устройством, см. e_device_modes 5. EXPIRED - признак устаревшего показания 6. AD - временная метка последних изменений настроек проекта (скорее всего уже артефакт) Сетевые состояния устройства: 1. READY - готов к работе, опроса пока не было 2. INIT_FAULT - не смог инициализироваться (сбой библиотеки устройства/шлюзов) 3. UNREACHABLE - не доступен, 4. INVALID_DATA - получены не корректные данные от устройства 5. UNSTABLE - получена только часть корректных данных 6. COMM_FAULT - ошибка приема/передачи данных 7. OK - устройство работает корректно 8. FAULT - сбой во внутренней логике 9. LIMIT - достигнуто лицензионное ограничение Режимы управления устройством (устройства могут не поддерживать и игнорировать некоторые режимы): 1. LOCKED - запрещено любое управление устройством 2. TRIGGERS - разрешена только внутренняя логика устройства (например реакция на высокую температуру) 3. MANUAL - разрешены предыдущие пункты и ручное управление непосредственно на самом устройстве 4. REMOTE - разрешены предыдущие пункты и удаленное управление, например через шину 5. SCENARIOS - разрешены предыдущие пункты и управление контроллером на базе сценариев *TYPE_ID может иметь значение в виде 0xAABBBBBB, где старший байт AA указывает на порядковый номер показания. Используется, если у устройства несколько одинаковых показаний. См. e_device_measures -------------------------------------------------------------------------------------------------------------------------------------------------------------- LOCATION_HEADERS - Краткая информация(заголовок) о локациях -------------------------------------------------------------------------------------------------------------------------------------------------------------- Запрос: {"SESSION_ID":2167050134516977715} или {"SESSION_ID":2167050134516977715,"EMAIL":"mail@mail.ru","LOGIN":"","HASH":"001122...aabbccddeeff"} Структура запроса: Обязательные: SESSION_ID - идентификатор сессии или также: EMAIL - email адрес проекта LOGIN - логин пользователя, владелец проекта может оставить пустым либо указать 'admin' HASH - MD5 хеш пароля в шестнадцатеричном виде В первом случае данные будут выбраны пользователя сессии, во втором - пользователя чьи авторизационые данные указаны. Ответ: {"ITEMS":[ {"ID":18,"NAME":"Гараж","COMMENT":"","DISABLED":false}, {"ID":21,"NAME":"Аква","COMMENT":"","DISABLED":false}, {"ID":8,"NAME":"Дом","COMMENT":"","DISABLED":false}, {"ID":9,"NAME":"Тестовая (linux)","COMMENT":"","DISABLED":false}, {"ID":12,"NAME":"Тестовая (windows)","COMMENT":"","DISABLED":false}]}} Структура ответа: ITEMS - массив элементов Структура элемента: ID - число, идентификатор локации NAME - название локации COMMENT - комментарий к локации DISABLED - признак заблокированной локации -------------------------------------------------------------------------------------------------------------------------------------------------------------- PLACE_HEADERS - Краткая информация(заголовок) о помещениях в локации -------------------------------------------------------------------------------------------------------------------------------------------------------------- Запрос: {"SESSION_ID":2167050134516977715,"LOCATION_ID":18} Структура запроса: Обязательные: SESSION_ID - идентификатор сессии LOCATION_ID - идентификатор локации Ответ: {"ITEMS":[ {"ID":1,"NAME":"Детская","COMMENT":""}, {"ID":2,"NAME":"Кабинет","COMMENT":""}, {"ID":3,"NAME":"Кухня","COMMENT":""}, {"ID":4,"NAME":"Коридор","COMMENT":""}, {"ID":5,"NAME":"Зал","COMMENT":""}, {"ID":6,"NAME":"Балкон","COMMENT":""}, {"ID":7,"NAME":"Туалет","COMMENT":""}]}} Структура ответа: ITEMS - массив элементов Структура элемента: ID - число, идентификатор помещения NAME - название помещения COMMENT - комментарий к помещению *Кроме того, всегда есть помещение 'Общее' с идентификатором 0 -------------------------------------------------------------------------------------------------------------------------------------------------------------- DEVICE_HEADERS - Краткая информация(заголовок) об устройствах -------------------------------------------------------------------------------------------------------------------------------------------------------------- Запрос: {"SESSION_ID":2167050134516977715,"LOCATION_ID":18} Структура запроса: Обязательные: SESSION_ID - идентификатор сессии LOCATION_ID - идентификатор локации Ответ: {"ITEMS":[ {"ID":230,"PLACE_ID":3,"NAME":"Свет","COMMENT":"","DISABLED":false,"AGGREGATION_PERIOD_ID":4}, {"ID":39,"PLACE_ID":1,"NAME":"Термометр","COMMENT":"","DISABLED":false,"AGGREGATION_PERIOD_ID":4}, {"ID":231,"PLACE_ID":2,"NAME":"Компьютер","COMMENT":"192.168.10.20 [00:e0:66:ae:2a:de]","DISABLED":false,"AGGREGATION_PERIOD_ID":4}, {"ID":40,"PLACE_ID":4,"NAME":"Аквариум","COMMENT":"","DISABLED":false,"AGGREGATION_PERIOD_ID":4}, ... {"ID":56,"PLACE_ID":4,"NAME":"Сценарии","COMMENT":"","DISABLED":false,"AGGREGATION_PERIOD_ID":4}]}} Структура ответа: ITEMS - массив элементов Структура элемента: ID - число, идентификатор устройства NAME - название устройства COMMENT - комментарий к устройству DISABLED - признак заблокированного устройства AGGREGATION_PERIOD_ID - идентификатор периода(число) сбора данных устройства в БД. (*пока не помню зачем оно здесь) -------------------------------------------------------------------------------------------------------------------------------------------------------------- COMMAND - управление устройством -------------------------------------------------------------------------------------------------------------------------------------------------------------- Запрос: {"SESSION_ID":5112320086770491216,"TYPE_ID":6,"LOCATION_ID":8,"DEVICE_ID":50,"NUM":1,"PARAM":"NDU="} Структура запроса: Обязательные: SESSION_ID - идентификатор сессии TYPE_ID - идентификатор типа команды(число), см. e_command_types DEVICE_ID - идентификатор устройства(число) NUM - номер канала(число 0-255), по умолчанию - 0 PARAM - дополнительный параметр (BASE64), используется в комадах типа SET_POWER для передачи мощности в процентах Не обязательные: LOCATION_ID - идентификатор локации в которой данное устройство. Если не указан, то используется текущая локация. Ответ: {} В ответе сервер сообщает о факте добавления команды в очередь заявок. Результат можно проверить запросив MEASURES_GET, показание ид. 104(Порт управления). Также, если режим работы асинхронный, сервер сообщает о состоянии заявки в информационных сообщениях 'INFORM' Сервер удаляет старую команду при поступлении однотипной команды в рамках одного устройства и канала. Выполнение команды можно отменить послав команду 0(CANCEL) -------------------------------------------------------------------------------------------------------------------------------------------------------------- INFORM - Информационное сообщение от сервера к клиентам (только в асинхронном режиме работы)! -------------------------------------------------------------------------------------------------------------------------------------------------------------- Запрос: {"LOCATION": {"ID":8, "DEVICES":[ {"MEASURES":[ {"TYPE_ID":2,"VALUE":1608170302056}, {"TYPE_ID":3,"VALUE":7}, {"TYPE_ID":16777320,"VALUE":"1"}, {"TYPE_ID":106,"VALUE":"45"}, {"TYPE_ID":4,"VALUE":"5"}], "COMMANDS":[ {"ID":80,"TYPE_ID":6,"DEVICE_ID":50,"NUM":1,"PARAM":"NDU=","RESULT":true,"TIMESTAMP":1608170301922}], "ID":50}]}} Структура запроса: LOCATION - блок данных текузей локации Структура LOCATION: ID - идентификатор текущей локации DEVICES - блок устройств Структура DEVICES: ID - идентификатор устройства (число) MEASURES - блок текущих показаний, аналогично ответу на MEASURES_GET COMMANDS - блок обрабатываемых комманд Структура объекта в COMMANDS: ID - идентификатор запроса команды (число) TYPE_ID - идентификатор типа команды(число), см. e_command_types DEVICE_ID - идентификатор устройства(число) NUM - номер канала(число 0-255), по умолчанию - 0 PARAM - дополнительный параметр (BASE64), используется в комадах типа SET_POWER для передачи мощности в процентах RESULT - результат выполнения (отсуствует или null - еще выполняется, true - успешное выполнение, false - не успешное выполнение) TIMESTAMP - временная метка создания заявки на выполнение(время с сервера, в миллисекундах) Ответ: {} После получения кода ответа 200(ок) сервер считает, что данные переданы успешно, помечает или удаляет не актуальные блоки информации (например выполненные команды). Иначе сервер периодически повторяет информирование. -------------------------------------------------------------------------------------------------------------------------------------------------------------- LOCATION_SELECT - Выбор текущей локации. -------------------------------------------------------------------------------------------------------------------------------------------------------------- Запрос: {"SESSION_ID":5757578819229333758,"ID":18} Структура запроса: Обязательные: SESSION_ID - идентификатор сессии ID - идентификатор локации Ответ: ...в процессе...