Difference between revisions of "IVS Module"

From IVS Wiki
Jump to: navigation, search
(Created page with "=VALT Class= ==Class Specifications== ===Usage=== Creates a class that is one instance of a connection to a VALT server. The below functions are all defined as part of the val...")
 
(→‎Usage)
 
(2 intermediate revisions by the same user not shown)
Line 69: Line 69:
  
 
===Example===
 
===Example===
−
<pre>valttest = ivs.valt("ivstest1.ad.ipivs.com","admin","admin")</pre>
+
<pre>valt = ivs.valt("ivstest1.ad.ipivs.com","admin","admin")</pre>
 
==auth==
 
==auth==
 
===Usage===
 
===Usage===
Line 240: Line 240:
 
|markertime
 
|markertime
 
|int
 
|int
−
|Time index to insert the marker. If not specified will use the current time index. When specifying a marker time, you must also specified a color.
+
|Time index to insert the marker. If not specified will use the current time index. When specifying a marker time, you must also specify a color.
 
|No
 
|No
 
|}
 
|}
Line 310: Line 310:
 
==getcameras==
 
==getcameras==
 
===Usage===
 
===Usage===
−
Returns a nested list, containing details for the cameras in the specified room. Primarily used with the AXIS module to enable/disable privacy mode on cameras.
+
Returns a nested list, containing details for the cameras in the specified room.
 
===Parameters===
 
===Parameters===
 
<pre>getcameras(room)</pre>
 
<pre>getcameras(room)</pre>
Line 332: Line 332:
 
Returns a list of rooms if successful. Each list item is actually a dictionary containing information about that room.
 
Returns a list of rooms if successful. Each list item is actually a dictionary containing information about that room.
 
===Parameters===
 
===Parameters===
−
<pre>getcameras()</pre>
+
<pre>getrooms()</pre>
  
 
This function does not accept any parameters.
 
This function does not accept any parameters.
Line 421: Line 421:
 
|Locked
 
|Locked
 
|4
 
|4
 +
|-
 +
|Prepared
 +
|5
 
|}
 
|}
  
 
===Parameters===
 
===Parameters===
−
<pre>getroomstatus(https,server,accesstoken,room)</pre>
+
<pre>getroomstatus(room)</pre>
 
{| class="wikitable"
 
{| class="wikitable"
 
|-
 
|-
−
|Parameter
+
!Parameter
−
|Type
+
!Type
−
|Value
+
!Value
−
|-
+
!Required
−
|https
 
−
|Boolean
 
−
|True if the server uses HTTPS, otherwise False.
 
−
|-
 
−
|server
 
−
|String
 
−
|IP address or DNS name of the Valt application server.
 
−
|-
 
−
|accesstoken
 
−
|String
 
−
|The authentication token returned by the function '''valtauth'''.
 
 
|-
 
|-
 
|room
 
|room
 
|Integer
 
|Integer
 
|The room number of the room in the Valt application. This must be the actual room ID number, not the room name. This can be obtained from the database.
 
|The room number of the room in the Valt application. This must be the actual room ID number, not the room name. This can be obtained from the database.
 +
|Yes
 
|}
 
|}
 
===Example===
 
===Example===
−
<pre>roomstatus = valt.getroomstatus(True,'valt.example.com','3e2c3e461736ce73830ed8d6d9d5dae6',4)</pre>
+
<pre>roomstatus = valt.getroomstatus(4)</pre>
  
−
==creategroup==
+
==getusers==
 
===Usage===
 
===Usage===
−
Connects to the VALT server and creates a user group with the specified rights, templates, retention period, and video access.
+
Function to return a list of users. Each list item is a dictionary with information about the user. Returns 0 on failure. Returns 99 if not currently authenticated to VALT.
 +
===Parameters===
 +
<pre>getusers()</pre>
 +
 
 +
This function does not accept any parameters.
 +
 
 +
===Example===
 +
<pre>users = valt.getusers()</pre>
  
 +
==setsharing==
 +
===Usage===
 +
