ControlID IdFace

Guía completa para instalar, configurar y conectar los dispositivos ControlID IdFace con el sistema de control de acceso de Vitality Gym.

Tip

Antes de seguir esta guía, asegúrate de tener configurada la Raspberry Pi como puente de red. Consulta la guía de Raspberry Pi para más detalles.

Requisitos Previos

• Dispositivos ControlID IdFace conectados a la VLAN del gimnasio (192.168.30.0/24)
• Raspberry Pi configurada con Tailscale y Traefik (ver Raspberry Pi)
• API de Vitality Gym desplegada y accesible
• Acceso de administrador a la interfaz web de los dispositivos

Arquitectura del Sistema

┌──────────────────┐       ┌────────────────────┐       ┌──────────────────┐
│   IdFace         │       │   Raspberry Pi      │       │   VPS            │
│   (Talanquera)   │──────►│   Traefik proxy     │──────►│   API Hono       │
│   192.168.30.Y   │       │   192.168.30.X      │       │   api.vitality-  │
│                  │◄──────│                     │       │   gym.com        │
│   IdFace         │       │   (Tailscale Subnet │       │                  │
│   (Zona Premium) │──────►│    Routing)         │       │                  │
│   192.168.30.Z   │       └────────────────────┘       └──────────────────┘
└──────────────────┘

Flujos de comunicación

Dirección	Descripción	Protocolo
VPS → Dispositivos	Enrolar usuarios, captura facial, consultar logs	HTTP vía Tailscale
Dispositivos → RPI → VPS	Eventos de acceso en tiempo real (Monitor)	HTTP → Traefik → HTTPS

---

Paso 1: Conexión Física y Red

1. Conectar los dispositivos a la red ethernet de la VLAN del gimnasio (192.168.30.0/24)

2. Verificar conectividad — Los dispositivos deben obtener IP automáticamente por DHCP o configurar IP estática:

   # Desde la Raspberry Pi, verificar que los dispositivos responden
   ping 192.168.30.Y    # Talanquera
   ping 192.168.30.Z    # Premium

3. Reservar las IPs en el router/DHCP para que no cambien

---

Paso 2: Acceso a la Interfaz Web

Cada dispositivo IdFace tiene una interfaz web de administración accesible por su IP.

1. Abrir en el navegador: http://192.168.30.Y (Talanquera) o http://192.168.30.Z (Premium)
2. Credenciales por defecto: admin / admin

Caution

Cambiar las contraseñas por defecto inmediatamente después de la configuración inicial. Actualizar también las variables de entorno en la API.

---

Paso 3: Configuración Manual del Dispositivo

Estos pasos se realizan desde la interfaz web del dispositivo:

3.1 Configuración de Red

Verificar que la configuración de red sea correcta:

• IP: Estática o reservada en DHCP
• Máscara: 255.255.255.0
• Gateway: Gateway de la VLAN
• DNS: DNS del router o público (8.8.8.8)

3.2 Fecha y Hora

Configurar la zona horaria correcta:

• Zona horaria: America/Bogota (UTC-5)
• NTP: Habilitado, apuntando a pool.ntp.org

3.3 Credenciales de Administrador

Cambiar usuario y contraseña del administrador:

# También se puede hacer vía API:
curl -X POST http://192.168.30.Y/change_password.fcgi?session=SESSION \
  -H "Content-Type: application/json" \
  -d '{"password": "NUEVA_CONTRASEÑA_SEGURA"}'

---

Paso 4: Configuración del Monitor (vía API)

El paso más importante: configurar el Monitor para que el dispositivo envíe eventos de acceso a la API de Vitality Gym.

4.1 Opción A: Desde la Interfaz de Admin (Recomendado)

Desde el panel de administración de Vitality Gym:

1. Ir a Control de Acceso > Dispositivos
2. Click en “Configurar” en el dispositivo deseado
3. Esto ejecuta internamente POST /api/v1/access-control/devices/:deviceType/configure

El sistema automáticamente envía la siguiente configuración al dispositivo:

