Zutrittskontrolle · Gallagher · REST API · Node-RED · KNX · 10 Min. Lesezeit

Gallagher Command Centre REST API zu KNX: Event Bridge mit Node-RED

Gallagher Command Centre 8.x verfügt über eine dokumentierte REST API, über die externe Systeme Tür- und Zutrittsereignisse nahezu in Echtzeit empfangen können. Die Überbrückung dieser Ereignisse zu KNX-Gruppenadressen über Node-RED ermöglicht automatische Beleuchtungs-, HLK- und Sicherheitsreaktionen auf Kartenlesevorgänge — ohne proprietäre Integrationsmodule oder Middleware-Lizenzen von Drittanbietern.

Übersicht der Gallagher Command Centre REST API

Gallagher Command Centre 8.x enthält einen integrierten REST-API-Server. Die API verwendet den OAuth2-Client-Credentials-Flow zur Authentifizierung. Erstellen Sie in den Command Centre-Servereinstellungen einen REST-API-Client mit Zugriff auf die Ressourcen Events und Doors. Notieren Sie die Client-ID und das Client-Secret — diese werden nur einmalig bei der Erstellung angezeigt.

Um ein Bearer-Token zu erhalten, senden Sie eine POST-Anfrage an den Token-Endpunkt. Das Token hat eine Ablaufzeit von 3600 Sekunden (eine Stunde). Node-RED übernimmt die automatische Token-Erneuerung, indem der Ablaufzeitstempel gespeichert und ein neues Token vor dem Ablauf angefordert wird.

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)

Polling von Zutrittsereignissen über die REST API

Der Events-Endpunkt gibt Zutrittsereignisse seit einem bestimmten ISO8601-Zeitstempel zurück. Fragen Sie diesen Endpunkt alle 2–5 Sekunden für nahezu echtzeitnahe Ereignisverarbeitung ab. Speichern Sie den Zeitstempel des zuletzt verarbeiteten Ereignisses im Node-RED-Flow-Kontext als nächsten Polling-Startpunkt.

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

Installieren Sie das Paket node-red-contrib-gallagher über npm im Node-RED-Datenverzeichnis. Dieses Paket stellt vorgefertigte Gallagher-Eingabeknoten bereit, die Authentifizierung und Polling automatisch übernehmen — konfigurieren Sie die IP-Adresse des Command Centre, die Client-ID und das Secret im Knotenkonfigurationspanel.

Node-RED-Flow: Türereignis zu KNX-Gruppenadresse

Der zentrale Node-RED-Flow verarbeitet Gallagher-Ereignisse und schreibt über den KNX-Write-Knoten auf KNX-Gruppenadressen. Konfigurieren Sie den KNX-Write-Knoten mit der IP-Adresse Ihres KNX IP Interface. Der Switch-Knoten filtert Ereignisse nach Typ und Türname, bevor KNX-Aktionen ausgelöst werden.

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-Ereignis	KNX-Gruppenadresse	DPT	Aktion
cardReadValid — Haupteingang	3/0/1	1.001	Lobbyleuchten voll ein
cardReadValid — Haupteingang	4/0/1	1.001	HLK-Belegungsmodus
doorForced — beliebige Tür	8/0/1	1.001	Alarmsirenrelais EIN
doorForced — beliebige Tür	3/0/2	5.001 (255)	Sicherheitsleuchten 100 %
doorHeldOpen — beliebige Tür	8/0/2	1.001	Relais für offen gehaltene Tür

Fernöffnung über KNX-Binäreingang

Die umgekehrte Richtung — das Auslösen einer Gallagher-Türfreigabe über einen KNX-Binäreingang — ist ebenso wichtig. Empfangspersonal mit einem KNX-Touchpanel kann die Haupteingangstür aus der Ferne freigeben, ohne ein dediziertes Zutrittskontrollterminal.

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

Gallagher Webhooks für Echtzeit-Event-Push (CC 8.10+)

Command Centre 8.10 und später unterstützt Webhooks — Gallagher sendet Ereignisse an einen konfigurierten HTTP-Endpunkt, sobald sie auftreten, und eliminiert so die 2–5-Sekunden-Polling-Verzögerung. Für sicherheitskritische Anwendungen wie die Aktivierung von Alarmsirenen sind Webhooks dem Polling eindeutig vorzuziehen.

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

Belegungsautomatisierung im Mehrmieterbürogebäude

In Mehrmieterbürogebäuden entsprechen Gallagher-Zonen physischen Etagen. Jede Etage hat ihre eigene Kartenleserzone, und Gallagher verfolgt, welche Karteninhaber sich aktuell auf welcher Etage befinden. Diese Zonenbestätigungsdaten werden direkt auf KNX-HLK-Zonenbelegung für etagenweise Heizungs- und Lüftungssteuerung übertragen.

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-Integration mit KNX-Alarm

Anti-Passback (APB) verhindert, dass ein Karteninhaber seine Karte verwendet, um eine Zone zweimal zu betreten, ohne sie zuvor verlassen zu haben — ein wichtiges Abschreckmittel gegen Tailgating. Wenn Gallagher einen APB-Verstoß erkennt, kann das Ereignis einen KNX-Alarmzustand für visuelle und akustische Alarmierung am Sicherheitspult auslösen, kombiniert mit CCTV-Querverweisen.

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

Inbetriebnahmehinweis: Testen Sie die gesamte Ereignis-zu-KNX-Kette mit einer Test-Karte und lösen Sie absichtlich jeden Ereignistyp in Folge aus — cardReadValid, doorForced und antiPassbackViol. Überprüfen Sie, ob die korrekten KNX-GAs im ETS6 Group Monitor innerhalb der erwarteten Latenz aktualisiert werden (unter 1 s für Webhooks, unter 5 s für Polling).

Solutions

Technologies

Knowledge

Company