Function changes/sets sharing permission on the specified recording. Users and groups must be passed as lists, encloded in []. Returns 0 on failure. Returns 99 if not currently authenticated to VALT.
 
===Parameters===
 
===Parameters===
−
<pre>creategroup(https,server,accesstoken,groupname,infoid,markerid)</pre>
+
<pre>setsharing(recid,users=[],groups=[])</pre>
 
{| class="wikitable"
 
{| class="wikitable"
 
|-
 
|-
Line 463: Line 466:
 
!Required
 
!Required
 
|-
 
|-
−
|https
+
|recid
−
|Boolean
+
|Integer
−
|True if the server uses HTTPS, otherwise False.
+
|The recording number of the record in the Valt application. This must be the actual record ID number, not the record name. This can be obtained from the database.
 
|Yes
 
|Yes
 
|-
 
|-
−
|server
+
|users
−
|String
+
|list
−
|IP address or DNS name of the VALT application server.
+
|Comma separated list of users to be granted permission to the specified video. This must be the user ID number. This is an optional parameter and must be specified as users=[1,2,3,4].
−
|Yes
 
 
|-
 
|-
−
|accesstoken
 
−
|String
 
−
|The authentication token returned by the function '''valtauth'''.
 
−
|Yes
 
−
|-
 
−
|Group name
 
−
|String
 
−
|The name that will be given the to group in VALT.
 
−
|Yes
 
−
|-
 
−
|infoid
 
−
|Int
 
−
|The id number of the information template that will be assigned to the group as the default.
 
−
|Yes
 
−
|-
 
−
|markerid
 
−
|Int
 
−
|The id number of the marker template that will be assigned to the group as the default.
 
−
|Yes
 
−
|-
 
−
|rights
 
−
|List (of strings)
 
−
|All the rights that should be granted to the new group in VALT.
 
 
|No
 
|No
 
|-
 
|-
−
|max_record_duration
+
|groups
−
|Int
+
|list
−
|The maximum record duration in minutes.
+
|Comma separated list of groups to be granted permission to the specified video. This must be the groups ID number. This is an optional parameter and must be specified as groups=[1,2,3,4].
 
|No
 
|No
 +
|}
 +
===Example===
 +
<pre>valt.setsharing(176,users=[4,36,17,28],groups=[2,4])</pre>
 +
 +
==lockroom==
 +
===Usage===
 +
Locks the specified room.
 +
===Parameters===
 +
<pre>lockroom(room)</pre>
 +
{| class="wikitable"
 
|-
 
|-
−
|rooms
+
!Parameter
−
|List (of ints)
+
!Type
−
|Room ids the new group should be granted access to in VALT.
+
!Value
−
|No
+
!Required
 
|-
 
|-
−
|video_access_users
+
|room
−
|List (of ints)
+
|Integer
−
|User ids the new group should be granted video access to in VALT.
+
|The room number of the room in the Valt application. This must be the actual room ID number, not the room name. This can be obtained from the database.
−
|No
+
|Yes
 +
|}
 +
===Example===
 +
<pre>valt.lockroom(4)</pre>
 +
 
 +
==unlockroom==
 +
===Usage===
 +
Unlocks the specified room.
 +
===Parameters===
 +
<pre>unlockroom(room)</pre>
 +
{| class="wikitable"
 
|-
 
|-
−
|video_access_groups
+
!Parameter
−
|List (of ints)
+
!Type
−
|Group ids the new group should be granted video access to in VALT.
+
!Value
−
|No
+
!Required
 
|-
 
|-
−
|retention_type
+
|room
−
|String
+
|Integer
−
|Retention Type (Valid Values: infinitely, until, days, hours, minutes)
+
|The room number of the room in the Valt application. This must be the actual room ID number, not the room name. This can be obtained from the database.
−
|No
+
|Yes
−
|-
 
−
|retention_until
 
−
|String
 
−
|Date formatted as MM-DD-YYYY
 
−
|No
 
−
|-
 
−
|retention_for
 
−
|Int
 
−
|Value in hours, minutes, or days (as specified by retention_type) the video will retained for.
 
−
|No
 
 
|}
 
|}
 +