{
  "monitor": {
    "hostname": "192.168.30.X",
    "port": "80",
    "path": "api/v1/access-control/notifications",
    "request_timeout": "5000"
  },
  "online_client": {
    "enabled": true
  }
}

Note

La ruta api/v1/access-control/notifications sigue la convención por defecto de ControlID (api/notifications). El dispositivo automáticamente agrega los sufijos /dao, /device_is_alive, etc. a esta ruta base.

4.2 Opción B: Configuración Manual vía API del Dispositivo

Si prefieres configurar directamente el dispositivo:

# 1. Iniciar sesión en el dispositivo
SESSION=$(curl -s -X POST http://192.168.30.Y/login.fcgi \
  -H "Content-Type: application/json" \
  -d '{"login":"admin","password":"admin"}' | jq -r '.session')

echo "Sesión: $SESSION"

# 2. Configurar el monitor
curl -X POST "http://192.168.30.Y/set_configuration.fcgi?session=$SESSION" \
  -H "Content-Type: application/json" \
  -d '{
    "monitor": {
      "hostname": "192.168.30.X",
      "port": "80",
      "path": "api/v1/access-control/notifications",
      "request_timeout": "5000"
    }
  }'

# 3. Verificar la configuración
curl -X POST "http://192.168.30.Y/get_configuration.fcgi?session=$SESSION" \
  -H "Content-Type: application/json" \
  -d '{"monitor": ["hostname", "port", "path", "request_timeout"]}'

Tip

La hostname debe ser la IP de la Raspberry Pi en la VLAN, ya que los dispositivos no tienen acceso directo a internet. Traefik en la RPI se encarga de reenviar las peticiones al VPS.

---

Paso 5: Variables de Entorno en la API

Agregar las siguientes variables al .env de la API:

# ============ CONTROLID ACCESS CONTROL ============

# IP de los dispositivos IdFace (accesibles vía Tailscale Subnet Routing)
CONTROLID_TURNSTILE_IP=192.168.30.Y
CONTROLID_PREMIUM_IP=192.168.30.Z

# Credenciales de acceso a los dispositivos
CONTROLID_TURNSTILE_LOGIN=admin
CONTROLID_TURNSTILE_PASSWORD=TU_CONTRASEÑA_SEGURA
CONTROLID_PREMIUM_LOGIN=admin
CONTROLID_PREMIUM_PASSWORD=TU_CONTRASEÑA_SEGURA

# URL del callback — IP de la Raspberry Pi en la VLAN
# Los dispositivos hacen POST HTTP aquí, Traefik reenvía a la API
CONTROLID_API_CALLBACK_URL=http://192.168.30.X

Caution

Reemplazar X, Y, Z con las IPs reales de la VLAN. No usar direcciones Tailscale aquí — los dispositivos solo ven la VLAN local.

---

Paso 6: Enrolamiento de Usuarios

Una vez configurados los dispositivos, enrolar usuarios desde la interfaz de admin:

1. Enrolar usuario (PIN + datos): El admin selecciona un usuario y ejecuta el enrolamiento. Esto crea el usuario en ambos dispositivos con su cédula como PIN.

2. Captura facial: El usuario se para frente al dispositivo Talanquera. El admin inicia la captura remota. La imagen se sincroniza automáticamente al dispositivo Premium.

3. Verificar: El usuario prueba el acceso con su rostro o PIN en ambos dispositivos.

---

Endpoints del Monitor ControlID

El dispositivo envía eventos a las siguientes rutas (construidas como hostname:port/path/endpoint):

Endpoint	URL Final	Descripción
dao	/api/v1/access-control/notifications/dao	Eventos de access_logs, alarm_logs, cards, templates
device_is_alive	/api/v1/access-control/notifications/device_is_alive	Heartbeat periódico (cada 30s por defecto)
catra_event	/api/v1/access-control/notifications/catra_event	Eventos de giro de talanquera (iDBlock)
door	/api/v1/access-control/notifications/door	Cambios de estado de puerta
secbox	/api/v1/access-control/notifications/secbox	Cambios de estado del relay SecBox
operation_mode	/api/v1/access-control/notifications/operation_mode	Cambios de modo de operación

