Guía de instalación — Hanwha Zone Bridge¶

Instalación desde cero sobre un servidor Milestone XProtect limpio.

Todos los ejemplos de esta guía son salidas reales del servidor de laboratorio SRV-MILESTONE (XProtect VMS 2026 R1, Windows Server 2022).

1. Qué hace y por qué existe¶

Las cámaras Hanwha reportan a Milestone un evento plano: "hubo intrusión en CAM-01". No dicen en qué zona. Esto lo confirma la configuración del propio driver, que tiene exactamente tres eventos cableados:

Binding	Evento
`event:15\\|0`	`IntrusionStart`
`event:8\\|1`	`Tripwire`
`event:4\\|2`	`Tampering`

El motivo es estructural: los 203 tipos de evento de driver de Milestone declaran <Parameters/> vacío. La zona no tiene dónde viajar.

Hanwha sí expone la zona por SUNAPI. Este servicio la lee y la inyecta en Milestone como Analytics Events con el índice de zona en el nombre del tipo, de forma que se puedan armar reglas y alarmas distintas por zona.

Detalle completo en Por qué el driver no trae zona.

2. Requisitos¶

En el servidor de Milestone¶

Requisito	Por qué	Verificación
Windows Server 2016+	.NET Framework 4.7.2 de fábrica	automática
XProtect Management Server corriendo	inventario y credenciales	automática
XProtect Event Server corriendo	recibe los eventos	automática
Analytics Events habilitado	es el canal de inyección	automática
Puerto libre para el panel	por defecto 8099	automática
Red hacia las cámaras	SUNAPI por HTTP	manual

El instalador verifica todo lo marcado como automático y se detiene con un mensaje claro si algo falta.

No hace falta instalar el runtime de .NET. El paquete es autocontenido. Lo único que usa del sistema es .NET Framework 4.7.2, que viene con Windows Server 2016 y posteriores, y que necesita el sidecar porque el MIP SDK de Milestone sólo publica assemblies net472.

Habilitar Analytics Events¶

En Management Client → Herramientas → Opciones → Eventos analíticos:

☑ Habilitado
Puerto: 9090
Seguridad → Eventos permitidos de: Todas las direcciones de red (o agregá la IP del servidor si preferís restringir)

Permisos de la cuenta de servicio¶

El servicio corre por defecto como NT AUTHORITY\NetworkService, que en una instalación típica de XProtect ya es miembro del rol Administrators del VMS. Se puede confirmar en Management Client → Seguridad → Roles → Administrators.

Necesita ese rol porque lee las contraseñas de las cámaras desde la configuración de Milestone — que es lo que evita tener que cargarlas a mano en 100+ equipos. Ver Credenciales del VMS.

Si en tu sistema NetworkService no está en el rol, tenés dos opciones:

# a) agregarla al rol (Management Client > Seguridad > Roles > Administrators)

# b) instalar con otra cuenta
.\Install-HanwhaZoneBridge.ps1 `
    -CuentaDeServicio 'DOMINIO\svc-hzb' `
    -PasswordDeServicio (Read-Host -AsSecureString "Password")

3. Armado del paquete¶

Sólo hace falta en la máquina que compila. Requiere el SDK de .NET 8; el servidor destino no.

cd desarrollo\installer
.\Build-Paquete.ps1 -Version 1.0.0

==> Publicando el servicio (.NET 8, autocontenido win-x64)
==> Publicando el sidecar MipHelper (net472)
==> Sumando scripts y documentacion
==> Comprimiendo

  Paquete listo: ...\dist\HanwhaZoneBridge-1.0.0.zip  (153 MB)

Los 153 MB son casi todos el runtime de .NET embebido. Es el precio de no depender de nada en el servidor destino.

Si el servidor no tiene fuentes NuGet configuradas¶

En un Windows Server recién instalado, dotnet puede venir sin ninguna fuente y la compilación falla con NU1100: Unable to resolve para todos los paquetes, incluso los más comunes. No es un problema de red ni de framework:

dotnet nuget list source        # "No sources found."
dotnet nuget add source "https://api.nuget.org/v3/index.json" -n nuget.org

