milestonexprotectwsPython 1.0.2

Milestone XProtect Web Services Python3 Library

Milestone XProtect Web Services Python3 Library

Overview

This API provides Python programmers the ability to retrieve various configuration information for Milestone Systems XProtect Video Manegement Systems (VMS) products. It utilizes the Milestone Systems XProtect VMS Web-Services to retrieve the information. More information on Milestone XProtect products can be found on the Milestone XProtect Products page.

What this API CAN Do

This API provides an easy way to retrieve XProtect configuration details: Hardware Devices (e.g. Cameras, Microphones, Speakers, etc), Recording Server information, Product License Information, Site information, etc. It also allows you to retrieve JPEG image data from live camera and archived footage. Check out the milestonexprotectwspython.xpwservercommandservice.XPWServerCommandService, milestonexprotectwspython.xpwrecordercommandservice.XPWRecorderCommandService, and milestonexprotectwspython.xpwserviceregistrationservice.XPWServiceRegistrationService class help documentation for more details.

What this API CANNOT Do (yet anyway)

This API does not provide any functionality to ADD, UPDATE, or DELETE XProtect configurations.

Requirements and Dependencies

The following XProtect requirements must be met in order to utilize this API:

• Milestone Systems XProtect Management Server 2023 R2, Version 23.2a+.

  The XProtect Management Server provides web-services for various commands and configuration. The XProtect software products can be downloaded from the: Milestone XProtect Products download page.

The following Python-related requirements must be met in order to utilize this API:

• Python 3.4 or greater (not tested with Python 2).

• smartinspectPython package (>= 3.0.20) - for diagnostics and logging support.

• requests package (>= 2.0).

• requests-ntlm package (>= 1.2.0).

Documentation

Documentation is located in the package library under the 'docs' folder; use the index.html as your starting point.

Quick-Start Sample Code

The following code snippets will get you started with establishing a connection to the XProtect web-services and retrieving information.

Check out the milestonexprotectwspython.xpwservercommandservice.XPWServerCommandService, milestonexprotectwspython.xpwrecordercommandservice.XPWRecorderCommandService, and milestonexprotectwspython.xpwserviceregistrationservice.XPWServiceRegistrationService class methods for more sample code.

Get Management Server Configuration

# package imports.
from milestonexprotectwspython.xpwconfiguration import XPWConfiguration
from milestonexprotectwspython.xpwlogininfo import XPWLoginInfo
from milestonexprotectwspython.xpwservercommandservice import XPWServerCommandService

# create service instance and set server prefixes for our environment.
svc:XPWServerCommandService = XPWServerCommandService()
svc.ManagementServerUrlPrefix = "https://mymanagementserver.example.com"
svc.IsSslVerifyEnabled = False

# authenticate using xprotect basic auth credentials.
loginInfo:XPWLoginInfo = svc.LoginBasicUser("xpsampleadmin", "MyPassword&1")
print("** Login Details:\n{0}\n".format(loginInfo))

# get configuration info.
cfg:XPWConfiguration = svc.GetConfiguration()
print("** Configuration Info:\n{0}\n".format(cfg))
print("**   Camera Groups:\n{0}\n".format(cfg.CameraGroups))
print("**   Input Groups:\n{0}\n".format(cfg.InputGroups))
print("**   Output Groups:\n{0}\n".format(cfg.OutputGroups))
print("**   Recorders:\n{0}\n".format(cfg.Recorders))
print("**   Speaker Groups:\n{0}\n".format(cfg.SpeakerGroups))
print("**   Licenses:\n{0}\n".format(cfg.Licenses))

Retrieve Live Camera JPEG Image and Save to a File

# package imports.
from milestonexprotectwspython.xpwjpegdata import XPWJpegData
from milestonexprotectwspython.xpwlogininfo import XPWLoginInfo
from milestonexprotectwspython.xpwrecordercommandservice import XPWRecorderCommandService

# create service instance and set server prefixes for our environment.
svc:XPWRecorderCommandService = XPWRecorderCommandService()
svc.ManagementServerUrlPrefix = "https://mymanagementserver.example.com"
svc.RecordingServerUrlPrefix =  "http://myrecordingserver.example.com:7563"
svc.IsSslVerifyEnabled = False

# authenticate using xprotect windows auth credentials.
loginInfo:XPWLoginInfo = svc.LoginWindowsUser("MYDOMAIN\XProtectSample", "MyPassword&1")
print("** Login Details:\n{0}\n".format(loginInfo))

# get live jpeg image in 1280 x 720 resolution.
item:XPWJpegData = svc.JPEGGetLive("71cab37e-8718-4383-8e86-146b38168e42", 1280, 720, "My Camera (1280x720)")
print("** JPEGGetLive Item Summary:\n{0}\n".format(item))

# save jpeg image to file.
if (item.HasData):
    item.SaveToFile("./tests/logfiles/TestCase_JPEGGetLive_{title}_{time}.jpg")
    print("** JPEGGetLive Item Saved:\n{0}\n".format(item.SaveToFilePath))

# get live jpeg image in 100 x 100 resolution.
item:XPWJpegData = svc.JPEGGetLive("71cab37e-8718-4383-8e86-146b38168e42", 100, 100, "My Camera (100x100)")
print("** JPEGGetLive Item Summary:\n{0}\n".format(item))

