Viewtron Python SDK

Python SDK for Viewtron IP camera API. Parse inbound alarm events and control cameras programmatically.

Viewtron IP cameras run AI detection on-camera (license plate recognition, face detection, human/vehicle detection) and send HTTP POST events to your server. This SDK parses those events and provides an API client for camera control.

Version 1.4.0 adds API 2.1 support for the Viewtron LPR-IP4 license plate recognition camera (firmware 5.3.x): plate direction (approach / away), confidence, allow / block / temporary plate lists by name, vehicle color, type, brand and model, capability discovery, and an on_unparsed hook for posts the SDK does not recognize.

Install

pip install viewtron

Inbound Events — Parse Camera Alarm Data

Viewtron cameras and NVRs send XML alarm events via HTTP POST. This SDK parses them into Python objects.

from viewtron import ViewtronServer

def on_event(event, client_ip):
    if event.category == "lpr":
        print(event.get_plate_number())       # "IB36NL"
        print(event.get_plate_group())        # "whiteList" or NVR group name
        print(event.direction)                # "approach", "away", or None
        print(event.confidence)               # 0-100, e.g. 99.0
        print(event.plate_list)               # "whiteList" or None
        print(event.vehicle_color, event.vehicle_brand, event.vehicle_type)

        # Images as decoded JPEG bytes — ready for saving, MQTT, notifications
        overview = event.get_source_image_bytes()   # full scene
        plate_crop = event.get_target_image_bytes() # plate closeup

def on_unparsed(xml, client_ip, reason):
    # reason is unknown-smartType, no-messageType, parse-error, or alarmStatus
    print(reason, client_ip)

server = ViewtronServer(port=5050, on_event=on_event, on_unparsed=on_unparsed)
server.serve_forever()

Every parsed event has config_version (the post's config version, such as "1.7" or "2.1.0") and format ("v1" or "v2"). A version-2 post that uses an IPC smartType and has no messageType is parsed with the IPC classes. smartType matching ignores case when that is unambiguous. VEHICLE in a version-2 envelope is a plate event only when licensePlateListInfo is present; otherwise on_unparsed is called with unknown-smartType.

on_raw is unchanged. The server reads Transfer-Encoding: chunked bodies and does not treat them as keepalives.

On an LPR event, direction is "approach", "away", or None. A post that says leave is "away". confidence is a float from 0 to 100 (PlateConfidence count="9900" is 99.0) or None. plate_list is whiteList, blackList, temporaryList, strangerList, or None. vehicle_color, vehicle_brand, vehicle_type, and vehicle_model come from the plate item's vehicle attributes when the post includes them. get_plate_group() still returns the raw group text, including a custom NVR group name. get_time_stamp_formatted() is the camera's event time. currentTime may be seconds, milliseconds, or microseconds.

examples/gate_direction_filter.py acts only on approaching allow-list plates at 90% confidence or higher.

Every LPR field is documented in the license plate recognition camera API docs. For a real driveway or HOA gate setup, see our ALPR gate access control walkthrough.

Supported Event Types

Version detection is automatic. IPC v1.x and version-2 posts (2.0, 2.1, and later 2.x versions with the same layout) use different XML structures; the SDK handles both. Check event.format and event.config_version when you need to tell them apart.

Outbound API — Control the Camera

Viewtron cameras ship set to DHCP, so the camera gets its address from your router. Find it with our IP camera finder tool and use it in place of the example address below.

from viewtron import ViewtronCamera

camera = ViewtronCamera("192.168.0.20", "admin", "password")

# Device info
info = camera.get_device_info()
print(info["model"])  # "LPR-IP4"

# What this firmware supports
caps = camera.capabilities
print(caps.api_version, caps.http_post_version, caps.config_version)
print(caps.supported_apis)  # frozenset, or None when GetSupportedAPIs is unavailable

# Plate groups. On current firmware (a camera running 5.3.1, API 2.1.0)
# group 1 is temporaryList and the allow list is whiteList, typically group 2.
print(camera.get_plate_groups())  # {1: "temporaryList", 2: "whiteList", 3: "blackList"}

# Manage the license plate database. Pass group= so the id is resolved for you.
# Omitting it still uses group id "1" and warns once; that default changes in a future major release.
plates = camera.get_plates(group="whiteList")
camera.add_plate("IB36NL", group="allow")  # allow, block, and temporary also resolve
camera.modify_plate("IB36NL", owner="Mike", telephone="555-1234", group="whiteList")
camera.delete_plate("IB36NL", group="whiteList")
all_plates = camera.get_all_plates()  # every group, paged with resultOffset / maxResult / total

# Temporary visitor pass. Omitting begin_time and end_time lets the camera
# assign the validity window. Pass both when the pass should last N days.
from datetime import datetime, timedelta
start = datetime.now().replace(microsecond=0)
camera.add_plate(
    "IB36NL",
    group="temporary",
    owner="Visitor",
    card_number="1001",
    begin_time=start,
    end_time=start + timedelta(days=7),
)
this_week = camera.get_expiring_plates(days=7)

# Or use as context manager
with ViewtronCamera("192.168.0.20", "admin", "password") as cam:
    plates = cam.get_plates(group="whiteList")

Projects Using This SDK

• Viewtron Home Assistant Integration — Camera events as HA sensors via MQTT auto-discovery
• Viewtron Node.js SDK — The same camera events for Node.js (npm install viewtron-sdk)
• Node-RED Viewtron node — License plate, intrusion, face and counting events in Node-RED flows
• IP Camera API Server — Alarm server with CSV logging and image saving

Documentation

• API Developer Docs — Full Viewtron API documentation portal
• Python SDK Reference — Event classes, camera client, version routing
• Home Assistant Integration — Connect cameras to HA via MQTT
• XML Event Examples
• examples/visitor_pass.py — add a temporary pass and list plates expiring this week
• examples/gate_direction_filter.py — approaching allow-list plates at 90% confidence or higher
• IP Camera Setup Guide
• NVR Setup Guide
• LPR camera API guide — plate webhooks, this SDK and Home Assistant, step by step
• Home Assistant license plate recognition — forum walkthrough with automations
• Viewtron LPR camera API / HTTP Post questions — answers to common integration questions

Products

• Viewtron security cameras and surveillance systems
• Viewtron license plate recognition systems
• Viewtron IP cameras and IP camera NVRs
• AI security cameras

Author

Mike Haldas — CCTV Camera Pros mike@cctvcamerapros.net