REST API для HDL MHRCU

Программный модуля для запуска на iRidi Server, позволяющий сторонним системам управлять устройством HDL MHRCU с помощью REST API (HTTP запросов). Предоставляет готовый web-интерфейс для быстрого поиска и управления HDL MHRCU

Инструкция по установке​

Модуль MHRCU для iRidi Server позволяет сторонним системам управлять оборудованием HDL RCU с помощью HTTP запросов. Также iRidi Server предосатвляет готовый web-интерфейс управления выбранным комнатным модулем.

iRidi Server подключается к RCU, а сторонняя система управляет сервером.

Чтобы настроить связь между iRidi Server и RCU, следуйте инструкции:

1. скачайте дистрибутив iRidi Server для Windows (7/8/10)
2. установите его, запустите iRidi Server, откроется консольное приложение
3. нажмите W в приложении, чтобы перейти к web-интерфейсу и настроить сервер
4. введите логин (mhrcudemo@iridiummobile.ru) и пароль (230105) авторизации на сервере
5. выберите короткий пароль для входа на Сервер. Его будет использовать внешняя система управления, чтобы авторизоваться на сервере. Пароль по умолчанию: 2007 (если вы пропустили выбор пароля, используйте 2007)
6. скачайте проект управления MHRCU (вы увидите его в списке проектов, доступных для загрузки из Облака)
7. откройте интерфейс управления комнатными контроллерами (Hoteza control). Через web-интерфейс сервера можно найти и выбрать RCU, управлять его параметрами.
8. начните управление RCU с помощью HTTP запросов из любой внешней системы управления

Ограничения 1й версии модуля:

1. нельзя подключиться к нескольким RCU с одного Сервера
2. нельзя изменить выбранный RCU (придется деактивировать сервер и установить проект заново)

Инструкция по обращению к серверу через REST API​

Чтобы начать работать с сервером по HTTP, убедитесь, что он запущен и проект управления MHRCU загружен на сервер. Отправить серверу команду REST API можно только после запроса авторизации в формате POST. Остальные команды нужно отправлять как GET запросы, передавая в них идентификатор сессии, полученный в ответ на запрос авторизации. Идентификатор сессии нужно периодически обновлять. Идентификатор меняется через 15 минут простоя или после выхода из веб-интерфейса.

Управление MHRCU​

Управлять HDL MHRCU с помощью REST API можно, настроив связь программного модуля iRidi Server и модуля HDL MHRCU. Здесь возможны две ситуации:

1. Вы еще не выбрали, к какому HDL MHRCU будет подключен iRidi Server. В этом случае вам потребуется:

   1. авторизоваться на сервере
   2. найти модули HDL MHRCU подключенные к сети и готовые к работе
   3. выбрать HDL MHRCU которыми будете управлять
   4. управлять модулем с помощью доступного списка команд

2. Вы выбрали HDL MHRCU, которым будете управлять, через web-интерфейс. Для управления нужно:

   1. авторизоваться на сервере
   2. управлять модулем с помощью доступного списка команд

Авторизация​

Вам нужно отправить на iRidi Server POST запрос авторизации на порт сервера 8888. В запросе передается обязательный заголовок "Content-Type" и поле данных с паролем авторизации.

Нам понадобится идентификатор сессии: ir-session-id=2QEsebNzyjC8;. Сохраните его, и используйте при отправке команд. Помните, что идентификатор периодически меняется.

После авторизации, можем начать поиск устройств или сразу перейдем к управлению, если управляемое устройство было выбрано в web-интерфейсе сервера.

Поиск устройства​

1. Начинаем поиск доступных MHRCU:

2. Найденные MHRCU сохранятся в переменную сервера, запросим список:

1. Выберем из списка MHRCU для управления

Когда устройство выбрано, можно управлять его параметрами.

Запрос всех параметров​

Запрос всех параметров поможет понять, как настроен MHRCU, и какие его выходы доступны для управления и запроса. Получение списка доступных команд и каналов обратной свзяи производится с помощью разных запросов.

Получив полный список команд и каналов, вы точно узнаете, какими Channel и Order можно управлять и какие данные можно запросить.

Response headers