# save jpeg image to file.
if (item.HasData):
    item.SaveToFile("./tests/logfiles/TestCase_JPEGGetLive_{title}_{time}.jpg")
    print("** JPEGGetLive Item Saved:\n{0}\n".format(item.SaveToFilePath))

Get List of Available Services

# package imports.
from milestonexprotectwspython.xpwcollection import XPWCollection
from milestonexprotectwspython.xpwlogininfo import XPWLoginInfo
from milestonexprotectwspython.xpwservice import XPWService
from milestonexprotectwspython.xpwserviceregistrationservice import XPWServiceRegistrationService

# create service instance and set server prefixes for our environment.
svc:XPWServiceRegistrationService = XPWServiceRegistrationService()
svc.ManagementServerUrlPrefix = "https://mymanagementserver.example.com"
svc.IsSslVerifyEnabled = False

# authenticate using xprotect basic auth credentials.
loginInfo:XPWLoginInfo = svc.LoginBasicUser("xpsampleadmin", "MyPassword&1")
print("** Login Details:\n{0}\n".format(loginInfo))

# get services info.
items:XPWCollection = svc.GetServices()
print("** Services Summary:\n{0}\n".format(items))

Licensing

This project is licensed under the terms of the MIT End-User License Agreement (EULA) license.

Logging / Tracing Support

The SmartInspectPython package (installed with this package) can be used to easily debug your applications that utilize this API.

The following topics and code samples will get you started on how to enable logging support.
Note that logging support can be turned on and off without changing code or restarting the application.
Click on the topics below to expand the section and reveal more information.

Configure Logging Support Settings File

Add the following lines to a new file (e.g. "smartinspect.cfg") in your application startup / test directory. Note the file name can be whatever you like, just specify it on the call to `SiAuto.Si.LoadConfiguration()` when initializing the logger.

; smartinspect.cfg

; SmartInspect Logging Configuration General settings.
; - "Enabled" parameter to turn logging on (True) or off (False).
; - "Level" parameter to control the logging level (Debug|Verbose|Message|Warning|Error).
; - "AppName" parameter to control the application name.
Enabled = False 
Level = Verbose
DefaultLevel = Debug
AppName = My Application Name

; SmartInspect Logging Configuration Output settings.
; - Log to SmartInspect Console Viewer running on the specified network address.
Connections = tcp(host=192.168.1.1,port=4228,timeout=5000,reconnect=true,reconnect.interval=10s,async.enabled=true)
; - Log to a file, keeping 14 days worth of logs.
;Connections = "file(filename=\"./tests/logfiles/logfile.log\", rotate=daily, maxparts=14, append=true)"
; - Log to an encrypted file, keeping 14 days worth of logs.
;Connections = "file(filename=\"./tests/logfiles/logfileEncrypted.sil\", encrypt=true, key=""1234567890123456"", rotate=daily, maxparts=14, append=true)"
        
; set defaults for new sessions
; note that session defaults do not apply to the SiAuto.Main session, since
; this session was already added before a configuration file can be loaded. 
; session defaults only apply to newly added sessions and do not affect existing sessions.
SessionDefaults.Active = True
SessionDefaults.Level = Message
SessionDefaults.ColorBG = 0xFFFFFF

; configure some individual session properties.
; note that this does not add the session to the sessionmanager; it simply
; sets the property values IF the session name already exists.
Session.Main.Active = True
Session.Main.ColorBG = 0xFFFFFF

Initialize Logging Support, MAIN module

Add the following lines to your program startup module. This will import the necessary package modules, and initialize logging support. NOTE - This code should only be executed one time!

# load SmartInspect settings from a configuration settings file.
from smartinspectpython.siauto import *
siConfigPath:str = "./tests/smartinspect.cfg"
SIAuto.Si.LoadConfiguration(siConfigPath)

# start monitoring the configuration file for changes, and reload it when it changes.
# this will check the file for changes every 60 seconds.
siConfig:SIConfigurationTimer = SIConfigurationTimer(SIAuto.Si, siConfigPath, 60)

# get smartinspect logger reference.
_logsi:SISession = SIAuto.Main

# log system environment and application startup parameters.
_logsi.LogSeparator(SILevel.Fatal)
_logsi.LogAppDomain(SILevel.Verbose)
_logsi.LogSystem(SILevel.Verbose)

Initialize Logging Support, CLASS or sub-modules

Add the following lines to your program supporting modules. This will import the necessary package modules, and initialize the shared logging session.

# get smartinspect logger reference.
from smartinspectpython.siauto import *
_logsi:SISession = SIAuto.Main

More Information on SmartInspect

You can use SmartInspectPython by itself to create log files for your own applications. Use the following PIP command to install the SmartInspectPython package from PyPi.org: `pip install smartinspectpython`

The SmarrtInspect Redistributable Console Viewer (free) is required to view SmartInspect Log (.sil) formatted log files, as well capture packets via the TcpProtocol or PipeProtocol connections. The Redistributable Console Viewer can be downloaded from the Code-Partners Software Downloads Page. Note that the "Redistributable Console Viewer" is a free product, while the "SmartInspect Full Setup" is the Professional level viewer that adds a few more bells and whistles for a fee. Also note that a Console Viewer is NOT required to view plain text (non .sil) formatted log files.