Guía de uso — Hanwha Zone Bridge¶

Cómo operar la integración una vez instalada: entender el panel, nombrar las zonas y armar las reglas y alarmas por zona en Milestone.

1. El modelo mental en una pantalla¶

  CÁMARA HANWHA              HANWHA ZONE BRIDGE            MILESTONE XPROTECT
  ─────────────              ──────────────────            ──────────────────

  DefinedArea 1  ──────────►  slot 1  ──────────────────►  Hanwha Intrusion_1
  DefinedArea 2  ──────────►  slot 2  ──────────────────►  Hanwha Intrusion_2
  DefinedArea 9  ──► (Mode vacío: ignorada)
  Line 1         ──────────►  slot 1  ──────────────────►  Hanwha Line Crossing_1

  SUNAPI                      mapeo persistido             Analytics Events
  eventstatus.cgi             mapeo-slots.json             TCP 9090

Tres ideas que hay que tener claras:

Los tipos de evento son globales y fijos. Son 20 en total y los comparten todas las cámaras. No se crea un tipo por cámara.
El _N es un slot lógico, no el número de zona de la cámara. Las dos numeraciones se muestran siempre juntas en el panel.
La cámara es el origen del evento. Por eso la alarma se define como tipo + cámara, y ahí está la discriminación que buscabas.

2. El panel¶

http://<servidor>:8099

Panel de la integración

Columna izquierda — cámaras y zonas¶

Cada tarjeta es una cámara. El punto de color indica el estado:

Color	Estado	Significa
🟢 verde	`EnLinea`	Stream de eventos abierto y funcionando
🟡 ámbar	`Conectando` / `Reintentando`	Reconectando con backoff
🔴 rojo	`Fallida` / `Detenida`	Más de 5 errores seguidos, o cámara dada de baja

Dentro de cada cámara, una fila por zona o línea:

☑  [Hanwha Intrusion_2]   CAM-01 / Zona 2        área 2    [probar]
│         │                        │                  │          │
│         │                        │                  │          └─ envía un evento de prueba
│         │                        │                  └─ índice real en la cámara
│         │                        └─ nombre editable
│         └─ el Analytics Event Type que se va a emitir
└─ habilita o deshabilita el envío de esa zona

Columna derecha — eventos en vivo¶

Las últimas 300 transiciones, en verde los inicios y en gris los fines. Sirve para confirmar que la zona correcta se activa antes de armar la alarma.

06:08:12   fin    CAM-01  Hanwha Intrusion_1 End  [CAM-01 / Zona 1]
06:08:11  INICIO  CAM-01  Hanwha Intrusion_2      [CAM-01 / Zona 2]
06:08:11  INICIO  CAM-01  Hanwha Intrusion_1      [CAM-01 / Zona 1]

Si un evento fue descartado por Milestone, la línea termina en << RECHAZADO y aparece en rojo.

3. Nombrar las zonas¶

La cámara no guarda nombres: sólo DefinedAreaID 1, 2, 9. El nombre vive en el panel.

Hacé clic en el campo de texto de la zona.
Escribí el nombre real: Portón Norte, Playa de carga, Perímetro sur.
Salí del campo. Se guarda solo.

El nombre viaja en la descripción del evento, así que el operador lo ve en el Smart Client, y te sirve para nombrar la definición de alarma.

Para saber qué zona es cuál, abrí el web de la cámara y mirá las áreas dibujadas. El panel muestra el índice real (área 2) al lado de cada fila, que es el mismo número que muestra la cámara.

4. Armar una alarma por zona en Milestone¶

Este es el objetivo de todo el desarrollo.

En Management Client → Alarmas → Definiciones de alarma → Agregar nueva:

Campo	Valor
Nombre	`Intrusión — Portón Norte`
Mensaje de disparo → Grupo de tipos de evento	`Eventos analíticos`
Mensaje de disparo → Tipo de evento	`Hanwha Intrusion_2`
Fuentes	la cámara `CAM-01`