4. Instalación¶

Copiá el zip al servidor de Milestone, descomprimilo y ejecutá como Administrador:

Expand-Archive HanwhaZoneBridge-1.0.0.zip -DestinationPath C:\temp\hzb
cd C:\temp\hzb
.\Install-HanwhaZoneBridge.ps1

Salida real de una instalación limpia:

  Hanwha Zone Bridge
  Discriminacion de zonas de analiticas Hanwha hacia Milestone XProtect

==> Verificando requisitos
    OK   Ejecutando como Administrador
    OK   .NET Framework OK (release 528449)
    OK   Paquete completo

==> Verificando Milestone XProtect
    OK   Management Server corriendo
    OK   Event Server corriendo
    OK   Analytics Events escuchando en 9090

==> Verificando el puerto 8099 para el panel
    OK   Puerto 8099 disponible

==> Instalando en C:\Program Files\HanwhaZoneBridge
    OK   Archivos copiados

==> Configurando
    OK   appsettings.json actualizado
    OK   Permisos otorgados a NT AUTHORITY\NetworkService

==> Creando el servicio de Windows
    OK   Servicio creado con cuenta NT AUTHORITY\NetworkService

==> Abriendo el puerto del panel
    OK   Regla de firewall creada para el puerto 8099

==> Arrancando el servicio
    OK   Servicio corriendo
    ... esperando el primer inventario
    OK   1 camaras Hanwha detectadas
    OK   Analytics Event Types listos (0 creados, 20 existentes)

   Instalacion completa

   Panel      http://192.0.2.200:8099
   Carpeta    C:\Program Files\HanwhaZoneBridge
   Logs       C:\Program Files\HanwhaZoneBridge\logs\
   Servicio   HanwhaZoneBridge  (NT AUTHORITY\NetworkService)

Opciones¶

Parámetro	Por defecto	Para qué
`-Puerto`	`8099`	Puerto del panel web
`-RutaDeInstalacion`	`C:\Program Files\HanwhaZoneBridge`	Carpeta destino
`-CuentaDeServicio`	`NT AUTHORITY\NetworkService`	Identidad del servicio
`-PasswordDeServicio`	—	SecureString, si la cuenta lo requiere
`-UriDelVms`	`http://localhost`	Si el Management Server está en otro host
`-PuertoEventServer`	`9090`	Si cambiaste el puerto de Analytics Events
`-SinFirewall`	—	No crear la regla de firewall
`-Forzar`	—	Continuar aunque Analytics Events no escuche

No uses el puerto 8080. En un servidor XProtect típico está reservado por http.sys para el Mobile Server, y aunque netstat no muestre nada escuchando, bindear ahí falla con SocketException 10013. El instalador lo detecta y aborta antes de dejar una instalación rota.

5. Qué deja instalado¶

C:\Program Files\HanwhaZoneBridge\
├── HanwhaZoneBridge.exe        servicio principal (.NET 8, autocontenido)
├── appsettings.json            configuración
├── mapeo-slots.json            mapeo zona→slot (se crea solo)
├── wwwroot\                    panel web
├── logs\                       hzb-YYYYMMDD.log, rotativo, 14 días
└── MipHelper\
    └── MipHelper.exe           sidecar net472 para el MIP SDK

Además:

Servicio de Windows HanwhaZoneBridge, arranque automático, con reinicio ante caídas a los 10 s, 30 s y 60 s.
Regla de firewall Hanwha Zone Bridge - Panel para el puerto elegido.
Hasta 20 Analytics Event Types en Milestone (Hanwha Intrusion_1..5, Hanwha Line Crossing_1..5 y sus variantes End).

⚠ mapeo-slots.json es el archivo que no hay que perder¶

Guarda qué zona física de cada cámara corresponde a cada slot lógico. Si se borra, los slots se reasignan y las definiciones de alarma ya armadas en Milestone pasan a apuntar a otra zona, sin dar ningún error.

El instalador lo respalda y lo restaura automáticamente al actualizar, y el desinstalador lo conserva salvo que pases -BorrarTodo. Igual: incluilo en tus backups.

6. Verificación¶

Get-Service HanwhaZoneBridge

