Skip to main content

Viewtron Python SDK

The Viewtron Python SDK (pip install viewtron) is the recommended way to work with the Viewtron IP Camera API. It handles two things:

  1. Inbound events — parse XML alarm events from cameras into Python objects (LPR, face detection, intrusion, counting)
  2. Outbound API — control cameras and manage plate databases programmatically

The SDK handles all XML formatting, API version differences (IPC v1.x vs NVR v2.0), and authentication automatically.

Install​

pip install viewtron

Requires Python 3.7+. Dependencies: requests, xmltodict.

Source code: github.com/mikehaldas/viewtron-python-sdk

Inbound Events — Parse Camera Alarm Data​

Viewtron cameras send AI detection events as HTTP POST requests with XML payloads. The SDK parses these into Python objects with typed accessors for every field.

Quick Example​

from viewtron import LPR, VehicleLPR

# In your HTTP POST handler, pass the raw request body:
event = LPR(request_body)

print(event.get_plate_number())       # "ABC1234"
print(event.is_plate_authorized())    # True
print(event.get_vehicle_list_type())  # "whiteList"

# Images are included as base64 JPEG
if event.source_image_exists():
    overview = event.get_source_image()    # full scene image
if event.target_image_exists():
    plate_crop = event.get_target_image()  # plate closeup

Event Classes​

The SDK provides separate classes for each detection type and API version. Version detection is automatic — IPC v1.x and NVR v2.0 use different XML structures, but the classes share common methods.

IPC v1.x (Direct from Camera)​

ClasssmartTypeDetectionApplication Guide
LPRVEHICELicense plate recognition with whitelist/blacklistLPR
FaceDetectionFACEFace detection with crop imageFace Detection
IntrusionDetectionPEAPerimeter intrusion (person/vehicle/motorcycle)Human Detection
IntrusionEntryAVDZone entry detectionPerimeter Security
IntrusionExitAVDZone exit detectionPerimeter Security
LoiteringDetectionLOITERINGLoitering in a zoneLoitering
IllegalParkingPVDParking violationVehicle/Parking
VideoMetadataVIDEO_METADATAContinuous object detectionReal-Time Tracking

NVR v2.0 (Forwarded via NVR)​

ClasssmartTypeDetectionApplication Guide
VehicleLPRvehicleLPR with vehicle brand, color, type, modelLPR
FaceDetectionV2faceDetectionFace detection with age, sex, glasses, maskFace Detection
RegionIntrusionregionIntrusionPerimeter intrusionHuman Detection
LineCrossinglineCrossingTripwire line crossingPerimeter Security
TargetCountingByLinetargetCountingByLinePeople/vehicle counting by linePeople Counting
TargetCountingByAreatargetCountingByAreaPeople/vehicle counting by areaPeople Counting
VideoMetadataV2videoMetadataContinuous object detectionReal-Time Tracking

Common Methods​

All event classes share these methods:

MethodReturnsDescription
get_ip_cam()strCamera IP address or device name
get_alarm_type()strDetection type identifier (e.g., PEA, VEHICE)
get_alarm_description()strHuman-readable description
get_time_stamp()strRaw timestamp from event
get_time_stamp_formatted()strFormatted date/time string
source_image_exists()boolWhether a full-frame image is included
get_source_image()strBase64 JPEG of the full scene
target_image_exists()boolWhether a target crop image is included
get_target_image()strBase64 JPEG of the detected target

Version Routing​

Your HTTP server receives events from both IPC and NVR sources. Route to the correct class based on the XML version:

import xmltodict
from viewtron import (
    LPR, VehicleLPR,
    IntrusionDetection, RegionIntrusion,
    FaceDetection, FaceDetectionV2,
)

def handle_post(body):
    data = xmltodict.parse(body)
    config = data.get('config', {})
    version = config.get('@version', '')

    if version.startswith('2'):
        # NVR v2.0 format
        smart_type = str(config.get('smartType', ''))
        if smart_type == 'vehicle':
            event = VehicleLPR(body)
        elif smart_type == 'regionIntrusion':
            event = RegionIntrusion(body)
        elif smart_type == 'faceDetection':
            event = FaceDetectionV2(body)
    else:
        # IPC v1.x format
        st = config.get('smartType', {})
        alarm = (st.get('#text') or str(st)).strip() if isinstance(st, dict) else str(st).strip()
        if alarm == 'VEHICE':
            event = LPR(body)
        elif alarm == 'PEA':
            event = IntrusionDetection(body)
        elif alarm == 'FACE':
            event = FaceDetection(body)

See each application guide for complete working examples with image saving and CSV logging.

Outbound API — Control the Camera​

The ViewtronCamera class sends commands to cameras using Basic HTTP authentication.

Quick Example​

from viewtron import ViewtronCamera

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

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

# Manage the license plate database
camera.add_plate("ABC1234")
plates = camera.get_plates()
camera.modify_plate("ABC1234", owner="Mike H.", telephone="555-1234")
camera.delete_plate("ABC1234")

Or use as a context manager:

with ViewtronCamera("192.168.0.20", "admin", "password") as cam:
    plates = cam.get_plates()
    for plate in plates:
        print(plate)

Camera Client Methods​

MethodDescription
get_device_info()Get camera model, firmware version, device name
add_plate(plate_number, group_id="1")Add a plate to the camera database
add_plates(plate_numbers, group_id="1")Add multiple plates in one request
get_plates(max_results=50, offset=1, group_id="1")Query plates with pagination (offset is 1-based)
modify_plate(plate_number, group_id="1", owner=None, telephone=None)Update plate details
delete_plate(plate_number, group_id="1")Remove a plate from the database

See the LPR Config API reference for the underlying XML endpoints.

Projects Built with This SDK​

ProjectDescription
Viewtron Home Assistant IntegrationCamera AI events as native HA sensors via MQTT auto-discovery
IP Camera API ServerAlarm server with CSV logging and image saving
ESP8266 Relay ControllerIoT relay triggered by camera detection events

Supported Cameras​

The SDK works with any Viewtron AI security camera or NVR that supports HTTP POST webhooks. For license plate recognition, use the Viewtron LPR cameras. All Viewtron products are NDAA compliant.

Video Guides​

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.