Kontrola dostępu · Gallagher · REST API · Node-RED · KNX · 10 min czytania

Gallagher Command Centre REST API do KNX: Event Bridge z Node-RED

Gallagher Command Centre 8.x udostępnia udokumentowane REST API umożliwiające zewnętrznym systemom odbieranie zdarzeń drzwi i dostępu niemal w czasie rzeczywistym. Przekazywanie tych zdarzeń do adresów grupowych KNX przez Node-RED umożliwia automatyczne reakcje oświetlenia, HVAC i systemów bezpieczeństwa na aktywność czytnika kart — bez własnościowych modułów integracyjnych ani licencji oprogramowania pośredniego od firm trzecich.

Przegląd REST API Gallagher Command Centre

Gallagher Command Centre 8.x zawiera wbudowany serwer REST API. Interfejs API używa przepływu OAuth2 client credentials do uwierzytelniania. W ustawieniach serwera Command Centre utwórz klienta REST API z dostępem do zasobów Events i Doors. Zanotuj identyfikator klienta i sekret klienta — są one wyświetlane tylko raz podczas tworzenia.

Aby uzyskać token Bearer, wyślij żądanie POST do punktu końcowego tokenu. Token ma czas ważności 3600 sekund (jedna godzina). Node-RED obsługuje automatyczne odnawianie tokenu, przechowując znacznik czasu wygaśnięcia i ponownie żądając tokenu przed jego wygaśnięciem.

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)

Odpytywanie zdarzeń dostępu przez REST API

Punkt końcowy zdarzeń zwraca zdarzenia dostępu od podanego znacznika czasu ISO8601. Odpytuj ten punkt końcowy co 2–5 sekund w celu przetwarzania zdarzeń niemal w czasie rzeczywistym. Przechowuj znacznik czasu ostatniego przetworzonego zdarzenia w kontekście przepływu Node-RED jako następny punkt startowy odpytywania.

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

Zainstaluj pakiet node-red-contrib-gallagher przez npm w katalogu danych Node-RED. Pakiet ten dostarcza gotowe węzły wejściowe Gallagher, które automatycznie obsługują uwierzytelnianie i odpytywanie — skonfiguruj adres IP Command Centre, identyfikator klienta i sekret w panelu konfiguracji węzła.

Przepływ Node-RED: zdarzenie drzwi do adresu grupowego KNX

Główny przepływ Node-RED przetwarza zdarzenia Gallagher i zapisuje do adresów grupowych KNX przez węzeł zapisu KNX. Skonfiguruj węzeł zapisu KNX z adresem IP KNX IP Interface. Węzeł switch filtruje zdarzenia według typu i nazwy drzwi przed wywołaniem akcji 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%

Zdarzenie Gallagher	Adres grupowy KNX	DPT	Akcja
cardReadValid — wejście główne	3/0/1	1.001	Oświetlenie lobby na pełną moc
cardReadValid — wejście główne	4/0/1	1.001	Tryb zajętości HVAC
doorForced — dowolne drzwi	8/0/1	1.001	Przekaźnik syreny alarmowej WŁ
doorForced — dowolne drzwi	3/0/2	5.001 (255)	Oświetlenie ochronne 100 %
doorHeldOpen — dowolne drzwi	8/0/2	1.001	Przekaźnik ostrzeżenia przytrzymanych drzwi

Zdalne otwieranie drzwi z wejścia binarnego KNX

Odwrotny kierunek — wyzwalanie zwolnienia drzwi Gallagher z wejścia binarnego KNX — jest równie ważny. Personel recepcji z panelem dotykowym KNX może zdalnie zwolnić drzwi główne bez dedykowanego terminala kontroli dostępu.

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 do push zdarzeń w czasie rzeczywistym (CC 8.10+)

Command Centre 8.10 i nowsze obsługują webhooks — Gallagher wysyła zdarzenia do skonfigurowanego punktu końcowego HTTP w momencie ich wystąpienia, eliminując opóźnienie odpytywania wynoszące 2–5 sekund. W przypadku aplikacji krytycznych pod względem bezpieczeństwa, takich jak aktywacja syreny alarmowej, webhooks są zdecydowanie preferowane przed odpytywaniem.

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

Automatyzacja zajętości pięter w wielodostępnym biurowcu

W wielodostępnych biurowcach strefy Gallagher odpowiadają fizycznym piętrom. Każde piętro ma własną strefę czytnika kart, a Gallagher śledzi, którzy posiadacze kart aktualnie przebywają na każdym piętrze. Te dane o obecności w strefie są bezpośrednio przekazywane do zajętości strefy HVAC KNX w celu sterowania ogrzewaniem i wentylacją na poszczególnych piętrach.

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

Integracja anti-passback z alarmem KNX

Anti-passback (APB) uniemożliwia posiadaczowi karty dwukrotne wejście do strefy bez wcześniejszego jej opuszczenia — kluczowy środek odstraszający przed tailgatingiem. Gdy Gallagher wykryje naruszenie APB, zdarzenie może wywołać stan alarmu KNX dla wizualnego i dźwiękowego alertu przy stanowisku ochrony, w połączeniu z odniesieniem do zapisu CCTV.

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

Uwaga dotycząca uruchomienia: Przetestuj pełny łańcuch zdarzenie-KNX używając testowej karty i celowo wywołując każdy typ zdarzenia w kolejności — cardReadValid, doorForced i antiPassbackViol. Sprawdź, czy prawidłowe GA KNX są aktualizowane w ETS6 Group Monitor w oczekiwanym czasie oczekiwania (poniżej 1 s dla webhooks, poniżej 5 s dla odpytywania).

Powiązane artykuły

Integracja kontroli dostępu z KNX

Paxton Net2 do KNX: OEM SDK i automatyzacja zdarzeń drzwi

Integracja kontroli dostępu z KNX

SALTO i ASSA ABLOY systemy drzwi online: integracja KNX przez OSDP i BACnet

Solutions

Technologies

Knowledge

Company