===Example===
 +
<pre>valt.unlockroom(4)</pre>
  
−
===Example===
 
−
<pre>valt.creategroup(https,server,auth,splitline[0],30,71,rights=rightslist,max_record_duration=180,video_access_users=[14,15,17],video_access_groups=[2,6],retention_type="days",retention_for=365)</pre>
 
 
=Other Functions=
 
=Other Functions=
 
==log==
 
==log==
Line 567: Line 556:
 
===Example===
 
===Example===
 
<pre>ivs.factorydefault</pre>
 
<pre>ivs.factorydefault</pre>
 +
==loadconfig==
 +
===Usage===
 +
This function is used to load configuration data from a json formatted config file.
 +
===Parameters===
 +
<pre>loadconfig(configfilepath)</pre>
 +
{| class="wikitable"
 +
|-
 +
!Parameter
 +
!Type
 +
!Value
 +
!Required
 +
|-
 +
|configfilepath
 +
|string
 +
|Path to the configuration file.
 +
|Yes
 +
|-
 +
|}
 +
===Example===
 +
<pre>ivs.loadconfig("/usr/local/ivs/config/keypad.cfg")</pre>
 +
==saveconfig==
 +
===Usage===
 +
This function is used to save configuration data to a json formatted config file.
 +
 +
===Parameters===
 +
<pre>saveconfig(configarray,configfilepath)</pre>
 +
{| class="wikitable"
 +
|-
 +
!Parameter
 +
!Type
 +
!Value
 +
!Required
 +
|-
 +
|configarray
 +
|string
 +
|Array containing all configuration information with keys.
 +
|Yes
 +
|-
 +
|configfilepath
 +
|string
 +
|Path to the configuration file.
 +
|Yes
 +
|-
 +
|}
 +
===Example===
 +
<pre>ivs.saveconfig(keypadconfigarray,"/usr/local/ivs/config/keypad.cfg")</pre>

Latest revision as of 15:55, 19 August 2022

Contents

VALT Class

Class Specifications

Usage

Creates a class that is one instance of a connection to a VALT server. The below functions are all defined as part of the valt class and can be called.

Initiation

Upon initiation, the class will attempt to authenticate to the specified VALT server using the provided credentials. If authentication fails upon initiation or upon any further actions, the class will wait 30 seconds and then attempt to reauthenticate. Upon success, the class with reauthenticate every 24 hours.

Variables

Variable Type Value
username string Stores the username used to authenticate to VALT.
password string Stores the password used to authenticate to VALT.
baseurl String Stores the basic url to connect to valt. The url is composed of the valt server address. For example http://ivstest1.ad.ipivs.com/api/v3/
success_reauth_time int The number of seconds to wait before reauthenticating to VALT after a successful authentication. Default is 28800.
failure_reauth_time int The number of seconds to wait before reauthenticating to VALT after a failed authentication attempt. Default is 30.
accesstoken string Stores the current access token retrieved during the last successful authentication. This will be set to 0 upon a failed authentication attempt or an error during any other function.
lastauthtime time Stores the last epoch time when authentication was attempted.

Parameters

valt(server,username,password)
Parameter Type Value Required
server String IP address or DNS name of the Valt application server. Yes
username String Valt Username. Yes
password String Valt Password. Yes

Example

valt = ivs.valt("ivstest1.ad.ipivs.com","admin","admin")

auth

Usage

Connects to the Valt server. This function is executed automatically during initializaton.

Parameters

auth()

This function does not accept any parameters.

Example

valt.auth()

isrecording

Usage

Checks the state of a room and returns True if it is recording, or False if it is not. Returns 2 if an error is encountered.

Parameters

isrecording(room)
Parameter Type Value Required
room Integer The room number of the room in the Valt application. This must be the actual room ID number, not the room name. This can be obtained from the database. Yes

Example

if valt.isrecording(4):

getrecordingid

Usage

If the room is currently recording, it returns the ID of the active recording. You should check if the room is recording using the isrecording function prior to getting the recording ID.

Parameters

