Встроенный CCU JSON API: Описание протокола

1. Описание обмена

Обмен данными с контроллерами CCU осуществляется с помощью методов GET или POST протокола HTTP. Запрашиваемый URL-путь: data.cgx. В запросе присутствует единственный параметр cmd, содержащий текст команды в JSON формате.

Пример запроса:

http://localhost:8080/data.cgx?cmd={"Command":"GetStateAndEvents"}

Применяется базовая HTTP-аутентификация.

При соединении через CCU.SU используется HTTPS. При соединении через CCU Proxy — HTTP.

2. JSON протокол

2.1. Команда GetStateAndEvents

Команда возвращает последнее состояние объекта и список непрочитанных событий.

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

{
    "Command":"GetStateAndEvents"
}

Таблица 1. Параметры команды
Параметр	Значение	Описание
Command	"GetStateAndEvents"	Тип команды.

Пример ответа:

{
    "Inputs":[
        {"Active":1,"Voltage":0},
        {"Active":0,"Voltage":20},
        {"Active":1,"Voltage":30},
        {"Active":0,"Voltage":40},
        {"Active":1,"Voltage":50},
        {"Active":1,"Voltage":60},
        {"Active":0,"Voltage":70},
        {"Active":1,"Voltage":4095}
    ],
    "Outputs":[1,0,1,1,1,0,1],
    "Partitions":["Arm","Disarm","Disarm","Disarm"],
    "Case":1,
    "Power":12.3,
    "Battery":{"State":"OK","Charge":20},
    "Temp":25,
    "Balance":"NotValid",
    "Events":[
        {"ID":24,"Type":"InputPassive","Number":1},
        {"ID":25,"Type":"InputActive","Number":16,"Partitions":[1,2,3,4]},
        {"ID":26,"Type":"PowerRecovery"},
        {"ID":27,"Type":"PowerFault"},
        {"ID":28,"Type":"BatteryLow1"},
        {"ID":29,"Type":"BatteryLow2"},
        {"ID":30,"Type":"BalanceLow"},
        {"ID":31,"Type":"TempLow"},
        {"ID":32,"Type":"TempNormal"},
        {"ID":33,"Type":"TempHigh"},
        {"ID":34,"Type":"CaseOpen"},
        {"ID":35,"Type":"Test"},
        {"ID":36,"Type":"Info"},
        {"ID":37,"Type":"ProfileApplied","Number":1},
        {"ID":38,"Type":"DeviceOn"},
        {"ID":39,"Type":"DeviceRestart"},
        {"ID":40,"Type":"Arm",
            "Source":{"Type":"Button"}},
        {"ID":41,"Type":"Arm","Partition":1,
            "Source":{"Type":"Input"}},
        {"ID":42,"Type":"Arm","Partition":2,
            "Source":{"Type":"Scheduler"}},
        {"ID":43,"Type":"Arm","Partition":3,
            "Source":{"Type":"Modbus"}},
        {"ID":44,"Type":"Arm","Partition":4,
            "Source":{"Type":"TouchMemory",
            "Key":"0001020304050607","KeyName":"Vasya"}},
        {"ID":45,"Type":"Arm","Partition":1,
            "Source":{"Type":"DTMF","Phone":"+71231234567"}},
        {"ID":46,"Type":"Disarm","Partition":2,
            "Source":{"Type":"SMS","Phone":"+71231234567"}},
        {"ID":47,"Type":"Disarm","Partition":3,
            "Source":{"Type":"CSD","Phone":"+71231234567"}},
        {"ID":48,"Type":"Disarm","Partition":4,
            "Source":{"Type":"Call","Phone":"+71231234567"}},
        {"ID":49,"Type":"Arm","Partition":1,
            "Source":{"Type":"GTNet"}},
        {"ID":50,"Type":"Disarm","Partition":2,
            "Source":{"Type":"uGuardNet","UserName":"Name"}},
        {"ID":51,"Type":"Disarm","Partition":3,
            "Source":{"Type":"Shell","UserName":"Name"}},
        {"ID":52,"Type":"FirmwareUpgrade"},
        {"ID":53,"Type":"ExtRuntimeError","ErrorCode":1},
        {"ID":54,"Type":"NewGateRecords"}
    ]
}

Таблица 2. Параметры ответа
Параметр	Значение	Описание
Inputs	Массив. Элемент — {состояние входа}.	Состояние входов. Кол-во элементов равно кол-ву входов.
Outputs	Массив. Элемент — 1 / 0.	Состояние выходов. Кол-во элементов равно кол-ву выходов. 1 — активен, 0 — пассивен.
Partitions	Массив. Элемент — "Arm" / "Disarm" / "Protect".	Состояние разделов. Кол-во элементов равно кол-ву разделов. "Arm" — ОХРАНА, "Disarm" — НАБЛЮДЕНИЕ, "Protect" — ЗАЩИТА (только для контроллеров с одним разделом).
Case	1 / 0 / отсутствует	Состояние крышки корпуса. 1 — открыта, 0 — закрыта, отсутствует — не поддерживается.
Power	"Off" / Число	Состояние питания. "Off" — выключено, Число — напряжение в вольтах.
Battery	{состояние батареи}	Состояние батареи.
Temp	"NotValid" / Целое число	Температура платы. "NotValid" — значение не определено, целое число — градусы Цельсия.
Balance	"NotValid" / Число	Состояние баланса. "NotValid" — значение не определено, число — значение в валюте.
Events	Массив / отсутствует. Элемент — {событие}.	Непрочитанные события. Отсутствует — нет непрочитанных событий.

