Control de acceso · Gallagher · REST API · Node-RED · KNX · 10 min de lectura

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

Gallagher Command Centre 8.x expone una REST API documentada que permite a los sistemas externos recibir eventos de puerta y acceso en tiempo casi real. El puente de estos eventos a las direcciones de grupo KNX mediante Node-RED permite respuestas automáticas de iluminación, HVAC y seguridad a la actividad del lector de tarjetas — sin módulos de integración propietarios ni licencias de middleware de terceros.

Descripción general de la REST API de Gallagher Command Centre

Gallagher Command Centre 8.x incluye un servidor REST API integrado. La API utiliza el flujo de credenciales de cliente OAuth2 para la autenticación. En la configuración del servidor Command Centre, cree un cliente REST API con acceso a los recursos Events y Doors. Anote el ID de cliente y el secreto de cliente — solo se muestran una vez en el momento de la creación.

Para obtener un token Bearer, envíe una solicitud POST al punto de conexión del token. El token tiene una caducidad de 3600 segundos (una hora). Node-RED gestiona la renovación automática del token almacenando la marca de tiempo de caducidad y solicitando un nuevo token antes de que expire.

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)

Sondeo de eventos de acceso mediante la REST API

El punto de conexión de eventos devuelve eventos de acceso desde una marca de tiempo ISO8601 dada. Sondee este punto de conexión cada 2–5 segundos para el procesamiento de eventos en tiempo casi real. Almacene la marca de tiempo del último evento procesado en el contexto de flujo de Node-RED para usarla como siguiente punto de inicio del sondeo.

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

Instale el paquete node-red-contrib-gallagher mediante npm en el directorio de datos de Node-RED. Este paquete proporciona nodos de entrada Gallagher preconstruidos que gestionan automáticamente la autenticación y el sondeo — configure la dirección IP del Command Centre, el ID de cliente y el secreto en el panel de configuración del nodo.

Flujo Node-RED: evento de puerta a dirección de grupo KNX

El flujo Node-RED principal procesa los eventos Gallagher y escribe en las direcciones de grupo KNX mediante el nodo de escritura KNX. Configure el nodo de escritura KNX con la dirección IP de su KNX IP Interface. El nodo switch filtra los eventos por tipo y nombre de puerta antes de activar las acciones 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	Dirección de grupo KNX	DPT	Acción
cardReadValid — Entrada principal	3/0/1	1.001	Luces vestíbulo a plena potencia
cardReadValid — Entrada principal	4/0/1	1.001	Modo ocupación HVAC
doorForced — cualquier puerta	8/0/1	1.001	Relé sirena alarma ON
doorForced — cualquier puerta	3/0/2	5.001 (255)	Luces de seguridad 100 %
doorHeldOpen — cualquier puerta	8/0/2	1.001	Relé aviso puerta mantenida abierta

Apertura remota de puerta desde entrada binaria KNX

La dirección inversa — activar una apertura de puerta Gallagher desde una entrada binaria KNX — es igualmente importante. El personal de recepción con un panel táctil KNX puede abrir la puerta de entrada principal de forma remota sin un terminal de control de acceso dedicado.

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 para push de eventos en tiempo real (CC 8.10+)

Command Centre 8.10 y versiones posteriores admiten webhooks — Gallagher envía eventos a un punto de conexión HTTP configurado en el momento en que ocurren, eliminando el retraso de sondeo de 2 a 5 segundos. Para aplicaciones críticas de seguridad como la activación de sirenas de alarma, los webhooks son claramente preferibles al sondeo.

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

Automatización de ocupación de plantas en edificios multiarrendatario

En edificios de oficinas multiarrendatario, las zonas Gallagher corresponden a plantas físicas. Cada planta tiene su propia zona de lector de tarjetas, y Gallagher rastrea qué titulares de tarjetas se encuentran actualmente en cada planta. Estos datos de presencia en zona se trasladan directamente a la ocupación de zona HVAC de KNX para el control de calefacción y ventilación por planta.

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

Integración anti-passback con alarma KNX

El anti-passback (APB) impide que un titular de tarjeta utilice su tarjeta para entrar en una zona dos veces sin haberla abandonado previamente — un elemento disuasorio clave contra el tailgating. Cuando Gallagher detecta una violación APB, el evento puede activar un estado de alarma KNX para alerta visual y sonora en el puesto de seguridad, combinada con referencias cruzadas a 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 de puesta en marcha: Pruebe la cadena completa evento-KNX utilizando una tarjeta de prueba y activando intencionalmente cada tipo de evento en secuencia — cardReadValid, doorForced y antiPassbackViol. Verifique que los GA KNX correctos se actualizan en ETS6 Group Monitor dentro de la latencia esperada (menos de 1 s para webhooks, menos de 5 s para sondeo).

Guías relacionadas

Integración control de acceso y KNX

Paxton Net2 a KNX: OEM SDK y automatización de eventos de puerta

Integración control de acceso y KNX

SALTO y ASSA ABLOY sistemas de puertas en línea: integración KNX mediante OSDP y BACnet

Solutions

Technologies

Knowledge

Company