Skip to main content

Relay Control & IoT Automation API

Viewtron IP cameras and NVRs include hardware alarm relay outputs that can be triggered via HTTP API calls. This enables IoT automation workflows where AI detection events from the camera drive physical actions in the real world — opening gates, activating lights, triggering external alarm panels, or controlling any device connected to the relay output. All processing runs on local hardware with no cloud dependency.

The API provides two relay control mechanisms: ManualAlarmOut for directly triggering a physical relay output on the camera or NVR, and TriggerVirtualAlarm (NVR v2.0 only) for triggering virtual alarm inputs that can activate NVR recording, push notifications, and relay outputs on specific channels. Both endpoints accept standard HTTP requests with Basic authentication. All Viewtron IP cameras and NVRs are NDAA compliant.

A working real-world example of this API is the ESP8266 relay controller project on GitHub, which uses Viewtron camera traject data for continuous human detection to control an ESP8266-based relay module.

What You Can Build​

  • Gate access control — combine with license plate recognition to open gates for authorized vehicles
  • Lighting automation — activate lights when a person is detected at night, deactivate after a timeout
  • Alarm panel integration — trigger wired alarm panel zones from camera AI detection events
  • Home automation — connect camera events to smart home relays for HVAC, locks, or irrigation
  • Industrial automation — trigger conveyor belts, safety shutoffs, or indicators based on human/vehicle detection
  • ESP8266/Arduino control — use microcontrollers as intermediary relay controllers driven by camera webhook events

How It Works​

  1. Camera detects an event — human detection, LPR, line crossing, or other AI detection triggers a webhook POST to your server
  2. Your server processes the event — verify target type, check authorization lists, evaluate time-based rules
  3. Send relay command — call ManualAlarmOut on the camera/NVR to trigger the physical relay output
  4. Or trigger a virtual alarm — call TriggerVirtualAlarm on the NVR to activate recording and notifications on a specific channel
  5. Reset after timeout — send a follow-up API call to release the relay after the desired duration

Relay Control Endpoints​

ManualAlarmOut​

Directly triggers or releases a physical alarm relay output.

FieldValue
URLPOST http://<host>[:port]/ManualAlarmOut[/channelId]
ProductsIPC, NVR
AuthHTTP Basic (admin credentials)

Trigger relay (activate):

<?xml version="1.0" encoding="UTF-8"?>
<config version="1.0" xmlns="http://www.ipc.com/ver10">
  <action>
    <status>true</status>
  </action>
</config>

Release relay (deactivate):

<?xml version="1.0" encoding="UTF-8"?>
<config version="1.0" xmlns="http://www.ipc.com/ver10">
  <action>
    <status>false</status>
  </action>
</config>
Known Firmware Bug

On IPC cameras, the firmware forcibly resets the alarm output when a perimeter alarm cycle ends, even when alarm output mode is set to manual_alarm and triggerAlarmOut is unchecked. This makes ManualAlarmOut unreliable for automation while perimeter detection is active on the same camera. NVR alarm outputs are not affected by this bug.

TriggerVirtualAlarm (NVR v2.0 Only)​

Triggers a virtual alarm input on the NVR, which can activate recording, push notifications, and relay outputs on specific channels.

FieldValue
URLGET http://<host>[:port]/TriggerVirtualAlarm/{virtualAlarmId}
ProductsNVR only
AuthHTTP Basic (admin credentials)

Virtual alarm ID calculation: IDs start after physical alarm inputs. If the NVR has 16 physical alarms, virtual alarm 1 = ID 17, virtual alarm 2 = ID 18, etc. Use GetAlarmInInfo to see the full list.

curl -u admin:password "http://192.168.0.147/TriggerVirtualAlarm/17"

Parsing Detection Events and Triggering Relays​

The simplest way to receive detection events and trigger relays. The SDK's ViewtronServer handles incoming webhooks while ViewtronCamera sends outbound relay commands:

pip install viewtron
from viewtron import ViewtronServer, ViewtronCamera
import os
import threading

IMG_DIR = "images"
os.makedirs(IMG_DIR, exist_ok=True)

# NVR credentials for relay control
nvr = ViewtronCamera("192.168.0.147", "admin", "password")
RELAY_DURATION = 15

def on_event(event, client_ip):
    if event.category != "intrusion":
        return
    print(f"Person detected from {client_ip} — triggering relay")
    print(f"  Type: {event.get_alarm_description()}")

    overview = event.get_source_image_bytes()
    if overview:
        with open(f"{IMG_DIR}/{event.get_time_stamp()}-relay-overview.jpg", "wb") as f:
            f.write(overview)

    # Trigger relay on NVR
    nvr.set_alarm_out(True)
    threading.Timer(RELAY_DURATION, lambda: nvr.set_alarm_out(False)).start()

server = ViewtronServer(port=5002, on_event=on_event)
server.serve_forever()

See the Python SDK reference for the full list of methods and event classes.

ESP8266 Relay Controller Project​

A complete real-world example using an ESP8266 microcontroller as a relay controller is available in the IP-Camera-API GitHub repository. This project uses Viewtron camera httpPostV2 traject data for continuous human detection to keep a relay active as long as a person is present in the camera's field of view. When the person leaves and traject data stops, the relay deactivates after a configurable timeout.

This approach solves the limitation of perimeterAlarm — which drops to false during the 5-20 second gaps between alarm cycles even if the person is still present — by using continuous traject position data instead.

Relevant API Endpoints​

EndpointPurposeReference
ManualAlarmOutTrigger or release alarm relay outputAlarm Input/Output Config
GetAlarmOutConfigRead alarm output relay configurationAlarm Input/Output Config
TriggerVirtualAlarmTrigger virtual alarm on NVR (v2.0)Virtual Alarm
GetAlarmStatusPoll current alarm stateAlarm Status
SetHttpPostConfigConfigure webhook destination for detection eventsWebhook Config

Integrations​

Viewtron relay control also integrates with automation platforms via published packages:

PlatformPackageWhat It Does
Home Assistantviewtron-home-assistantDetection events as native HA sensors — trigger relays via HA automations
Node-REDnode-red-contrib-viewtronDetection events direct to Node-RED flows — build relay logic visually

Questions & Development Inquiries​

Mike Haldas is available for questions, consultation, and custom software development for Viewtron API related projects. Email details about your project to mike@viewtron.com.