Таблица 3. Параметры состояния входа
Параметр	Значение	Описание
Active	1 / 0	Состояние входа. 1 — активен, 0 — пассивен.
Voltage	Целое число: [0…4095]	Напряжение входа. Целое число — значение в дискретах (\$D\$). Если выбран тип входа RTD-03, то значение в дискретах учитывает калибровку входа в конфигураторе. Перевод в вольты \$U = D * 10 / 4095\$ Перевод в градусы по Цельсию для датчика RTD-03 \$T = (U / 5 - 0.5) / 0.01\$ Перевод в градусы по Цельсию для датчика RTD-04 \$T = -3.03641 * U^3 + 25.5916 * U^2 - 87.9556 * U + 120.641\$

Таблица 4. Параметры состояния батареи
Параметр	Значение	Описание
State	"Low2" / "Low1" / "OK" / "NotUsed" / "Disconnected"	Состояние батареи. "Low2" — разряд до 2 уровня, "Low1" — разряд до 1 уровня, "OK" — норма, "NotUsed" — не использовалась, "Disconnected" — отключена.
Charge	Целое число / отсутствует	Заряд батареи. Целое число — значение в процентах, отсутствует — нет данных.

Таблица 5. Общие параметры для всех событий
Параметр	Значение	Описание
ID	Целое число	Идентификатор события. Подтверждается командой AckEvents.
Type	Строка	Тип события.

Таблица 6. Типы событий
Тип	Описание
InputPassive	Вход пассивен.
InputActive	Вход активен.
PowerRecovery	Восстановление внешнего питания.
PowerFault	Отключение внешнего питания.
BatteryLow1	Разряд батареи до 1 уровня.
BatteryLow2	Разряд батареи до 2 уровня.
BalanceLow	Баланс снизился до минимального значения.
TempLow	Температура платы упала до нижней границы.
TempNormal	Температура платы вернулась в допустимый диапазон.
TempHigh	Температура платы поднялась до верхней границы.
CaseOpen	Вскрытие корпуса контроллера.
Test	Тестовое сообщение.
Info	Информационное сообщение.
Arm	Переведен в режим ОХРАНА.
Disarm	Переведен в режим НАБЛЮДЕНИЕ.
Protect	Переведен в режим ЗАЩИТА.
ProfileApplied	Применен профиль.
DeviceOn	Контроллер включен.
DeviceRestart	Контроллер перезапущен.
FirmwareUpgrade	Прошивка обновлена.
ExtRuntimeError	Ошибка выполнения программы EXT.
NewGateRecords	Новые записи в журнале управления шлагбаумом.

Таблица 7. Дополнительные параметры для событий InputActive и InputPassive
Параметр	Значение	Описание
Number	Целое число	Номер входа.
Partitions	Массив / отсутствует. Элемент — целое число.	Номера привязанных разделов. Отсутствует — не поддерживается.

Таблица 8. Дополнительные параметры для событий Arm, Disarm, Protect
Параметр	Значение	Описание
Partition	Целое число / отсутствует	Номер раздела. Отсутствует — не поддерживается.
Source	{источник изменения режима охраны}	Источник изменения режима охраны.

Таблица 9. Общие параметры источника изменения режима охраны
Параметр	Значение	Описание
Type	Строка	Тип источника изменения режима охраны.

Таблица 10. Типы источника изменения режима охраны
Тип	Описание
Button	Кнопка.
Input	Вход.
Scheduler	Планировщик задач.
Modbus	GuardTracker по сети Modbus.
TouchMemory	Ключ TouchMemory.
DTMF	Голосовое меню.
SMS	SMS команда.
CSD	CSD соединение.
Call	Вызов без соединения.
GTNet	GuardTracker по сети.
uGuardNet	uGuard по сети.
Shell	CCU shell.

Таблица 11. Дополнительные параметры для источника изменения режима охраны TouchMemory
Параметр	Значение	Описание
Key	Строка / отсутствует	Номер ключа. Отсутствует — обязателен KeyName.
KeyName	Строка / отсутствует	Имя ключа. Отсутствует — обязателен Key.

Таблица 12. Дополнительные параметры для источников изменения режима охраны DTMF, SMS, CSD, Call
Параметр	Значение	Описание
Phone	Строка / отсутствует	Номер телефона. Отсутствует — нет данных.

Таблица 13. Дополнительные параметры для события ProfileApplied
Параметр	Значение	Описание
Number	Целое число	Номер профиля.

Таблица 14. Дополнительные параметры для источников изменения режима охраны uGuardNet и Shell
Параметр	Значение	Описание
UserName	Строка	Имя пользователя.

Таблица 15. Дополнительный параметр для события ExtRuntimeError
Параметр	Значение	Описание
ErrorCode	Целое число	Код ошибки.

Описание ErrorCode см. в руководстве пользователя EXT.

2.2. Команда AckEvents

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

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

{
    "Command":"AckEvents",
    "IDs":[37,38]
}

Таблица 16. Параметры команды
Параметр	Значение	Описание
Command	"AckEvents"	Тип команды.
IDs	Массив. Элемент — целое число.	Массив идентификаторов событий, полученных с помощью команды GetStateAndEvents. Пустой массив не допускается.

При успешном подтверждении возвращается ответ типа Status с кодом 0.

2.3. Команда SetPartitionState

Команда устанавливает состояние охраны первого раздела.

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

{
    "Command":"SetPartitionState",
    "State":"Arm"
}

Таблица 17. Параметры команды
Параметр	Значение	Описание
Command	"SetPartitionState"	Тип команды.
State	"Arm" / "Disarm" / "Protect"	Состояние охраны раздела. "Arm" — ОХРАНА, "Disarm" — НАБЛЮДЕНИЕ, "Protect" — ЗАЩИТА (только для контроллеров с одним разделом).