Contrôle d'accès · Gallagher · REST API · Node-RED · KNX · 10 min de lecture

Gallagher Command Centre REST API vers KNX : Event Bridge avec Node-RED

Gallagher Command Centre 8.x expose une API REST documentée qui permet aux systèmes externes de recevoir des événements de porte et d'accès en quasi-temps réel. La passerelle de ces événements vers les adresses de groupe KNX via Node-RED permet des réponses automatiques de l'éclairage, de la CVC et de la sécurité à l'activité des lecteurs de badge — sans modules d'intégration propriétaires ni licences de middleware tiers.

Vue d'ensemble de l'API REST Gallagher Command Centre

Gallagher Command Centre 8.x inclut un serveur API REST intégré. L'API utilise le flux de credentials client OAuth2 pour l'authentification. Dans les paramètres du serveur Command Centre, créez un client API REST avec accès aux ressources Events et Doors. Notez l'identifiant client et le secret client — ils ne sont affichés qu'une seule fois lors de la création.

Pour obtenir un token Bearer, envoyez une requête POST au point de terminaison du token. Le token a une expiration de 3600 secondes (une heure). Node-RED gère le renouvellement automatique du token en stockant l'horodatage d'expiration et en redemandant un token avant son expiration.

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)

Interrogation des événements d'accès via l'API REST

Le point de terminaison des événements retourne les événements d'accès depuis un horodatage ISO8601 donné. Interrogez ce point de terminaison toutes les 2 à 5 secondes pour un traitement quasi-temps réel des événements. Stockez l'horodatage du dernier événement traité dans le contexte de flux Node-RED pour l'utiliser comme prochain point de départ d'interrogation.

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

Installez le package node-red-contrib-gallagher via npm dans le répertoire de données Node-RED. Ce package fournit des nœuds d'entrée Gallagher préconstruits qui gèrent automatiquement l'authentification et l'interrogation — configurez l'adresse IP du Command Centre, l'identifiant client et le secret dans le panneau de configuration du nœud.

Flux Node-RED : événement de porte vers adresse de groupe KNX

Le flux Node-RED principal traite les événements Gallagher et écrit vers les adresses de groupe KNX via le nœud d'écriture KNX. Configurez le nœud d'écriture KNX avec l'adresse IP de votre KNX IP Interface. Le nœud switch filtre les événements par type et nom de porte avant de déclencher les actions 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%

Événement Gallagher	Adresse de groupe KNX	DPT	Action
cardReadValid — Entrée principale	3/0/1	1.001	Éclairage hall pleine puissance
cardReadValid — Entrée principale	4/0/1	1.001	Mode occupation CVC
doorForced — toute porte	8/0/1	1.001	Relais sirène alarme ON
doorForced — toute porte	3/0/2	5.001 (255)	Éclairage sécurité 100 %
doorHeldOpen — toute porte	8/0/2	1.001	Relais avertissement porte maintenue

Ouverture de porte à distance depuis une entrée binaire KNX

La direction inverse — déclencher une ouverture de porte Gallagher depuis une entrée binaire KNX — est tout aussi importante. Le personnel de réception avec un panneau tactile KNX peut ouvrir la porte d'entrée principale à distance sans terminal de contrôle d'accès dédié.

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 pour le push d'événements en temps réel (CC 8.10+)

Command Centre 8.10 et versions ultérieures prennent en charge les webhooks — Gallagher pousse les événements vers un point de terminaison HTTP configuré dès qu'ils se produisent, éliminant le délai d'interrogation de 2 à 5 secondes. Pour les applications critiques en matière de sécurité comme l'activation de sirènes d'alarme, les webhooks sont fortement préférés à l'interrogation.

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

Automatisation de l'occupation par étage dans un immeuble multi-locataires

Dans les immeubles de bureaux multi-locataires, les zones Gallagher correspondent aux étages physiques. Chaque étage dispose de sa propre zone de lecteur de badge, et Gallagher suit quels titulaires de carte se trouvent actuellement sur chaque étage. Ces données de présence en zone sont directement transmises à l'occupation de zone CVC KNX pour le contrôle du chauffage et de la ventilation par étage.

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

Intégration anti-passback avec alarme KNX

L'anti-passback (APB) empêche un titulaire de badge d'utiliser sa carte pour entrer dans une zone deux fois sans en être sorti — un moyen de dissuasion essentiel contre le passage en file. Lorsque Gallagher détecte une violation APB, l'événement peut déclencher un état d'alarme KNX pour une alerte visuelle et sonore au poste de sécurité, combinée à une référence croisée 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

Note de mise en service : Testez la chaîne complète événement-KNX en utilisant une carte de test et en déclenchant intentionnellement chaque type d'événement en séquence — cardReadValid, doorForced et antiPassbackViol. Vérifiez que les GA KNX corrects se mettent à jour dans ETS6 Group Monitor dans la latence attendue (moins de 1 s pour les webhooks, moins de 5 s pour l'interrogation).

Guides associés

Intégration contrôle d'accès et KNX

Paxton Net2 vers KNX : OEM SDK et automatisation des événements de porte

Intégration contrôle d'accès et KNX

SALTO et ASSA ABLOY systèmes de portes en ligne : intégration KNX via OSDP et BACnet

Solutions

Technologies

Knowledge

Company