Controllo accessi · Gallagher · REST API · Node-RED · KNX · 10 min di lettura

Gallagher Command Centre REST API verso KNX: Event Bridge con Node-RED

Gallagher Command Centre 8.x espone una REST API documentata che consente ai sistemi esterni di ricevere eventi di porta e accesso in quasi tempo reale. Il bridging di questi eventi verso gli indirizzi di gruppo KNX tramite Node-RED consente risposte automatiche di illuminazione, HVAC e sicurezza all'attività dei lettori badge — senza moduli di integrazione proprietari o licenze middleware di terze parti.

Panoramica della REST API di Gallagher Command Centre

Gallagher Command Centre 8.x include un server REST API integrato. L'API utilizza il flusso client credentials OAuth2 per l'autenticazione. Nelle impostazioni del server Command Centre, creare un client REST API con accesso alle risorse Events e Doors. Annotare l'ID client e il segreto client — vengono mostrati solo una volta al momento della creazione.

Per ottenere un token Bearer, inviare una richiesta POST all'endpoint del token. Il token ha una scadenza di 3600 secondi (un'ora). Node-RED gestisce il rinnovo automatico del token memorizzando il timestamp di scadenza e richiedendo un nuovo token prima che scada.

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 degli eventi di accesso tramite REST API

L'endpoint degli eventi restituisce gli eventi di accesso da un dato timestamp ISO8601. Effettuare il polling di questo endpoint ogni 2–5 secondi per l'elaborazione degli eventi in quasi tempo reale. Memorizzare il timestamp dell'ultimo evento elaborato nel contesto del flusso Node-RED da utilizzare come prossimo punto di partenza del polling.

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

Installare il pacchetto node-red-contrib-gallagher tramite npm nella directory dati di Node-RED. Questo pacchetto fornisce nodi di input Gallagher preconfigurati che gestiscono automaticamente autenticazione e polling — configurare l'indirizzo IP del Command Centre, l'ID client e il segreto nel pannello di configurazione del nodo.

Flusso Node-RED: evento porta verso indirizzo di gruppo KNX

Il flusso Node-RED principale elabora gli eventi Gallagher e scrive sugli indirizzi di gruppo KNX tramite il nodo di scrittura KNX. Configurare il nodo di scrittura KNX con l'indirizzo IP del KNX IP Interface. Il nodo switch filtra gli eventi per tipo e nome porta prima di attivare le azioni 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%

Evento Gallagher	Indirizzo di gruppo KNX	DPT	Azione
cardReadValid — Ingresso principale	3/0/1	1.001	Luci lobby a piena potenza
cardReadValid — Ingresso principale	4/0/1	1.001	Modalità occupazione HVAC
doorForced — qualsiasi porta	8/0/1	1.001	Relè sirena allarme ON
doorForced — qualsiasi porta	3/0/2	5.001 (255)	Luci di sicurezza 100 %
doorHeldOpen — qualsiasi porta	8/0/2	1.001	Relè avviso porta mantenuta aperta

Apertura remota della porta da ingresso binario KNX

La direzione inversa — attivare un'apertura di porta Gallagher da un ingresso binario KNX — è ugualmente importante. Il personale della reception con un pannello touch KNX può aprire l'ingresso principale da remoto senza un terminale di controllo accessi dedicato.

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

Webhook Gallagher per push eventi in tempo reale (CC 8.10+)

Command Centre 8.10 e versioni successive supportano i webhook — Gallagher invia gli eventi a un endpoint HTTP configurato non appena si verificano, eliminando il ritardo di polling di 2–5 secondi. Per applicazioni critiche per la sicurezza come l'attivazione di sirene di allarme, i webhook sono fortemente preferiti al polling.

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

Automazione dell'occupazione per piano in edifici multi-tenant

Negli edifici per uffici multi-tenant, le zone Gallagher corrispondono ai piani fisici. Ogni piano ha la propria zona lettore badge, e Gallagher tiene traccia di quali titolari di badge si trovano attualmente su ciascun piano. Questi dati di presenza nella zona vengono trasferiti direttamente all'occupazione della zona HVAC KNX per il controllo del riscaldamento e della ventilazione per piano.

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

Integrazione anti-passback con allarme KNX

L'anti-passback (APB) impedisce a un titolare di badge di utilizzare la propria carta per entrare in una zona due volte senza averla prima lasciata — un deterrente fondamentale contro il tailgating. Quando Gallagher rileva una violazione APB, l'evento può attivare uno stato di allarme KNX per un avviso visivo e sonoro alla postazione di sicurezza, combinato con un riferimento incrociato alle telecamere 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

Nota di messa in servizio: Testare l'intera catena evento-KNX utilizzando una carta di test e attivando intenzionalmente ciascun tipo di evento in sequenza — cardReadValid, doorForced e antiPassbackViol. Verificare che i GA KNX corretti si aggiornino in ETS6 Group Monitor entro la latenza prevista (meno di 1 s per i webhook, meno di 5 s per il polling).

Guide correlate

Integrazione controllo accessi e KNX

Paxton Net2 verso KNX: OEM SDK e automazione degli eventi porta

Integrazione controllo accessi e KNX

SALTO e ASSA ABLOY sistemi porta online: integrazione KNX tramite OSDP e BACnet

Solutions

Technologies

Knowledge

Company