Y listo: esa alarma se dispara sólo cuando hay intrusión en la zona 2 de esa cámara. Otra alarma con Hanwha Intrusion_1 y la misma cámara cubre la zona 1, con distinta prioridad, distinto destinatario y distinto procedimiento operativo si hace falta.

Verificación de que discrimina¶

Prueba real hecha en el laboratorio: se enviaron los dos tipos, con una sola definición de alarma creada (la de zona 2).

envío  Hanwha Intrusion_1  ->  aceptado
envío  Hanwha Intrusion_2  ->  aceptado

alarmas generadas:
2026-09-21 02:58:22 >> Intrusion - Porton Norte (CAM-01 zona 2) >> Hanwha Intrusion_2

Los dos eventos entraron, pero sólo el de zona 2 generó alarma, porque sólo esa zona tenía definición. Es exactamente el comportamiento buscado.

Reglas de grabación con duración¶

Como se emiten inicio y fin, se puede grabar mientras dure el evento:

Paso de la regla	Valor
Evento de inicio	`Hanwha Intrusion_2`
Acción	Iniciar grabación en `CAM-01`
Evento de fin	`Hanwha Intrusion_2 End`

El cruce de línea es instantáneo por naturaleza. Se emite el End por consistencia, pero probablemente no lo uses en reglas.

5. Convivencia con el evento del driver¶

La integración no reemplaza al driver nativo de Hanwha: convive con él. Cada intrusión va a generar dos cosas:

Origen	Evento	Tiene zona
Driver de Milestone	`IntrusionStart`	❌
Hanwha Zone Bridge	`Hanwha Intrusion_2`	✅

Usá el nuestro en las reglas nuevas. Si ya tenías alarmas armadas sobre IntrusionStart, siguen funcionando igual — conviene revisarlas para no tener alarmas duplicadas por el mismo hecho físico.

6. Configuración¶

C:\Program Files\HanwhaZoneBridge\appsettings.json. Después de editar, reiniciá el servicio:

Restart-Service HanwhaZoneBridge

Clave	Por defecto	Qué hace
`Urls`	`http://0.0.0.0:8099`	Dirección del panel
`EventServer.Puerto`	`9090`	Puerto de Analytics Events
`Mapeo.SlotsPorCamara`	`5`	Zonas y líneas máximas por cámara
`Puente.MinutosEntreRefrescos`	`5`	Cada cuánto relee el inventario de Milestone
`Puente.MsAntiRebote`	`1000`	Mínimo entre dos inicios de la misma zona
`Puente.EmitirEventosDeFin`	`true`	Emitir los `_N End`
`MipHelper.PatronesDeModelo`	`hanwha, wisenet, samsung`	Qué hardware se considera Hanwha

El anti-rebote¶

Una analítica que oscila puede disparar muchas veces por segundo. MsAntiRebote pone un mínimo entre dos inicios de la misma zona. Los fines siempre pasan, para no dejar una alarma colgada abierta.

Si ves alarmas repetidas por el mismo hecho, subilo a 3000–5000.

7. Operación diaria¶

Cámara nueva¶

No hay que hacer nada. Dala de alta en Milestone como siempre. En el próximo refresco (5 minutos por defecto) el servicio la detecta, lee su credencial desde Milestone, descubre sus zonas y las mapea. Aparece sola en el panel.

Lo único que queda por hacer a mano es ponerle nombre a las zonas y crear las definiciones de alarma.

Cambio de contraseña de una cámara¶

Cambiala en Milestone. El servicio la relee en el próximo refresco. No hay un segundo lugar donde actualizarla.

Zona nueva en una cámara¶

Se detecta sola y toma el primer slot libre. Va a aparecer en el log:

[INF] 89d3bfd1-...: "Area" 3 -> slot 3

Zona borrada en una cámara¶

El slot no se libera automáticamente. La fila queda marcada como (huérfana) en el panel.

