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

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

Пример запроса:
http://localhost:8080/data.cgx?cmd={"Command":"GetStateAndEvents"}

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

При соединении через CCU.SH используется 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]

Напряжение входа. Целое число — значение в дискретах. Перевод в вольты по формуле: дискреты * 10 / 4095.

Таблица 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" — ЗАЩИТА (только для контроллеров с одним разделом).

При успешном выполнении возвращается состояние контроллера и непрочитанные события, см. команду GetStateAndEvents.

2.4. Команда SetPartitionsState

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

Пример команды:
{
    "Command":"SetPartitionsState",
    "State":["Arm","Disarm","","Arm"]
}
Таблица 18. Параметры команды
Параметр Значение Описание

Command

"SetPartitionsState"

Тип команды.

State

Массив. Элемент — "Arm" / "Disarm" / "Protect" / "".

Состояние охраны разделов. Номер элемента в массиве равен номеру раздела. "Arm" — ОХРАНА, "Disarm" — НАБЛЮДЕНИЕ, "Protect" — ЗАЩИТА (только для контроллеров с одним разделом), "" — нет воздействия.

При успешном выполнении возвращается состояние контроллера и непрочитанные события, см. команду GetStateAndEvents.

2.5. Команда SetOutputState

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

Пример команды:
{
    "Command":"SetOutputState",
    "Number":5,
    "State":0
}
Таблица 19. Параметры команды
Параметр Значение Описание

Command

"SetOutputState"

Тип команды.

Number

Целое число

Номер выхода.

State

1 / 0

Состояние выхода. 1 — активен, 0 — пассивен.

При успешном выполнении возвращается состояние контроллера и непрочитанные события, см. команду GetStateAndEvents.

2.6. Команда SetOutputsState

Команда устанавливает состояние нескольких выходов.

Пример команды:
{
    "Command":"SetOutputsState",
    "State":[1,-1,-1,0,0,1,1]
}
Таблица 20. Параметры команды
Параметр Значение Описание

Command

"SetOutputsState"

Тип команды.

State

Массив. Элемент — 1 / 0 / -1.

Состояние выходов. Номер элемента в массиве равен номеру выхода. 1 — активен, 0 — пассивен, -1 — нет воздействия.

При успешном выполнении возвращается состояние контроллера и непрочитанные события, см. команду GetStateAndEvents.

2.7. Команда ApplyProfile

Команда применяет профиль.

Пример команды:
{
    "Command":"ApplyProfile",
    "Number":3
}
Таблица 21. Параметры команды
Параметр Значение Описание

Command

"ApplyProfile"

Тип команды.

Number

Целое число

Номер профиля.

При успешном выполнении возвращается состояние контроллера и непрочитанные события, см. команду GetStateAndEvents.

2.8. Команда GetDeviceInfo

Команда запрашивает информацию о контроллере.

Пример команды:
{
    "Command":"GetDeviceInfo"
}
Таблица 22. Параметры команды
Параметр Значение Описание

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
}
Таблица 23. Параметры ответа
Параметр Значение Описание

DeviceType

Строка

Тип контроллера.

DeviceMod

Строка

Модификация.

ExtBoard

Строка

Плата расширения.

InputsCount

Целое число

Количество входов.

PartitionsCount

Целое число

Количество разделов.

HwVer

Строка

Аппаратная версия.

FwVer

Строка

Версия прошивки.

BootVer

Строка

Версия загрузчика.

FwBuildDate

Строка

Дата сборки прошивки.

CountryCode

Строка

Код страны.

Serial

Строка

Серийный номер.

IMEI

Строка

IMEI.

uGuardVerCode

Целое число

Код минимальной версии uGuard.

2.9. Команда GetAllGateUsers

Команда запрашивает всех пользователей из списка управления шлагбаумом.

Пример команды:
{
    "Command":"GetAllGateUsers"
}
Таблица 24. Параметры команды
Параметр Значение Описание

Command

"GetAllGateUsers"

Тип команды.

Пример ответа:
{
    "Users":[
        ["+79109451234","Петров","S8","","","","OFF","ON",""],
        ["+79109454321","Боширов","ON","OFF","","","S1","S14",""]
    ]
}
Таблица 25. Параметры ответа
Параметр Значение Описание

Users

Массив. Элемент массива — [параметры пользователя].

Список пользователей для управления шлагбаумом. Пустой массив — отсутствие пользователей.

Таблица 26. Параметры пользователя
Индекс массива Значение Описание

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",""]
    ]
}
Таблица 27. Параметры команды
Параметр Значение Описание

Command

"SetAllGateUsers"

Тип команды.

Users

Массив. Элемент массива — [параметры пользователя].

Список пользователей для управления шлагбаумом. Максимальное кол-во пользователей — 4000.

Описание параметров пользователя см. в описании команды GetAllGateUsers.

Ответ команды SetAllGateUsers соответствует ответу команды GetAllGateUsers.

2.11. Команда DelAllGateUsers

Команда удаляет всех пользователей из списка управления шлагбаумом.

Пример команды:
{
    "Command":"DelAllGateUsers"
}
Таблица 28. Параметры команды
Параметр Значение Описание

Command

"DelAllGateUsers"

Тип команды.

Ответ команды DelAllGateUsers соответствует ответу команды GetAllGateUsers.