getrecordingid(room)
Parameter Type Value Required
room Integer The room number of the room in the Valt application. This must be the actual room ID number, not the room name. This can be obtained from the database. Yes

Example

current_recording = valt.getrecording(4)

startrecording

Usage

Starts a new recording in the specified room.

Parameters

startrecording(room,name,author)
Parameter Type Value Required
room Integer The room number of the room in the Valt application. This must be the actual room ID number, not the room name. This can be obtained from the database. Yes
name String The name that will be associated with the recording in Valt. Yes
author int The user id under which the recording should be started. If not specified, the recording will be started under the authenticated user. Must be specified as author= when calling the function. See the example below. No

Example

valt.startrecording(4,"My Recording",author=12)

stoprecording

Usage

Stops the current recording in the specified room.

Parameters

stoprecording(room)
Parameter Type Value Required
room Integer The room number of the room in the Valt application. This must be the actual room ID number, not the room name. This can be obtained from the database. Yes

Example

valt.stoprecording(4)

pauserecording

Usage

Pauses the current recording in the specified room.

Parameters

pauserecording(room)
Parameter Type Value Required
room Integer The room number of the room in the Valt application. This must be the actual room ID number, not the room name. This can be obtained from the database. Yes

Example

valt.pauserecording(4)

resumerecording

Usage

Unpauses the current recording in the specified room.

Parameters

resumerecording(room)
Parameter Type Value Required
room Integer The room number of the room in the Valt application. This must be the actual room ID number, not the room name. This can be obtained from the database. Yes

Example

valt.resumerecording(4)

WARNING

As of the writing of this article, pausing and unpausing the recording will reset the duration timer for the recording. This may cause issues with inserting markers.

addmarker

Usage

Adds a marker to the recording in progress in the specified room.

Parameters

addmarker(room,markername,color,markertime)
Parameter Type Value Required
room Integer The room number of the room in the Valt application. This must be the actual room ID number, not the room name. This can be obtained from the database. Yes
markername String Name for the marker in the Valt application. Yes
color String Color for the marker, valid values are white, gray, red, yellow, purple, cyan, blue, green, and orange. If not specified, will default to red. No
markertime int Time index to insert the marker. If not specified will use the current time index. When specifying a marker time, you must also specify a color. No

Example

valt.addmarker(4,"My Marker","green",137)

getrecordingtime

Usage

Returns the current time value of the recording in the specified room. Primarily used by the add marker function to specify the time for the marker.

Parameters

getrecordingtime(room)
Parameter Type Value Required
room Integer The room number of the room in the Valt application. This must be the actual room ID number, not the room name. This can be obtained from the database. Yes

Example

current_recording_time = valt.getrecordingtime(4)

ispaused

Usage

Checks the state of a room and returns True if it is paused, or False if it is not.

Parameters

ispaused(room)
Parameter Type Value Required
room Integer The room number of the room in the Valt application. This must be the actual room ID number, not the room name. This can be obtained from the database. Yes

Example

if valt.ispaused(4):

islocked

Usage

Checks the state of a room and returns True if it is locked and False if it is not.

Parameters

islocked(room)
Parameter Type Value Required
room Integer The room number of the room in the Valt application. This must be the actual room ID number, not the room name. This can be obtained from the database. Yes

Example

if valt.islocked(4):

getcameras

Usage

Returns a nested list, containing details for the cameras in the specified room.

Parameters

getcameras(room)
Parameter Type Value Required
room Integer The room number of the room in the Valt application. This must be the actual room ID number, not the room name. This can be obtained from the database. Yes

Example

cameras = valt.getcameras(4)

getrooms

Usage

Returns a list of rooms if successful. Each list item is actually a dictionary containing information about that room.

Parameters

getrooms()

This function does not accept any parameters.

Example

rooms = valt.getrooms()

getschedule

Usage

Returns a nested list of all upcoming schedules for the specified room. The returned list contains the start and end time for each schedule.

Parameters

getschedule(room)
Parameter Type Value Required
room Integer The room number of the room in the Valt application. This must be the actual room ID number, not the room name. This can be obtained from the database. Yes

Example

schedules = valt.getschedule(4)