{
	"tags_count": "59",
	"tags":
[
[1, "Broadcast_Receiver_HDL_Hotel.Online","1.000000","bool","0"],
[2, "Broadcast_Receiver_HDL_Hotel.Status","2.000000","u8","0"],
[3, "Broadcast_Receiver_HDL_Hotel.Host","255.255.255.255","string","0"],
[4, "Broadcast_Receiver_HDL_Hotel.IP","192.168.0.66","string","0"],
[5, "Broadcast_Receiver_HDL_Hotel.Port","6008.000000","u16","0"],
[6, "Broadcast_Receiver_HDL_Hotel.HostIP","255.255.255.255","string","0"],
[7, "Broadcast_Receiver_HDL_Hotel.HostPort","6008.000000","u16","0"],
[8, "Broadcast_Receiver_HDL_Hotel.AV Control Feedback","0.000000","bool","0"],
[9, "Broadcast_Device.Online","0.000000","bool","0"],
[10, "Broadcast_Device.Status","0.000000","u8","0"],
[11, "Broadcast_Device.Host","255.255.255.255","string","0"],
[12, "Broadcast_Device.IP","192.168.0.66","string","0"],
[13, "Broadcast_Device.Port","52666.000000","u16","0"],
[14, "Broadcast_Device.HostIP","255.255.255.255","string","0"],
[15, "Broadcast_Device.HostPort","6006.000000","u16","0"],
[16, "Broadcast_Device.AV Control Feedback","0.000000","bool","0"],
[17, "Device.Online","1.000000","bool","0"],
[18, "Device.Status","2.000000","u8","0"],
[19, "Device.Host","192.168.0.117","string","0"],
[20, "Device.IP","192.168.0.66","string","0"],
[21, "Device.Port","53546.000000","u16","0"],
[22, "Device.HostIP","192.168.0.117","string","0"],
[23, "Device.HostPort","6006.000000","u16","0"],
[24, "Device.AV Control Feedback","0.000000","bool","0"],
[25, "Host","192.168.0.117","string","0"],
[26, "FoundDeviceHDLHotel","[]","string","0"],
[27, "Device.AC_Mode_1","1.000000","f64","0"],
[28, "Device.AC_Power_1","1.000000","f64","0"],
[29, "Device.AC_Cooling_Temp_1","0.000000","f64","0"],
[30, "Device.AC_Fan_1","0.000000","f64","0"],
[31, "Device.AC_Wind_1","0.000000","f64","0"],
[32, "Device.AC_Lock_1","1.000000","f64","0"],
[33, "Device.AC_Heating_Temp_1","30.000000","f64","0"],
[34, "Device.AC_Auto_Temp_1","30.000000","f64","0"],
[35, "Device.AC_Dry_Temp_1","30.000000","f64","0"],
[36, "Device.AC_CurrentTemperature_1","0.000000","f64","0"],
[37, "Device.AC_All_1","{\"Power\":1, \"CoolingTemp\":0, \"Mode\":1, \"Fan\":0, \"Lock\":1, \"CurrentTemperature\":0, \"HeatingTemp\":30, \"AutoTemp\":30, \"DryTemp\":30, \"Wind\":0}","string","0"],
[38, "Device.Curtain_Channel_1","0.000000","f64","0"],
[39, "Device.Alarm_Laundry","1.000000","f64","0"],
[40, "Device.Alarm_Disturb","0.000000","f64","0"],
[41, "Device.Alarm_Clean","0.000000","f64","0"],
[42, "Device.Alarm_All","{\"Laundry\":1, \"Disturb\":0, \"Clean\":0}","string","0"],
[43, "Device.Ventilation_Switcher_1","1","string","0"],
[44, "Device.Ventilation_Ventilation_all","1,0,0,0,0","string","0"],
[45, "Device.FM_Power","1","string","0"],
[46, "Device.FM_Volume","15","string","0"],
[47, "Device.FM_Channel","1","string","0"],
[48, "Device.FM_All","{\"Power\":\"1\", \"Channel\":\"1\", \"Volume\":\"15\"}","string","0"],
[49, "Device.Dimmer_Channel_5","45.000000","f64","0"],
[50, "Device.Dimmer_Channel_6","0.000000","f64","0"],
[51, "Device.Relay_Channel_8","100.000000","f64","0"],
[52, "Device.Dimmer_Channel_9","50.000000","f64","0"],
[53, "Device.Dimmer_Channel_15","0.000000","f64","0"],
[54, "Device.Dimmer_Channel_16","45.000000","f64","0"],
[55, "Device.Dimmer_Channel_17","10.000000","f64","0"],
[56, "Device.Dimmer_Channel_18","58.000000","f64","0"],
[57, "Device.Dimmer_Channel_19","25.000000","f64","0"],
[58, "Device.Dimmer_Channel_20","34.000000","f64","0"],
[59, "Device.Dimmer_Channel_21","50.000000","f64","0"]

]	
}

Response headers