2.12. Команда GetGateUser

Команда запрашивает параметры пользователя из списка управления шлагбаумом по номеру телефона.

Пример команды:
{
    "Command":"GetGateUser",
    "Phone":"+79109451234"
}
Таблица 29. Параметры команды
Параметр Значение Описание

Command

"GetGateUser"

Тип команды.

Phone

Строка. Может содержать от 7 до 15 цифр с символом '+' и от 3 до 15 цифр без '+'.

Телефонный номер пользователя.

Пример ответа:
{
    "User":["+79109451234","Петров","S8","","","","OFF","ON",""]
}
Таблица 30. Параметры ответа
Параметр Значение Описание

User

[параметры пользователя] / отсутствует.

Параметры пользователя. Отсутствует — пользователь не найден.

Описание параметров пользователя см. в описании команды GetAllGateUsers.

2.13. Команда SetGateUser

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

Пример команды:
{
    "Command":"SetGateUser",
    "User":["+79109451234","Петров","S8","","","","OFF","ON",""]
}
Таблица 31. Параметры команды
Параметр Значение Описание

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"
}
Таблица 32. Параметры команды
Параметр Значение Описание

Command

"DelGateUser"

Тип команды.

Phone

Строка. Может содержать от 7 до 15 цифр с символом '+' и от 3 до 15 цифр без '+'.

Телефонный номер пользователя.

Ответ команды DelGateUser соответствует ответу команды GetGateUser.

2.15. Команда GetFirstGateRecord

Команда запрашивает первую (самую старую) запись в журнале управления шлагбаумом.

Пример команды:
{
    "Command":"GetFirstGateRecord"
}
Таблица 33. Параметры команды
Параметр Значение Описание

Command

"GetFirstGateRecord"

Тип команды.

Пример ответа:
{
    "Record":[1,"2021-06-04T21:07:46","+79109451234"]
}
Таблица 34. Параметры ответа
Параметр Значение Описание

Record

[параметры записи] / отсутствует.

Параметры записи. Отсутствует — запись не найдена.

Таблица 35. Параметры записи
Индекс массива Значение Описание

0

Целое число: [0…​​2147483647].

Индекс записи.

1

Строка. Время в формате ISO 8601: YYYY-MM-DDThh:mm:ss.

Время записи по часам контроллера.

2

Строка. Может содержать от 7 до 15 цифр с символом '+' и от 3 до 15 цифр без '+'.

Телефонный номер пользователя.

2.16. Команда GetLastGateRecord

Команда запрашивает последнюю (самую новую) запись в журнале управления шлагбаумом.

Пример команды:
{
    "Command":"GetLastGateRecord"
}
Таблица 36. Параметры команды
Параметр Значение Описание

Command

"GetLastGateRecord"

Тип команды.

Ответ команды GetLastGateRecord соответствует ответу команды GetFirstGateRecord.

2.17. Команда GetNextGateRecords

Команда запрашивает очередную порцию записей журнала управления шлагбаумом. Размер порции ограничен.

Пример команды:
{
    "Command":"GetNextGateRecords",
    "Index":0
}
Таблица 37. Параметры команды
Параметр Значение Описание

Command

"GetNextGateRecords"

Тип команды.

Index

Целое число: [0…​2147483647].

Индекс записи журнала управления шлагбаумом, после которого производится чтение.

Пример ответа:
{
    "Records":[
        [1,"2021-06-04T21:07:46","+79109451234"],
        [2,"2021-06-04T21:08:00","+79109454321"]
    ],
    "Last":true
}
Таблица 38. Параметры ответа
Параметр Значение Описание

Records

Массив. Элемент массива — [параметры записи].

Список записей журнала управления шлагбаумом. Пустой массив — отсутствие записей в запрошенном диапазоне.

Last

true / отсутствует.

true — последняя запись в массиве является последней в журнале. Отсутствует — конец журнала не достигнут или отсутствие записей в запрошенном диапазоне.

Описание параметров записи см. в описании команды GetFirstGateRecord.

Для получения записей журнала, например по событию NewGateRecords, необходимо последовательно давать команду GetNextGateRecords до получения ответа с установленным признаком Last или до получения пустого массива. При этом каждая следующая команда должна устанавливать параметр Index в значение равное индексу последней записи из ответа на предыдущую команду GetNextGateRecords.

Если Index меньше индекса первой (самой старой) записи журнала, то производится чтение записей с первой (самой старой) записи журнала. Если Index больше индекса последней (самой новой) записи журнала, то возвращается пустой массив.

2.18. Ответ типа Status

На любую команду может быть прислан ответ типа Status.

Пример ответа:
{
    "Status":{
        "Code":-5,
        "Description":"system error"
    }
}
Таблица 39. Параметры ответа
Параметр Значение Описание

Status

{информация о статусе операции}

Информация о статусе операции.

Таблица 40. Параметры информации о статусе операции
Параметр Значение Описание

Code

Целое число

Код статуса операции. 0 — успех, не равно 0 — ошибка.

Description

Строка

Описание кода статуса операции.

3. Диаграмма обмена

exchange diagram

4. Событийно-ориентированный обмен

Для оперативного получения событий от контроллера следует использовать информационный канал https://ccu.sh/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.sh"
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)))