getroomname

Usage

Returns the name of the room in VALT.

Parameters

getroomname(room)
Parameter Type Value Required
room Integer The room number of the room in the Valt application. This must be the actual room ID number, not the room name. This can be obtained from the database. Yes

Example

roomname = valt.getroomname(4)

getusername

Usage

Returns the name of the user in VALT.

Parameters

getusername(user)
Parameter Type Value Required
user Integer The user number of the user in the Valt application. This must be the actual user ID number, not the user name. This can be obtained from the database. Yes

Example

username = valt.getusername(4)

getroomstatus

Usage

Returns a value indicating the current status of the room. This should be used instead of islocked, ispaused, or isrecording as it also includes better error handling.

Room Status Return Value
ERROR 0
Available 1
Recording 2
Paused 3
Locked 4
Prepared 5

Parameters

getroomstatus(room)
Parameter Type Value Required
room Integer The room number of the room in the Valt application. This must be the actual room ID number, not the room name. This can be obtained from the database. Yes

Example

roomstatus = valt.getroomstatus(4)

getusers

Usage

Function to return a list of users. Each list item is a dictionary with information about the user. Returns 0 on failure. Returns 99 if not currently authenticated to VALT.

Parameters

getusers()

This function does not accept any parameters.

Example

users = valt.getusers()

setsharing

Usage

Function changes/sets sharing permission on the specified recording. Users and groups must be passed as lists, encloded in []. Returns 0 on failure. Returns 99 if not currently authenticated to VALT.

Parameters

setsharing(recid,users=[],groups=[])
Parameter Type Value Required
recid Integer The recording number of the record in the Valt application. This must be the actual record ID number, not the record name. This can be obtained from the database. Yes
users list Comma separated list of users to be granted permission to the specified video. This must be the user ID number. This is an optional parameter and must be specified as users=[1,2,3,4].
No
groups list Comma separated list of groups to be granted permission to the specified video. This must be the groups ID number. This is an optional parameter and must be specified as groups=[1,2,3,4]. No

Example

valt.setsharing(176,users=[4,36,17,28],groups=[2,4])

lockroom

Usage

Locks the specified room.

Parameters

lockroom(room)
Parameter Type Value Required
room Integer The room number of the room in the Valt application. This must be the actual room ID number, not the room name. This can be obtained from the database. Yes

Example

valt.lockroom(4)

unlockroom

Usage

Unlocks the specified room.

Parameters

unlockroom(room)
Parameter Type Value Required
room Integer The room number of the room in the Valt application. This must be the actual room ID number, not the room name. This can be obtained from the database. Yes

Example

valt.unlockroom(4)

Other Functions

log

Usage

Used to to write log entries to a standard central log. This function is used by the valt class. This function writes a time stamp in YYYY-MM-DD HH:MM:SS format before each log entry.

Parameters

log(message,logpath)
Parameter Type Value Required
message string String to be written to the log. Yes
logpath string Local path to the log file. If not specified it will default to ivs.log in the same directory as the executed python program. No

Example

ivs.log("Room 127 Unlocked")

factorydefault

Usage

This function is specific to the use of IVS accessories. The factory default function restores all config files to a template and re-enables the web service. It then reboots the device. This function is currently only supported on the IVS Keypad and IVS Card Reader.

Example

ivs.factorydefault

loadconfig

Usage

This function is used to load configuration data from a json formatted config file.

Parameters

loadconfig(configfilepath)
Parameter Type Value Required
configfilepath string Path to the configuration file. Yes

Example

ivs.loadconfig("/usr/local/ivs/config/keypad.cfg")

saveconfig

Usage

This function is used to save configuration data to a json formatted config file.

Parameters

saveconfig(configarray,configfilepath)
Parameter Type Value Required
configarray string Array containing all configuration information with keys. Yes
configfilepath string Path to the configuration file. Yes

Example

ivs.saveconfig(keypadconfigarray,"/usr/local/ivs/config/keypad.cfg")
Retrieved from "https://ipivs.info/wiki/index.php?title=IVS_Module&oldid=10595"