Esto es deliberado: si el slot se reciclara solo, la próxima zona nueva lo tomaría y la alarma que apuntaba a ese slot empezaría a dispararse por otra zona física, sin dar ningún error. Revisá la definición de alarma antes de reutilizar ese slot.

Cámara con más de 5 zonas activas¶

El panel lo marca en rojo:

⚠ Sin slot libre: Area 6, Area 7. Estos eventos NO se envían a Milestone.

Se avisa en vez de perder eventos en silencio. Opciones: subir Mapeo.SlotsPorCamara (y reiniciar, que crea los tipos nuevos), o desactivar en la cámara las zonas que no te interesan.

8. API¶

Por si querés integrarlo con otra cosa o monitorearlo desde afuera.

Método	Ruta	Devuelve
`GET`	`/api/camaras`	Árbol de cámaras con sus zonas y slots
`GET`	`/api/estado`	Salud por cámara
`GET`	`/api/bitacora`	Últimos 300 eventos
`POST`	`/api/zona`	Renombra o habilita una zona
`POST`	`/api/probar`	Envía un evento de prueba

# Salud de todas las cámaras
Invoke-RestMethod http://localhost:8099/api/estado |
    Select-Object -ExpandProperty camaras |
    Format-Table Nombre, Estado, UltimoEvento, ErroresSeguidos

# Renombrar una zona
Invoke-RestMethod http://localhost:8099/api/zona -Method Post -ContentType application/json -Body (@{
    camaraId       = '89d3bfd1-f5c8-4f6d-8805-82a510570cf9'
    espacio        = 'Area'
    indiceEnCamara = 2
    nombre         = 'Portón Norte'
} | ConvertTo-Json)

9. Diagnóstico¶

Logs¶

C:\Program Files\HanwhaZoneBridge\logs\hzb-YYYYMMDD.log, rotativo, 14 días.

Get-Content "C:\Program Files\HanwhaZoneBridge\logs\hzb-$(Get-Date -f yyyyMMdd).log" -Tail 30 -Wait

Arranque sano:

[INF] Now listening on: http://0.0.0.0:8099
[INF] Mapeo cargado: 3 asignaciones
[INF] Analytics Event Types: 0 creados, 20 ya existian, 0 con error
[INF] Inventario: 1 camaras Hanwha con credencial
[INF] CAM-01 en linea, 3 zonas

Confirmar que las alarmas llegan¶

sqlcmd -S localhost -E -d Surveillance -Q @"
SELECT TOP 10 Timestamp, Name, Message
FROM Central.Alarms
WHERE VendorName = 'HanwhaZoneBridge'
ORDER BY Timestamp DESC
"@

La tabla está en el esquema Central, no en dbo. SELECT ... FROM Alarms a secas falla con Invalid object name.

Probar sin esperar a que alguien camine¶

Botón probar de cada zona en el panel, o:

Invoke-RestMethod http://localhost:8099/api/probar -Method Post -ContentType application/json -Body (@{
    camaraId = '89d3bfd1-f5c8-4f6d-8805-82a510570cf9'
    tipo     = 'Hanwha Intrusion_2'
} | ConvertTo-Json)

aceptado
---------
    True

10. Límites conocidos¶

Sólo intrusión y cruce de línea. La cámara también expone Entering, Exiting, Loitering y Appearing, y el servicio los lee, pero no los emite. Sumarlos es agregar tipos: el motor ya los tiene.
5 zonas y 5 líneas por cámara. Configurable, pero subirlo agranda la lista de tipos en el Management Client.
Sólo cámaras Hanwha con SUNAPI y SchemaBased. Firmware viejo sin soporte de SchemaBased=True no puede discriminar zona; el servicio lo detecta al conectar.
Un canal por cámara. Probado con cámaras de un solo canal. Encoders multicanal deberían funcionar por el filtro de Channel, pero no está verificado en campo.