Status  Name             StartType
------  ----             ---------
Running HanwhaZoneBridge Automatic

Invoke-RestMethod http://localhost:8099/api/camaras | ForEach-Object {
    "$($_.nombre) [$($_.estado)]"
    $_.zonas | ForEach-Object { "  slot $($_.slot) <- $($_.espacio) $($_.indiceEnCamara)  $($_.tipoDeEvento)" }
}

CAM-01 [EnLinea]
  slot 1 <- Area 1   Hanwha Intrusion_1
  slot 2 <- Area 2   Hanwha Intrusion_2
  slot 1 <- Linea 1  Hanwha Line Crossing_1

Invoke-RestMethod http://localhost:8099/api/bitacora | Select-Object -First 6

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]
06:08:11   fin    CAM-01  Hanwha Intrusion_2 End  [CAM-01 / Zona 2]

Y en el panel, http://<servidor>:8099:

Panel de la integración

7. Problemas frecuentes¶

`VMO61008: You do not have sufficient permissions`¶

La cuenta del servicio no es administradora del VMS. Agregá NT AUTHORITY\NETWORK SERVICE al rol Administrators en Management Client, o reinstalá con -CuentaDeServicio.

Correr como LocalSystem no alcanza: el VMS lo ve como la cuenta de máquina y la rechaza.

`0 camaras Hanwha detectadas`¶

¿Hay hardware Hanwha habilitado en el Recording Server?
El filtro de marca busca hanwha, wisenet o samsung en el modelo o el nombre del hardware. Si tus cámaras se llaman distinto, ajustá MipHelper.PatronesDeModelo en appsettings.json.
Si el log dice "sin credencial legible", la cuenta de servicio no tiene permiso para leer contraseñas de hardware.

El servicio arranca y se cae¶

Mirá logs\hzb-*.log. La causa más común es el puerto del panel ocupado o reservado por http.sys.

Los eventos salen pero no aparecen en Milestone¶

En la bitácora del panel van a figurar como << RECHAZADO. Las dos causas:

Respuesta del Event Server	Significado
`Warning: Event message not known`	El Analytics Event Type no existe. Reiniciá el servicio para que los vuelva a crear.
`Warning: Device not known`	La cámara ya no existe en Milestone, o cambió de ID.

La cámara aparece `Fallida`¶

Probá la conectividad desde el servidor:

Test-NetConnection 192.0.2.10 -Port 80

No uses curl.exe para probar la cámara. El curl 7.79.1 que trae Windows Server 2022 no completa el handshake Digest contra estas cámaras: recibe el 401, reutiliza la conexión y nunca manda la segunda request, terminando en exit=67 con salida vacía. Parece un problema de credenciales y no lo es. Usá PowerShell:
Add-Type -AssemblyName System.Net.Http
$cc = New-Object System.Net.CredentialCache
$cc.Add([Uri]"http://192.0.2.10/", "Digest",
        (New-Object System.Net.NetworkCredential("admin","LA_CLAVE")))
$h = New-Object System.Net.Http.HttpClientHandler; $h.Credentials = $cc
$c = New-Object System.Net.Http.HttpClient($h)
$c.GetStringAsync("http://192.0.2.10/stw-cgi/system.cgi?msubmenu=deviceinfo&action=view").Result

8. Actualización¶

Ejecutá el instalador de la versión nueva. Detecta la instalación anterior, respalda mapeo-slots.json, actualiza los binarios y lo restaura.

.\Install-HanwhaZoneBridge.ps1

    !    El servicio ya existe: se detiene y se actualiza
    OK   Mapeo de slots existente respaldado
    ...
    OK   Mapeo de slots restaurado

9. Desinstalación¶

.\Uninstall-HanwhaZoneBridge.ps1

Saca el servicio, la regla de firewall y los archivos, conservando mapeo-slots.json.

Parámetro	Efecto
`-BorrarTodo`	Borra también el mapeo de slots
`-LimpiarMilestone`	Borra los Analytics Event Types y las alarmas `Hanwha *`

Por defecto no toca la configuración en Milestone, porque las reglas que armaste a mano pueden depender de ella.