{
	"channels_count": "33",	
	"channels":
	[
[1,"Broadcast_Receiver_HDL_Hotel.AV Control Command"],
[2,"Broadcast_Device.AV Control Command"],
[3,"Device.AV Control Command"],
[4,"StartScan"],
[5,"HostSend"],
[6,"Device.AC_Mode_1"],
[7,"Device.AC_Power_1"],
[8,"Device.AC_Cooling_Temp_1"],
[9,"Device.AC_Fan_1"],
[10,"Device.AC_Wind_1"],
[11,"Device.AC_Lock_1"],
[12,"Device.AC_Heating_Temp_1"],
[13,"Device.AC_Auto_Temp_1"],
[14,"Device.AC_Dry_Temp_1"],
[15,"Device.Curtain_Channel_1"],
[16,"Device.Alarm_Laundry"],
[17,"Device.Alarm_Disturb"],
[18,"Device.Alarm_Clean"],
[19,"Device.Ventilation_Switcher_1"],
[20,"Device.FM_Power"],
[21,"Device.FM_Volume"],
[22,"Device.FM_Channel"],
[23,"Device.Dimmer_Channel_5"],
[24,"Device.Dimmer_Channel_6"],
[25,"Device.Relay_Channel_8"],
[26,"Device.Dimmer_Channel_9"],
[27,"Device.Dimmer_Channel_15"],
[28,"Device.Dimmer_Channel_16"],
[29,"Device.Dimmer_Channel_17"],
[30,"Device.Dimmer_Channel_18"],
[31,"Device.Dimmer_Channel_19"],
[32,"Device.Dimmer_Channel_20"],
[33,"Device.Dimmer_Channel_21"]

	]
}

Управление параметрами​

Обратившись к параметру MHRCU по имени, с помощью специального запроса, вы можете изменить этот параметр. Чтобы понять, какие параметры доступны для изменения, запросите список всех параметров . Чтобы понять, какие значения можно установить в эти параметры, см. таблицу Список параметров. .

Запрос параметров​

Обратившись к параметру MHRCU по имени, с помощью специального запроса, вы можете получить текущее значение этого параметра. Другим запросом вы можете запросить сразу все параметры MHRCU.

Запросите список всех параметров чтобы понять, какие значения можно запросить у выбранного MHRCU, все возможные параметры и допустимые значения для них указаны в Списке параметров .

Список параметров​

В запросе к серверу, обращение к MHRCU всегда начинается с Device., далее идет имя параметра из таблицы. См. Управление параметрами и Запрос параметров

Примеры управления​

Пример авторизации​

Установите REST клиент (например, Advanced REST Client) - расширение для браузера Chrome, чтобы протестировать отправку REST запросов на сервер.

Скачайте файл с готовыми (настроенными) запросами для Advanced REST Client и добавьте к себе через меню Import/Export. Вы получите готовые примеры запросов, которые можно открыть через вкладку Saved.

POST запрос авторизации (REST клиент может добавить и другие заголовки):
 POST /html/login HTTP/1.1
 Host: 192.168.0.66
 Content-Length: 39
 Connection: Keep-Alive
 Keep-Alive: timeout=15, max=300
 Content-Type: application/x-www-form-urlencoded
 User-Agent: iRidium/1.0.6
 Accept: */* Password=2007&name=authform&Login=admin

Настройка запроса в REST клиенте:

Формирование запроса:

1. Host/Path (URL): http://192.168.0.66:8888/html/login
2. Type: POST
3. Raw headers: Content-Type: application/x-www-form-urlencoded
4. Raw payload: Password=2007&name=authform&Login=admin
5. Нажмите клавишу SEND

При успехе вы получите ответ 301:Moved Permanently и данные в Response headers :

 **Location:**  /html/main
 **Set-Cookie:**  ir-session-id=2QEsebNzyjC8; path=/
 **Access-Control-Allow-Origin:**  * **Origin:**  localhost:8888

Нам понадобится идентификатор сессии: ir-session-id=2QEsebNzyjC8;. Сохраните его, и используйте при отправке команд. Помните, что идентификатор периодически меняется

Чтобы управлять функциями сервера, нужно отправлять серверу команды REST API - запросы GET на порт 8888. Список запросов REST API приведен далее. В ответ на запросы приходят данные от сервера в формате JSON. По запросу, сервер выполняет команды и возвращает подтверждение (данные).

Пример управления параметром​

Используйте тот же REST клиент, что при авторизации.

GET запрос для установки яркости диммера:

 GET /json/ok/server/channel/set?name=Device.Dimmer_Channel_9?value=50 HTTP/1.1
 Host: 192.168.0.66
 Connection: Keep-Alive
 Cookie: ir-session-id=2QEsebNzyjC8;
 User-Agent: iRidium/1.0.6
 Accept: */* Если вы правильно укажете идентификатор сессии (см. как его получить в примере авторизации), сервер вернет {"status" : "OK"}

Настройка запроса в REST клиенте:

Формирование запроса:

1. Host/Path (URL): http://192.168.0.66:8888/json/ok/server/channel/set?name=Device.Dimmer_Channel_9?value=50
2. Type: GET
3. Raw headers: Cookie: ir-session-id=a4KEW2VgPcc5;
4. Нажмите клавишу SEND

В URL передаем значения:

• Device.Dimmer_Channel_9 - имя управляемого параметра MHRCU
• value=50 - значение для установки

При успехе вы получите ответ 200: OK и данные в Parsed :

{"status": "OK"}

Данные можно обрабатывать в сторонних приложениях как JSON.