Материал из for iRidium developers
Перейти к: навигация, поиск

REST API для HDL MHRCU

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


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

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

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


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

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


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

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


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

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


Управление MHRCU

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

  1. Вы еще не выбрали, к какому HDL MHRCU будет подключен iRidium Server. В этом случае вам потребуется:
    1. авторизоваться на сервере
    2. найти модули HDL MHRCU подключенные к сети и готовые к работе
    3. выбрать HDL MHRCU которым будете управлять
    4. управлять модулем с помощью доступного списка команд
  2. Вы выбрали HDL MHRCU, которым будете управлять, через web-интерфейс. Для управления нужно:
    1. авторизоваться на сервере
    2. управлять модулем с помощью доступного списка команд


Если вы выбрали HDL MHRCU для управления, но хотите его сменить, деактивируйте сервер через web-интерфейс и активируйте заново (смена MHRCU не доступна в первой версии модуля управления, но будет добавлена позже).

Команды REST API можно передавать с помощью приложения REST клиента, добавив в него необходимые данные.

См. ПРИМЕРЫ отправки REST запросов на Сервер с помощью приложения REST клиента.


Авторизация

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

Запрос авторизоваться на сервере
Type POST
URL /html/login
Headers Content-Type: application/x-www-form-urlencoded
Data Password=2007&name=authform&Login=admin
Ответ:
Code 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;. Сохраните его, и используйте при отправке команд. Помните, что идентификатор периодически меняется.

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


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

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

Запрос найти доступные MHRCU
Type GET
URL /json/ok/server/channel/set?name=StartScan&value=1
Headers Cookie: ir-session-id=2QEsebNzyjC8;
Ответ:
Code 200: OK
Response headers {"status": "OK"}


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

Запрос запросить список найденных MHRCU
Type GET
URL /plain/api/server/tag/get?name=FoundDeviceHDLHotel
Headers Cookie: ir-session-id=2QEsebNzyjC8;
Ответ:
Code 200: OK
Response headers FoundDeviceHDLHotel [{\"MacString\":\"48,44,4c,48,4f,54,45,4c\", \"Remark\":\"49000000048782217000074508924\", \"Version\":\"HDL_V2.01.1_2014/09/12\", \"mMac\":[72, 68, 76, 72, 79, 84, 69, 76], \"Host\":\"192.168.0.117\"}]


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

Запрос выбрать MHRCU, которым будем управлять
Type GET
URL /json/ok/server/channel/set?name=HostSend&value=<RCU_FROM_LIST>
* <RCU_FROM_LIST> - IP адрес модуля MHRCU из списка, полученного в п.2
например, /json/ok/server/channel/set?name=HostSend&value=192.168.0.117
Headers Cookie: ir-session-id=2QEsebNzyjC8;
Ответ:
Code 200: OK
Response headers {"status": "OK"}

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


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

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

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

Обратите внимание, что имена управляемых параметров MHRCU всегда начинаются с Device.<PARAMETER>, все остальные имена - системные.

См. список всех возможных параметров и допустимых значений.


Запрос получить список всех КАНАЛОВ (параметров, которые можно запросить) и их текущее состояние
Type GET
URL /json/tags/server/tags/get
Headers Cookie: ir-session-id=2QEsebNzyjC8;
Ответ:
Code 200: OK

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"]
 
]	
}
Запрос получить список всех КОМАНД (параметров, которыми можно управлять)
Type GET
URL /json/ch/server/channels/get
Headers Cookie: ir-session-id=2QEsebNzyjC8;
Ответ:
Code 200: OK

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 по имени, с помощью специального запроса, вы можете изменить этот параметр. Чтобы понять, какие параметры доступны для изменения, запросите список всех параметров. Чтобы понять, какие значения можно установить в эти параметры, см. таблицу Список параметров.

Запрос установить указанное значение параметра
Type GET
URL /json/ok/server/channel/set?name=Device.<PARAMETER>?value=<VALUE>
* <PARAMETER> - управляемый параметр MHRCU (см. список параметров)
* <VALUE> - значение управляемого параметра MHRCU (см. список доступных значений)
например, /json/ok/server/channel/set?name=Device.Dimmer_Channel_9?value=50
Headers Cookie: ir-session-id=2QEsebNzyjC8;
Ответ:
Code 200: OK
Response headers {"status": "OK"}


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

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

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

Запрос запросить значение параметра
Type GET
URL /plain/api/server/tag/get?name=Device.<PARAMETER>
* <PARAMETER> - запрашиваемый параметр MHRCU (см. список параметров)
например, /plain/api/server/tag/get?name=Device.Dimmer_Channel_9
Headers Cookie: ir-session-id=2QEsebNzyjC8;
Ответ:
Code 200: OK
Response headers Sender HDL Hotel.Dimmer Channel 9 45.000000


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

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

Устройство R/W Параметр Значение
Air Condition
X = AC Order (1-4)
R/W AC_Mode_X 0 - 4: 0 - Cooling, 1 - Heating, 2 - Fan, 3 - Auto, 4 - Dry
R/W AC_Power_X 0 - 1: 0 - Power off, 1 - Power on
R/W AC_Cooling_Temp_X 0 - 86: 0 - 31 C, 32 - 86 F
R/W AC_Fan_X 0 - 3: 0 - Auto, 1 - High, 2 - Medium, 3 - Low
R/W AC_Wind_X 0 - 1: 0 - Wind off, 1 - Wind on
R/W AC_Lock_X 0 - 1: 0 - Lock off, 1 - Lock on
R/W AC_Heating_Temp_X 0 - 86: 0 - 31 C, 32 - 86 F
R/W AC_Auto_Temp_X 0 - 86: 0 - 31 C, 32 - 86 F
R/W AC_Dry_Temp_X 0 - 86: 0 - 31 C, 32 - 86 F
R AC_CurrentTemperature_X 0 - 86: 0 - 31 C, 32 - 86 F
Curtain
X = Curtain Order (1-6)
R/W Curtain_Channel_X 0 - 2: 0 - Stop, 1 - Open, 2 - Closed
Alarm R/W Alarm_Laundry 0 - 1: 0 - Off, 1 - On
R/W Alarm_Disturb 0 - 1: 0 - Off, 1 - On
R/W Alarm_Clean 0 - 1: 0 - Off, 1 - On
Ventilation
X = Ventilation Order (1-5)
R/W Ventilation_Switcher_X 0 - 1: 0 - Off, 1 - On
FM R/W FM_Power 0 - 1: 0 - Power off, 1 - Power on
R/W FM_Volume 0 - 15
R/W FM_Channel 0 - 18
Dimmer
X = Dimmer Channel (1-48)
R/W DImmer_Channel_X 0 - 100
Relay
X = Relay Channel (1-48)
R/W Relay_Channel_X 0 - 100


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


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

Установите 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 клиенте:

MCU-auth-POST-request.png

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

  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 клиенте:

MCU-cmd-GET-request.png

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

  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.