Контроль доступа · Gallagher · REST API · Node-RED · KNX · 10 мин чтения

Gallagher Command Centre REST API и KNX: Event Bridge через Node-RED

Gallagher Command Centre 8.x имеет открытый REST API, позволяющий получать события дверей и доступа почти в реальном времени. Передача этих событий на групповые адреса KNX через Node-RED даёт автоматические реакции освещения, отопления и безопасности на активность считывателя – без проприетарных модулей или дополнительных лицензий. Решение подходит для латвийских объектов: от частных вилл до многоарендных офисов.

Обзор REST API Gallagher Command Centre

Gallagher Command Centre 8.x включает встроенный сервер REST API. API использует поток client credentials OAuth2 для аутентификации. В настройках сервера Command Centre создайте REST API-клиент с доступом к ресурсам Events и Doors. Запишите идентификатор клиента и секрет клиента – они отображаются только один раз при создании.

Для получения токена Bearer отправьте POST-запрос к конечной точке токена. Токен имеет срок действия 3600 секунд (один час). Node-RED выполняет автоматическое обновление токена, сохраняя метку времени истечения срока и запрашивая новый токен до его истечения.

OAuth2 token request

POST /api/access_control/rest/v1/oauth2/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id=<your_client_id>
&client_secret=<your_client_secret>

Response:
{
 "access_token": "eyJhbGciOi...",
 "token_type": "Bearer",
 "expires_in": 3600
}

Node-RED: store token in flow context variable
 msg.token = msg.payload.access_token
 flow.set('gallagher_token', msg.token)
 flow.set('token_expiry', Date.now() + 3500000)

Опрос событий доступа через REST API

Конечная точка событий возвращает события доступа, начиная с заданной метки времени ISO8601. Опрашивайте эту конечную точку каждые 2–5 секунд для обработки событий в режиме, близком к реальному времени. Сохраняйте метку времени последнего обработанного события в контексте потока Node-RED для использования в качестве следующей начальной точки опроса.

Event polling request

GET /api/access_control/rest/v1/events
 ?after=2024-01-15T09:30:00Z
 &pageSize=50
Authorization: Bearer <access_token>

Response array – each event object contains:
{
 "eventType": "cardReadValid",
 "door": { "name": "Main Entrance", "id": "door-uuid-1" },
 "cardholder": { "name": "John Smith", "id": "ch-uuid-1" },
 "timestamp": "2024-01-15T09:31:45Z"
}

eventType values:
 cardReadValid – card accepted, door unlocked
 cardReadInvalid – card rejected (wrong zone, expired)
 doorForced – door opened without valid access
 doorHeldOpen – door held open beyond timer threshold
 antiPassbackViol – anti-passback rule violation detected

Установите пакет node-red-contrib-gallagher через npm в каталоге данных Node-RED. Этот пакет предоставляет готовые входные узлы Gallagher, которые автоматически обрабатывают аутентификацию и опрос – настройте IP-адрес Command Centre, идентификатор клиента и секрет в панели конфигурации узла.

Поток Node-RED: событие двери групповой адрес KNX

Основной поток Node-RED обрабатывает события Gallagher и записывает на групповые адреса KNX через узел записи KNX. Настройте узел записи KNX с IP-адресом вашего KNX IP Interface. Узел switch фильтрует события по типу и имени двери перед запуском действий KNX.

Node-RED flow – card read to KNX actions

Flow: Gallagher event input node
 switch node
 Rule 1: msg.payload.eventType == "cardReadValid"
 AND msg.payload.door.name == "Main Entrance"
 Rule 2: msg.payload.eventType == "doorForced"
 Rule 1 output function node (set KNX payloads)
 msg.knxGA = "3/0/1" // lobby lights full on
 msg.knxDPT = "1.001"
 msg.knxValue = true
 KNX write node (IP Interface: 192.168.1.100)

 function also sends second message:
 msg.knxGA = "4/0/1" // HVAC occupied mode
 msg.knxValue = true
 KNX write node

 Rule 2 output KNX write node
 GA "8/0/1" DPT 1.001 value true // alarm siren relay
 second KNX write node
 GA "3/0/2" DPT 5.001 value 255 // security lights 100%

Событие Gallagher	Групповой адрес KNX	DPT	Действие
cardReadValid – главный вход	3/0/1	1.001	Освещение лобби на полную мощность
cardReadValid – главный вход	4/0/1	1.001	Режим занятости ОВК
doorForced – любая дверь	8/0/1	1.001	Реле сирены сигнализации ВКЛ
doorForced – любая дверь	3/0/2	5.001 (255)	Охранное освещение 100 %
doorHeldOpen – любая дверь	8/0/2	1.001	Реле предупреждения удержания двери

Удалённое открытие двери через двоичный вход KNX

Обратное направление – инициирование открытия двери Gallagher через двоичный вход KNX – не менее важно. Персонал ресепшн с сенсорной панелью KNX может удалённо открыть главный вход без выделенного терминала контроля доступа.

KNX binary input to Gallagher door release

