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"
}
Параметр | Значение | Описание |
---|---|---|
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"}
]
}
Параметр | Значение | Описание |
---|---|---|
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 |
Массив / отсутствует. Элемент — {событие}. |
Непрочитанные события. Отсутствует — нет непрочитанных событий. |
Параметр | Значение | Описание |
---|---|---|
Active |
1 / 0 |
Состояние входа. 1 — активен, 0 — пассивен. |
Voltage |
Целое число: [0…4095] |
Напряжение входа. Целое число — значение в дискретах (\$D\$). Если выбран тип входа RTD-03, то значение в дискретах учитывает калибровку входа в конфигураторе.
|
Параметр | Значение | Описание |
---|---|---|
State |
"Low2" / "Low1" / "OK" / "NotUsed" / "Disconnected" |
Состояние батареи. "Low2" — разряд до 2 уровня, "Low1" — разряд до 1 уровня, "OK" — норма, "NotUsed" — не использовалась, "Disconnected" — отключена. |
Charge |
Целое число / отсутствует |
Заряд батареи. Целое число — значение в процентах, отсутствует — нет данных. |
Параметр | Значение | Описание |
---|---|---|
ID |
Целое число |
Идентификатор события. Подтверждается командой AckEvents. |
Type |
Строка |
Тип события. |
Тип | Описание |
---|---|
InputPassive |
Вход пассивен. |
InputActive |
Вход активен. |
PowerRecovery |
Восстановление внешнего питания. |
PowerFault |
Отключение внешнего питания. |
BatteryLow1 |
Разряд батареи до 1 уровня. |
BatteryLow2 |
Разряд батареи до 2 уровня. |
BalanceLow |
Баланс снизился до минимального значения. |
TempLow |
Температура платы упала до нижней границы. |
TempNormal |
Температура платы вернулась в допустимый диапазон. |
TempHigh |
Температура платы поднялась до верхней границы. |
CaseOpen |
Вскрытие корпуса контроллера. |
Test |
Тестовое сообщение. |
Info |
Информационное сообщение. |
Arm |
Переведен в режим ОХРАНА. |
Disarm |
Переведен в режим НАБЛЮДЕНИЕ. |
Protect |
Переведен в режим ЗАЩИТА. |
ProfileApplied |
Применен профиль. |
DeviceOn |
Контроллер включен. |
DeviceRestart |
Контроллер перезапущен. |
FirmwareUpgrade |
Прошивка обновлена. |
ExtRuntimeError |
Ошибка выполнения программы EXT. |
Новые записи в журнале управления шлагбаумом. |
Параметр | Значение | Описание |
---|---|---|
Number |
Целое число |
Номер входа. |
Partitions |
Массив / отсутствует. Элемент — целое число. |
Номера привязанных разделов. Отсутствует — не поддерживается. |
Параметр | Значение | Описание |
---|---|---|
Partition |
Целое число / отсутствует |
Номер раздела. Отсутствует — не поддерживается. |
Source |
{источник изменения режима охраны} |
Источник изменения режима охраны. |
Параметр | Значение | Описание |
---|---|---|
Type |
Строка |
Тип источника изменения режима охраны. |
Тип | Описание |
---|---|
Button |
Кнопка. |
Input |
Вход. |
Scheduler |
Планировщик задач. |
Modbus |
GuardTracker по сети Modbus. |
TouchMemory |
Ключ TouchMemory. |
DTMF |
Голосовое меню. |
SMS |
SMS команда. |
CSD |
CSD соединение. |
Call |
Вызов без соединения. |
GTNet |
GuardTracker по сети. |
uGuardNet |
uGuard по сети. |
Shell |
CCU shell. |
Параметр | Значение | Описание |
---|---|---|
Key |
Строка / отсутствует |
Номер ключа. Отсутствует — обязателен KeyName. |
KeyName |
Строка / отсутствует |
Имя ключа. Отсутствует — обязателен Key. |
Параметр | Значение | Описание |
---|---|---|
Phone |
Строка / отсутствует |
Номер телефона. Отсутствует — нет данных. |
Параметр | Значение | Описание |
---|---|---|
Number |
Целое число |
Номер профиля. |
Параметр | Значение | Описание |
---|---|---|
UserName |
Строка |
Имя пользователя. |
Параметр | Значение | Описание |
---|---|---|
ErrorCode |
Целое число |
Код ошибки. |
Описание ErrorCode см. в руководстве пользователя EXT.
2.2. Команда AckEvents
Команда подтверждает получение событий.
{
"Command":"AckEvents",
"IDs":[37,38]
}
Параметр | Значение | Описание |
---|---|---|
Command |
"AckEvents" |
Тип команды. |
IDs |
Массив. Элемент — целое число. |
Массив идентификаторов событий, полученных с помощью команды GetStateAndEvents. Пустой массив не допускается. |
При успешном подтверждении возвращается ответ типа Status с кодом 0.
2.3. Команда SetPartitionState
Команда устанавливает состояние охраны первого раздела.
{
"Command":"SetPartitionState",
"State":"Arm"
}
Параметр | Значение | Описание |
---|---|---|
Command |
"SetPartitionState" |
Тип команды. |
State |
"Arm" / "Disarm" / "Protect" |
Состояние охраны раздела. "Arm" — ОХРАНА, "Disarm" — НАБЛЮДЕНИЕ, "Protect" — ЗАЩИТА (только для контроллеров с одним разделом). |
При успешном выполнении возвращается состояние контроллера и непрочитанные события, см. команду GetStateAndEvents.
2.4. Команда SetPartitionsState
Команда устанавливает состояние охраны нескольких разделов.
{
"Command":"SetPartitionsState",
"State":["Arm","Disarm","","Arm"]
}
Параметр | Значение | Описание |
---|---|---|
Command |
"SetPartitionsState" |
Тип команды. |
State |
Массив. Элемент — "Arm" / "Disarm" / "Protect" / "". |
Состояние охраны разделов. Номер элемента в массиве равен номеру раздела. "Arm" — ОХРАНА, "Disarm" — НАБЛЮДЕНИЕ, "Protect" — ЗАЩИТА (только для контроллеров с одним разделом), "" — нет воздействия. |
При успешном выполнении возвращается состояние контроллера и непрочитанные события, см. команду GetStateAndEvents.
2.5. Команда SetOutputState
Команда устанавливает состояние выхода.
{
"Command":"SetOutputState",
"Number":5,
"State":0
}
Параметр | Значение | Описание |
---|---|---|
Command |
"SetOutputState" |
Тип команды. |
Number |
Целое число |
Номер выхода. |
State |
1 / 0 |
Состояние выхода. 1 — активен, 0 — пассивен. |
При успешном выполнении возвращается состояние контроллера и непрочитанные события, см. команду GetStateAndEvents.
2.6. Команда SetOutputsState
Команда устанавливает состояние нескольких выходов.
{
"Command":"SetOutputsState",
"State":[1,-1,-1,0,0,1,1]
}
Параметр | Значение | Описание |
---|---|---|
Command |
"SetOutputsState" |
Тип команды. |
State |
Массив. Элемент — 1 / 0 / -1. |
Состояние выходов. Номер элемента в массиве равен номеру выхода. 1 — активен, 0 — пассивен, -1 — нет воздействия. |
При успешном выполнении возвращается состояние контроллера и непрочитанные события, см. команду GetStateAndEvents.
2.7. Команда ApplyProfile
Команда применяет профиль.
{
"Command":"ApplyProfile",
"Number":3
}
Параметр | Значение | Описание |
---|---|---|
Command |
"ApplyProfile" |
Тип команды. |
Number |
Целое число |
Номер профиля. |
При успешном выполнении возвращается состояние контроллера и непрочитанные события, см. команду GetStateAndEvents.
2.8. Команда GetDeviceInfo
Команда запрашивает информацию о контроллере.
{
"Command":"GetDeviceInfo"
}
Параметр | Значение | Описание |
---|---|---|
Command |
"GetDeviceInfo" |
Тип команды. |
{
"DeviceType":"CCU825",
"DeviceMod":"HOME+",
"ExtBoard":"E01.1",
"InputsCount":16,
"PartitionsCount":4,
"HwVer":"10.02",
"FwVer":"02.02",
"BootVer":"01.02",
"FwBuildDate":"Aug 31 2015",
"CountryCode":"RUS",
"Serial":"1414FD09535605154EF8C306F5043213",
"IMEI":"869158123877455",
"uGuardVerCode":17
}
Параметр | Значение | Описание |
---|---|---|
DeviceType |
Строка |
Тип контроллера. |
DeviceMod |
Строка |
Модификация. |
ExtBoard |
Строка |
Плата расширения. |
InputsCount |
Целое число |
Количество входов. |
PartitionsCount |
Целое число |
Количество разделов. |
HwVer |
Строка |
Аппаратная версия. |
FwVer |
Строка |
Версия прошивки. |
BootVer |
Строка |
Версия загрузчика. |
FwBuildDate |
Строка |
Дата сборки прошивки. |
CountryCode |
Строка |
Код страны. |
Serial |
Строка |
Серийный номер. |
IMEI |
Строка |
IMEI. |
uGuardVerCode |
Целое число |
Код минимальной версии uGuard. |
2.9. Команда GetAllGateUsers
Команда запрашивает всех пользователей из списка управления шлагбаумом.
{
"Command":"GetAllGateUsers"
}
Параметр | Значение | Описание |
---|---|---|
Command |
"GetAllGateUsers" |
Тип команды. |
{
"Users":[
["+79109451234","Петров","S8","","","","OFF","ON",""],
["+79109454321","Боширов","ON","OFF","","","S1","S14",""]
]
}
Параметр | Значение | Описание |
---|---|---|
Users |
Массив. Элемент массива — [параметры пользователя]. |
Список пользователей для управления шлагбаумом. Пустой массив — отсутствие пользователей. |
Индекс массива | Значение | Описание |
---|---|---|
0 |
Строка. Может содержать от 7 до 15 цифр с символом '+' и от 3 до 15 цифр без '+'. |
Телефонный номер пользователя. |
1 |
Строка. Может содержать от 1 до 16 латинских символов, русских символов, цифр и символов из набора: "#$%&'()*,.:;<>@[]\^_`{}|~. Может быть пустой. |
Имя пользователя. |
2…N |
Строка. Допустимые значения: ON, OFF, S1…S14. Может быть пустой. |
Реакция выходов. Пустая строка — нет реакции, ON — включить, OFF — выключить, S1…S14 — выполнить сценарий с заданным номером. Индекс последнего элемента массива параметров пользователя N определяется кол-вом выходов контроллера — для CCU825 N=8 (7 выходов), для CCU422 N=5 (4 выхода). |
2.10. Команда SetAllGateUsers
Команда задает параметры всех пользователей из списка управления шлагбаумом. Отсутствующие в команде пользователи удаляются.
{
"Command":"SetAllGateUsers",
"Users":[
["+79109451234","Петров","S8","","","","OFF","ON",""],
["+79109454321","Боширов","ON","OFF","","","S1","S14",""]
]
}
Параметр | Значение | Описание |
---|---|---|
Command |
"SetAllGateUsers" |
Тип команды. |
Users |
Массив. Элемент массива — [параметры пользователя]. |
Список пользователей для управления шлагбаумом. Максимальное кол-во пользователей — 4000. |
Описание параметров пользователя см. в описании команды GetAllGateUsers.
Ответ команды SetAllGateUsers соответствует ответу команды GetAllGateUsers.
2.11. Команда DelAllGateUsers
Команда удаляет всех пользователей из списка управления шлагбаумом.
{
"Command":"DelAllGateUsers"
}
Параметр | Значение | Описание |
---|---|---|
Command |
"DelAllGateUsers" |
Тип команды. |
Ответ команды DelAllGateUsers соответствует ответу команды GetAllGateUsers.
2.12. Команда GetGateUser
Команда запрашивает параметры пользователя из списка управления шлагбаумом по номеру телефона.
{
"Command":"GetGateUser",
"Phone":"+79109451234"
}
Параметр | Значение | Описание |
---|---|---|
Command |
"GetGateUser" |
Тип команды. |
Phone |
Строка. Может содержать от 7 до 15 цифр с символом '+' и от 3 до 15 цифр без '+'. |
Телефонный номер пользователя. |
{
"User":["+79109451234","Петров","S8","","","","OFF","ON",""]
}
Параметр | Значение | Описание |
---|---|---|
User |
[параметры пользователя] / отсутствует. |
Параметры пользователя. Отсутствует — пользователь не найден. |
Описание параметров пользователя см. в описании команды GetAllGateUsers.
2.13. Команда SetGateUser
Команда задает параметры пользователя из списка управления шлагбаумом.
{
"Command":"SetGateUser",
"User":["+79109451234","Петров","S8","","","","OFF","ON",""]
}
Параметр | Значение | Описание |
---|---|---|
Command |
"SetGateUser" |
Тип команды. |
User |
[параметры пользователя] |
Параметры пользователя. |
Описание параметров пользователя см. в описании команды GetAllGateUsers.
Ответ команды SetGateUser соответствует ответу команды GetGateUser.
Если при выполнении команы SetGateUser превышено максимальное кол-во пользователей 4000, возвращается ответ типа Status с кодом -15 (insufficient space).
{
"Status":{
"Code":-15,
"Description":"insufficient space"
}
}
2.14. Команда DelGateUser
Команда удаляет пользователя из списка управления шлагбаумом по номеру телефона.
{
"Command":"DelGateUser",
"Phone":"+79109451234"
}
Параметр | Значение | Описание |
---|---|---|
Command |
"DelGateUser" |
Тип команды. |
Phone |
Строка. Может содержать от 7 до 15 цифр с символом '+' и от 3 до 15 цифр без '+'. |
Телефонный номер пользователя. |
Ответ команды DelGateUser соответствует ответу команды GetGateUser.
2.15. Команда GetFirstGateRecord
Команда запрашивает первую (самую старую) запись в журнале управления шлагбаумом.
{
"Command":"GetFirstGateRecord"
}
Параметр | Значение | Описание |
---|---|---|
Command |
"GetFirstGateRecord" |
Тип команды. |
{
"Record":[1,"2021-06-04T21:07:46","+79109451234"]
}
Параметр | Значение | Описание |
---|---|---|
Record |
[параметры записи] / отсутствует. |
Параметры записи. Отсутствует — запись не найдена. |
Индекс массива | Значение | Описание |
---|---|---|
0 |
Целое число: [0…4294967295]. |
Индекс записи. |
1 |
Строка. Время в формате ISO 8601: YYYY-MM-DDThh:mm:ss. |
Время записи по часам контроллера. |
2 |
Строка. Может содержать от 7 до 15 цифр с символом '+' и от 3 до 15 цифр без '+'. |
Телефонный номер пользователя. |
2.16. Команда GetLastGateRecord
Команда запрашивает последнюю (самую новую) запись в журнале управления шлагбаумом.
{
"Command":"GetLastGateRecord"
}
Параметр | Значение | Описание |
---|---|---|
Command |
"GetLastGateRecord" |
Тип команды. |
Ответ команды GetLastGateRecord соответствует ответу команды GetFirstGateRecord.
2.17. Команда GetNextGateRecords
Команда запрашивает очередную порцию записей журнала управления шлагбаумом. Размер порции ограничен.
{
"Command":"GetNextGateRecords",
"Index":0
}
Параметр | Значение | Описание |
---|---|---|
Command |
"GetNextGateRecords" |
Тип команды. |
Index |
Целое число: [0…4294967295]. |
Индекс записи журнала управления шлагбаумом, после которого производится чтение. |
{
"Records":[
[1,"2021-06-04T21:07:46","+79109451234"],
[2,"2021-06-04T21:08:00","+79109454321"]
],
"Last":true
}
Параметр | Значение | Описание |
---|---|---|
Records |
Массив. Элемент массива — [параметры записи]. |
Список записей журнала управления шлагбаумом. Пустой массив — отсутствие записей в запрошенном диапазоне. |
Last |
true / отсутствует. |
true — последняя запись в массиве является последней в журнале. Отсутствует — конец журнала не достигнут или отсутствие записей в запрошенном диапазоне. |
Описание параметров записи см. в описании команды GetFirstGateRecord.
Для получения записей журнала, например по событию NewGateRecords, необходимо последовательно давать команду GetNextGateRecords до получения ответа с установленным признаком Last или до получения пустого массива. При этом каждая следующая команда должна устанавливать параметр Index в значение равное индексу последней записи из ответа на предыдущую команду GetNextGateRecords.
Если Index меньше индекса первой (самой старой) записи журнала, то производится чтение записей с первой (самой старой) записи журнала. Если Index больше индекса последней (самой новой) записи журнала, то возвращается пустой массив.
2.18. Ответ типа Status
На любую команду может быть прислан ответ типа Status.
{
"Status":{
"Code":-5,
"Description":"system error"
}
}
Параметр | Значение | Описание |
---|---|---|
Status |
{информация о статусе операции} |
Информация о статусе операции. |
Параметр | Значение | Описание |
---|---|---|
Code |
Целое число |
Код статуса операции. 0 — успех, не равно 0 — ошибка. |
Description |
Строка |
Описание кода статуса операции. |
3. Диаграмма обмена
4. Событийно-ориентированный обмен
Для оперативного получения событий от контроллера следует использовать информационный канал https://ccu.su/events. Данный метод, по сравнению с организацией периодического опроса контроллера (polling), увеличивает скорость реакции на события и минимизирует трафик. Информационный канал использует технологию SSE.
Типы событий информационного канала:
-
Поддержание канала. Данное событие не требует реакции.
{"Type":"Keepalive"}
-
Новые события контроллера. Необходимо выполнить команду GetStateAndEvents и, при наличии в ответе событий, команду AckEvents.
{"Type":"NewEvents"}
-
Контроллер отключился. Канал будет закрыт.
{"Type":"Close"}
Пример реализации на Python 3. Используется библиотека https://pypi.python.org/pypi/sseclient. Необходимо задать действительные имя пользователя, пароль и IMEI контроллера в переменной auth.
#!/usr/bin/env python3
from sseclient import SSEClient
import requests
import json
url="https://ccu.su"
auth=("admin@000000000000000", "password")
def do_req(cmd):
headers = {"Content-Type": "application/x-www-form-urlencoded"}
data = json.dumps(cmd, separators=(',', ':'))
r = requests.post(url + "/data.cgx", auth=auth, headers=headers, data=data)
r.raise_for_status()
return r.json()
def handle_msg(msg):
print(msg)
if msg["Type"] == "NewEvents":
r = do_req({"Command": "GetStateAndEvents"})
print(r)
if "Events" in r:
ids = []
for e in r["Events"]:
ids.append(e["ID"])
if ids:
r = do_req({"Command": "AckEvents", "IDs": ids})
print(r)
msgs = SSEClient(url + "/events", auth=auth)
for msg in msgs:
handle_msg(json.loads(str(msg)))