Note

Actualmente la API solo implementa los handlers para dao y device_is_alive. Los demás eventos se pueden agregar según se necesite.

---

Formato del Evento DAO

El evento más importante es el dao, que se envía cuando cambian las tablas de acceso:

{
  "object_changes": [
    {
      "object": "access_logs",
      "type": "inserted",
      "values": {
        "id": "519",
        "time": "1532977090",
        "event": "7",
        "device_id": "478435",
        "identifier_id": "0",
        "user_id": "1234567890",
        "portal_id": "1",
        "identification_rule_id": "0",
        "card_value": "0",
        "log_type_id": "-1"
      }
    }
  ],
  "device_id": 478435
}

Códigos de Evento

Código	Evento
7	Acceso permitido
6	Acceso denegado
12	Sin identificación (desconocido)

---

Verificación y Troubleshooting

Verificar que el monitor está configurado

# Obtener configuración actual del monitor
SESSION=$(curl -s -X POST http://192.168.30.Y/login.fcgi \
  -H "Content-Type: application/json" \
  -d '{"login":"admin","password":"admin"}' | jq -r '.session')

curl -X POST "http://192.168.30.Y/get_configuration.fcgi?session=$SESSION" \
  -H "Content-Type: application/json" \
  -d '{"monitor": ["hostname", "port", "path", "request_timeout", "alive_interval"]}'

Respuesta esperada:

{
  "monitor": {
    "hostname": "192.168.30.X",
    "port": "80",
    "path": "api/v1/access-control/notifications",
    "request_timeout": "5000",
    "alive_interval": "30000"
  }
}

El dispositivo no envía eventos

1. Verificar que el monitor está configurado (ver arriba)
2. Verificar que la RPI es alcanzable desde el dispositivo:

   # Desde la RPI, simular un evento
   curl -X POST http://localhost/api/v1/access-control/notifications/dao \
     -H "Content-Type: application/json" \
     -d '{"object_changes": [{"object": "access_logs", "type": "inserted", "values": {"user_id": "0"}}], "device_id": 123}'

3. Verificar los logs de Traefik:

   docker logs $(docker ps -q --filter "name=traefik") --tail 50

El heartbeat no llega

Verificar que el intervalo de heartbeat está configurado:

curl -X POST "http://192.168.30.Y/set_configuration.fcgi?session=$SESSION" \
  -H "Content-Type: application/json" \
  -d '{"monitor": {"alive_interval": "30000"}}'

Restablecer configuración del dispositivo

Si necesitas volver a la configuración de fábrica:

# Reset completo (usar con precaución)
curl -X POST "http://192.168.30.Y/reset_configuration.fcgi?session=$SESSION"

Caution

El reset borrará TODOS los usuarios y configuraciones del dispositivo. Tendrás que re-enrolar todos los usuarios con la función de sincronización masiva.

---

Referencia de la API ControlID

Para más información sobre la API de los dispositivos ControlID:

Documentación oficial de ControlID API Access Control Devices — guía completa de endpoints y configuración

Endpoints del dispositivo más usados

Endpoint	Descripción
POST /login.fcgi	Iniciar sesión (obtener token de sesión)
POST /create_objects.fcgi?session=X	Crear usuarios, PINs, reglas
POST /load_objects.fcgi?session=X	Consultar usuarios, logs
POST /destroy_objects.fcgi?session=X	Eliminar objetos
POST /set_configuration.fcgi?session=X	Modificar configuración (monitor, red, etc.)
POST /get_configuration.fcgi?session=X	Consultar configuración actual
POST /remote_enroll.fcgi?session=X	Captura facial remota
POST /execute_actions.fcgi?session=X	Abrir puerta/talanquera remotamente
POST /system_information.fcgi?session=X	Información del sistema
POST /user_set_image.fcgi?session=X&user_id=Y	Subir foto facial
POST /user_get_image.fcgi?session=X	Descargar foto facial