Hardware: MDT SCN-BTL1 binary input at reception touchpanel
KNX telegram on button press GA 3/1/0 DPT 1.001 value 1

Node-RED KNX input node listens on GA 3/1/0:
 filter: value == true (rising edge only)
 HTTP request node:
 Method: POST
 URL: http://<cc-server>/api/access_control/rest/v1/doors/<door_id>/access
 Headers: Authorization: Bearer {flow.gallagher_token}
 Body: { "type": "release" }

Gallagher releases the door for 5 seconds (configured in CC)
Response 200: door release confirmed

door_id: obtain from GET /api/access_control/rest/v1/doors
 Returns array of door objects with id and name fields
 Store Main Entrance door_id in Node-RED environment variable

Webhooks Gallagher для push-уведомлений в реальном времени (CC 8.10+)

Command Centre 8.10 и более поздние версии поддерживают webhooks – Gallagher отправляет события на настроенную HTTP-конечную точку по мере их возникновения, устраняя задержку опроса в 2–5 секунд. Для критически важных с точки зрения безопасности приложений, таких как активация сирены сигнализации, webhooks настоятельно предпочтительнее опроса.

Webhook configuration in Command Centre

In CC server settings REST API Webhooks:
 Add webhook URL: http://<node-red-ip>:1880/gallagher-events
 Events to push: AccessGranted, DoorForced, DoorHeldOpen
 Authentication: HMAC-SHA256 shared secret (recommended)

Node-RED: HTTP input node on /gallagher-events
 verify HMAC signature (function node)
 identical switch/KNX write flow as polling approach
 no inject timer needed – events arrive within 200ms

Webhook payload format matches polling event object:
 { "eventType": "...", "door": {...}, "timestamp": "..." }

Advantage: sub-second latency vs 2-5s polling
Use case: door forced alarm must trigger siren immediately
 – polling delay is unacceptable for security events

Автоматизация занятости этажей в многоарендных зданиях

В многоарендных офисных зданиях зоны Gallagher соответствуют физическим этажам. На каждом этаже есть собственная зона считывателей карт, и Gallagher отслеживает, какие владельцы карт в данный момент находятся на каждом этаже. Эти данные о присутствии в зоне напрямую передаются на занятость зоны ОВК KNX для поэтажного управления отоплением и вентиляцией.

Floor-level occupancy to KNX HVAC zones

Gallagher zone configuration:
 Zone A: Floor 1 readers (doors A01, A02, A03)
 Zone B: Floor 2 readers (doors B01, B02, B03)

Node-RED logic:
 On cardReadValid to Floor 1 door:
 write GA 4/1/1 = true (HVAC zone 1 occupied)
 On cardReadValid to Floor 2 door:
 write GA 4/2/1 = true (HVAC zone 2 occupied)

Last-person-out event (Gallagher CC 8.x):
 When last cardholder exits zone (zone count = 0):
 Event: "lastPersonOut" for zone A
 write GA 4/1/1 = false (HVAC zone 1 setback)
 write GA 3/1/0 = false (floor 1 lights off)
 wait 300s delay in Node-RED (residual occupancy buffer)
 write GA 5/1/1 = true (HVAC night setback active)

End-of-day sequence fires automatically when last
cardholder badges out of each floor – no time-based
schedule needed, responds to actual occupancy

Интеграция anti-passback с сигнализацией KNX

Anti-passback (APB) не позволяет владельцу карты дважды войти в зону, не выйдя из неё – это ключевое средство сдерживания хвостования. Когда Gallagher обнаруживает нарушение APB, событие может инициировать состояние сигнализации KNX для визуального и звукового оповещения на посту охраны в сочетании с перекрёстной ссылкой на видеонаблюдение.

Anti-passback to KNX alarm sequence

Gallagher event: antiPassbackViol
 door name, cardholder name, timestamp in event payload

Node-RED:
 write GA 8/1/0 = true (APB alarm flag KNX)
 write GA 8/1/1 = cardholder ID (DPT 5.010 mapped ID)
 security desk touchpanel (MDT or Gira) shows APB alert

CCTV cross-reference (Bosch BVMS plugin):
 Bosch BVMS has optional Gallagher plugin:
 CC alarm event BVMS pops up camera view for that door
 For KNX-only installations without BVMS:
 APB KNX alarm GA triggers ONVIF camera snapshot
 via Node-RED http-request to camera snapshot URL
 snapshot stored locally for security review

Reset APB alarm:
 Security desk KNX button GA 8/1/0 = false
 Node-RED: POST /api/access_control/rest/v1/cardholders/
 {cardholder_id}/antipassback/reset
 CC resets cardholder APB zone status

Примечание по вводу в эксплуатацию: Протестируйте всю цепочку событие-KNX с тестовой картой, намеренно инициируя каждый тип события в последовательности – cardReadValid, doorForced и antiPassbackViol. Убедитесь, что правильные KNX GA обновляются в ETS6 Group Monitor в пределах ожидаемой задержки (менее 1 с для webhooks, менее 5 с для опроса).