Контроль доступа · 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 с для опроса).

Solutions

Technologies

Knowledge

Company