This is an old revision of the document!
For HE4K-01 / HE4K-R4 / MVE-150 / MVE-100R / SME-01 / DME-02/03/04 use Z3-TI-http_api
To read configuration variable, simply perform an HTTP GET to the URL
http://server_address/cgi-bin/control.cgi
with the body as given below.
The reponse will be in JSON format, giving the value of each variable.
To read global configuration variables, GET with this body:
ctrl=sys&chn=null
To read encoder channel configuration variables for channel 1, GET with this body:
ctrl=enc&chn=1
Python example code for reading configuration:
import requests, json, sys server_url='http://192.168.0.120/cgi-bin/control.cgi' global_cfg = requests.get(server_url, params='ctrl=sys&chn=null') print global_cfg.json() enc_cfg = requests.get(server_url, params='ctrl=enc&chn=1' ) print enc_cfg.json()
Sample output:
>>> print global_cfg.json() {u'wifi_exists': False, u'processor_id': u'Hi3519', u'default_gw': u'192.168.0.1', u'disp_std': u'auto', u'session_id': u'---', u'timezone': u'CST6CDT,M3.2.0,M11.1.0', u'MODEL': u'Z3CAM-HD', u'pe3': u'', u'board_id': u'0xFF02', u'z3_termsrv': u'enabled', u'local_netmask': u'255.255.0.0', u'ret': u'0', u'z3_wifi': u'enabled', u'opmode': u'encoder', u'syspassword': u'', u'enc_current_preset': u'encoder', u'sysdevicename': u'ENCDEV', u'z3_tslowlat': u'enabled', u'z3_sntp': u'enabled', u'enc_adv_setting': u'off', u'do_autostart': 1, u'enc_channels': u'1', u'pe8': u'', u'local_dnsip': u'8.8.8.8', u'local_ip': u'192.168.0.120', u'pe4': u'', u'pe5': u'', u'pe6': u'', u'pe7': u'', u'pe0': u'encoder', u'pe1': u'', u'pe2': u'', u'opstate': u'RUNNING', u'enable_snmp': u'false', u'local_dnsip2': u'8.8.4.4', u'enable_sntp': u'false', u'use_dhcp': u'1', u'sntp_servers': u'128.138.141.172', u'focus_manual': u'auto', u'optical_zoom_only': u'0', u'visca_present': u'true'}>>> print enc_cfg.json() {u'zixioverhead': u'15', u'tsrate': u'3000K', u'zixiuser': u'user', u'vprofile': u'high', u'vbitrate': u'2M', u'feconoff': u'off', u'vdelay': 1000, u'vsource': u'hdmi', u'klvsrc': u'/dev/gv7601.0', u'fprefix': u'MOV1_%F_%T_', u'enc_status': u'RUNNING', u'telopenable': u'off', u'auth_passwd': u'password', u'teloplocation': u'top_left', u'pcrinterval': 50, u'aptspcr': 250, u'teloptext': u'ENCDEV', u'zixiauthen': u'off', u'tslowlat': u'on', u'storage': u'', u'vquality': u'balanced', u'ret': u'0', u'asamplerate': u'48000', u'vdest': u'192.168.0.6:8600', u'filesize': u'1024M', u'vgdr': u'on', u'telopcharsize': u'32', u'vratectrl': u'cbr', u'klvbrate': u'1000', u'abitrate': u'128000', u'vpid': 221, u'feccol': 5, u'acodec': u'fdk_aaclc', u'vframeratediv': 1, u'zixisession': u'test', u'vres': u'follow_input', u'pcrpid': 521, u'apid': 120, u'aenable': u'on', u'asource': u'MICL', u'vprotocol': u'rtsp', u'preset': u'actv_preset', u'nfstrength': u'0', u'aport': u'8700', u'klvpid': u'35', u'vgopsize': 60, u'pmtpid': 31, u'authonoff': u'off', u'vcodec': u'h265', u'klvenable': u'off', u'klvmode': u'sdi', u'auxonoff': u'off', u'channel': 1, u'mounts': u'', u'auth_user': u'user', u'fecrow': 1}
Description: Enable audio channel
Possible values: yes, no
Description: Audio encoder algorithm selection
Possible values: dsp_aaclc, fdk_aaclc, fdk_aache, fdk_aache_v2
Description: Audio encode bitrate
Possible values: Depends on codec; in units of bits per second
Description: Audio sample rate
Possible values: 48000, 44100
Description: Select audio input
Possible values: MICL (microphone, line input levels)
MIC (unpowered microphone levels) HDMI (microHDMI input, for HE4K-DCK only) HD-SDI (SDI input, for DME-10/FSDI-DCK only)
Description: Audio PID for transport stream.
Possible values: 32 to 8191 - must not conflict with other PID assignments.
Description: Destination UDP port for RTP audio
Description: For transport stream modes only – intial PTS to PCR offset for audio, in milliseconds
Possible values: 100 to 2000
Description: Password for RTMP authentication.
Description: Username for RTMP authentication.
Description: Enable or disable RTMP authentication. Default: off Possible values: on, off
Description: Encoder channel number
Possible values: 1, 2, 3
Description: Column count for ProMPEG.
Possible values: integer greater than 1
Description: Enable ProMPEG if supported.
Possible values: on, off
Description: Row count for ProMPEG.
Possible values: integer greater than 1
Description: Size of TSFILE or AUX file recording, in bytes.
A “K” suffix indicates kilobytes (thousands of bytes/second).
A “M” suffix indicates megabytes (millions of bytes/second).
Description: Relative filename for TSFILE or AUX file recording. Note that “fprefix” does NOT include the absolute media path – the “storage” parameter is the proper place to specify the absolute media path.
Absolute path to mounted media device (e.g. /media/sda1/)
OSD overlay text character size in pixels
Possible values: 16, 32, or 64
Enable or disable telop (i.e. OSD overlay of text).
Possible values: on, off
Where to overlay text in the encoded video
Possible values: top_left top_right top_center bottom_left bottom_right bottom_center
Text string for OSD overlay
Description: Distance between I frames (key frames) in GOP sequence
Possible values: 1 through 240
Description: Video bitrate in bits per second.
Possible values: A “K” suffix indicates kilobits (thousands of bits/second).
A “M” suffix indicates megabits (millions of bits/second).
Note: In UDP transport stream case, the tsrate should be set
higher than the vbitrate, with at least 15% margin.
Description: Video maximum burst size in milliseconds.
Possible values: 100 to 2000
Description: Destination URL address for encoded bitstream. May be interpreted differently depending on “vprotocol” setting.
For UDP and RTP transports:
client_ip:client_port
For RTMP transport:
server_ip[:server_port]/application/streamname
Description: Divide video input frame rate by this number to get encode frame rate.
The encoder will discard (frameratediv-1) out of (frameratediv) frames.
Possible values: 1, 2, 3, 4, 5, 6
Description: Enable or disable Gradual Data Refresh. Reduces I-frame size (reduces latency). At lower bitrates, a horizontal rolling artifact may be visible.
Possible values: on, off
Description: Specifiec which codec to encode with.
Possible values: h265, h264, mjpeg
Description: H.264 profile (see https://en.wikipedia.org/wiki/H.264/MPEG-4_AVC#Profiles for full description)
Possible values: baseline, main, high
Description: Protocol used to transport the encoded bitstream.
Possible values: rtp, rtmp, udp, asi, tsfile, mts, tsrtp
Description: Set balance between low latency, and higher quality+bitrate compliance.
Possible values: lowlat, balanced, high
Description: Rate control mode for encoder.
Possible values: cbr, vbr
vbr mode may be burstier than cbr.
Description: Video resolution
Possible values: follow_input preserve video source resolution, no resize
WxH resize to width W and height H
Description: Video input from which encoder will source its video
Possible values: Board-dependent
Description: Enable PIP of channel 2 on channel 1 encode. Only available on FV4K/FV2K/FSDI
Possible values: on, off
Description: Sets the location of the PIP on channel one. Only available on FV4K/FV2K/FSDI
Possible values: top_left, top_right, bottom_left, bottom_right
Description: Sets the interlaced mode for the video input
Possible values: combined, separated (H265 only)
Description: video multicast destination for RTSP. Used by ONVIF StartMulticast/StopMulticast functions
Possible values: valid multicast addresses
Description: audio multicast destination for RTSP. Used by ONVIF StartMulticast/StopMulticast functions
Possible values: valid multicast addresses
Description: enables/disables rtsp authorization for stream
Possible values: on, off
Description: username for rtsp authorization
Possible values: alpha numeric string
Description: password for rtsp authorization
Possible values: *
The following parameters only apply to transport stream encoding (transport is set to udp, asi, tsfile, mts, or tsrtp).
Description: Video PID for transport stream.
Possible values: 32 to 8191 – must not conflict with other PID assignments
Description: Audio PID for transport stream.
Possible values: 32 to 8191 – must not conflict with other PID assignments
Description: PCR PID for transport stream.
Possible values: 32 to 8191 – must not conflict with other PID assignments
Description: PMT PID for transport stream.
Possible values: 16 to 31 – must not conflict with other PID assignments
Description: Transport stream total transport rate in bits per second.
Possible values: The 'K' suffix indicates kilobits (thousands of bits/second). The 'M' suffix indicates megabits (millions of bits/second).
Note: In UDP transport stream case, the tsrate should be set higher than the vbitrate, with at least 15% margin.
Description: Low latency transport stream mode (VBR).
Possible values: off, on
Describe: Enable AUXillary file recording in UDP mode – allows simultaneous UDP streaming and TS file recording on the same channel. Only valid if transport is UDP and tslowlat is off
The path to storage is set by the “storage” parameter.
The filename is set by the “fprefix” parameter. The default value is “MOV1_%F_%T”. The “%F” specifier inserts a date stamp, and the “%T” specifier inserts a time stamp.
The recording file size is set by the “filesize” parameter. When the file reaches this size, a new file will be created.
Description: Bitrate to allocate in transport stream for KLV data.
Description: Enable KLV capture from SDI, if supported.
Possible values: off, on
Description: PID for KLV data in transport stream
Description: Source device for KLV metadata
Description: Interval between PCR packets in milliseconds.
Possible values: 30 - 100
Python example code for starting/stopping all channels:
import requests, json import sys, getopt actionname='StartChannel' server_url='http://192.168.0.120' control_cgi_url = server_url + '/cgi-bin/control.cgi' payload = 'ctrl=sys&chn=null' sysctrl = requests.get(control_cgi_url, params=payload) j = sysctrl.json() print j enc_channels_string = j['enc_channels'] opmode = j['opmode'] enc_channels = enc_channels_string.split( ',' ) print 'enc_channels', enc_channels, 'opmode', opmode channel_list = enc_channels for channel in channel_list : # Remove leading C if channel[0:0] == 'C': channel = channel[1:] print actionname, ' ', opmode, 'channel', channel payload = 'action='+actionname+'&'+ 'chn=' +channel+'&' + 'loadfromdb=true'; headers={'Content-Type':'application/x-www-form-urlencoded; charset=UTF-8'} r = requests.post(control_cgi_url, data=payload, headers=headers) print r.text
The “loadfromdb=true” parameter will load the current settings from the database.
If you omit the loadfromdb parameter, *none* of the database settings will be used – any parameters you do not supply, will be set to default values.
For example, this is what a StartChannel request from the web server looks like:
action=StartChannel&chn=1&vsource=&vres=follow_input&vcodec=h265&vgdr=on&vprofile=high&vratectrl=cbr&vbitrate=2M&vframeratediv=1&vgopsize=60&vprotocol=rtsp&vdest=192.168.0.6:8600&storage=&fprefix=MOV1_%F_%T_&vpid=221&vdelay=1000&pcrpid=521&pcrinterval=50&pmtpid=31&tsrate=3000K&tslowlat=on&feconoff=off&fecrow=1&feccol=5&zixioverhead=15&zixiauthen=off&zixisession=test&zixiuser=user&aenable=on&asource=MICL&acodec=fdk_aaclc&abitrate=128000&asamplerate=48000&aport=8700&apid=120&aptspcr=250&klvenable=off&klvmode=sdi&klvsrc=/dev/gv7601.0&klvpid=35&klvbrate=1000&authonoff=off&auth_user=user&auth_passwd=password&auxonoff=off&filesize=1024M&telopenable=off&teloptext=ENCDEV&teloplocation=top_left&telopcharsize=32&vquality=balanced
Transition the encoder channel into the running state.
Once you start the channel, it will not transmit data until the
video input is detected.
Transition the encoder channel into the stopped state.
Save current settings to non-volatile memory, so they will be used on the next startup.
Reboot the board
Send VISCA commands to camera.
Only one command can be sent at a time; the list below are the only supported VISCA commands through the HTTP API. To use VISCA commands that are not listed, usage of the TCP socket can be used to send those VISCA commands.
API Format:
action=CameraControl&command=visca_command
example:
Commands without value assignments
action=CameraControl&command=dzoom_off
Commands with value assignments
action=CameraControl&command=set_monitor_mode 1080p-59.94
The commands use the same syntax as the serial menu “V” command, as shown below
For the most current list of VISCA commands supported press “V” from the Serial/SSH session of the Serial Menu.
auto_icr_disable auto_icr_enable cam_control_inquiry cam_custom_recall cam_custom_reset cam_custom_set chroma_get_suppress chroma_suppress Set Chroma Suppression (0=none, 1 to 3=chroma supression strength) clear_if color_gain Set Color gain (0=60%, 14=200%) color_get_gain color_get_hue color_hue Set Color hue (0=-14 degrees, 14=+14 degrees) debug_rx dzoom_combine_mode dzoom_direct D-Zoom Position (0x00 to 0xeb) * Enabled during Separate mode dzoom_off dzoom_on dzoom_separate_mode dzoom_stop dzoom_super_res dzoom_tele_var p = 0 (Low) .. 7 (High) * Enabled during Separate Mode dzoom_wide_var p = 0 (Low) .. 7 (High) * Enabled during Separate Mode dzoom_x1_max eflip_off eflip_on ext1_func_inquiry ext2_func_inquiry ext3_func_inquiry focus_auto focus_direct focus pos Min. 0x1000 Over Inf 0x2000 10m 0x3000 5m 0x4000 3.3m 0x5000 2.5m 0x6000 2m 0x7000 1.7m 0x8000 1.5m 0x9000 1m 0xa000 50cm 0xb000 30cm 0xc000 15cm 0xd000 6cm 0xe000 1cm focus_get_mode focus_get_pos focus_manual focus_near_limit focus near limit Min. 0x1000 Over Inf 0x2000 10m 0x3000 5m 0x4000 3.3m 0x5000 2.5m 0x6000 2m 0x7000 1.7m 0x8000 1.5m 0x9000 1m 0xa000 50cm 0xb000 30cm 0xc000 15cm 0xd000 6cm 0xe000 1cm focus_stop focus_tele_std focus_tele_var p = 0 (Low) .. 7 (High) focus_toggle focus_wide_std focus_wide_var p (0 (Low) .. 7 (High)) get_low_delay_mode Get low delay mode: 0 - normal, 1 - low delay get_monitor_mode get_monitor_mode: Get video mode of camera output help high_sensitivity_off high_sensitivity_on icr_mode modes: auto on off threshold [0-255] lens_control_inquiry lens_get_temp lr_reverse_off lr_reverse_on other_inquiry power_inquiry power_off power_on register_read Read internal register. register_write Write internal register. * Note: To make register changes effective, run power_off and power_on set_address set_low_delay_mode Set low delay mode: 0 - normal, 1 - low delay set_monitor_mode Set monitor mode. List of modes: 1080p-25 720p-50 720p-59.94 2160p-25 2160p-29.97 1080p-29.97 1080p-59.94 1080p-50 slow_shutter modes: on off limit [0-255] trace enable (0=off, 1=on) version_inquiry wb_auto_mode wb_autotrace_mode wb_get_bgain wb_get_mode wb_get_mode_name wb_get_rgain wb_indoor_mode wb_manual_bgain_direct Set Manual WB BGain (0..255) * Enabled during Manual WB mode wb_manual_bgain_reset wb_manual_mode wb_manual_rgain_direct Set Manual WB RGain (0..255) * Enabled during Manual WB mode wb_manual_rgain_reset wb_onepush_mode wb_onepush_trigger wb_outdoor_auto_mode wb_outdoor_mode wb_sodium_lamp_auto_mode wb_sodium_lamp_fixed_mode wb_sodium_lamp_outdoor_mode zoom_direct pos Min. 0x0000 Max. 0x4000 (In Separate mode) Max. 0x4000 (In Combine mode and DZoom=Off) Max. 0x59C0 (In Combine mode, DZoom=Super Resolution Zoom, and monitoring mode QFHD) Max. 0x6000h (In Combine mode, DZoom=Super Resolution Zoom, and monitoring mode FHD or less) Max. 0x7AC0h (In Combine mode and DZoom=On) zoom_get_pos zoom_stop zoom_tele_std zoom_tele_var p = 0 (Low) .. 7 (High) zoom_wide_std zoom_wide_var p (0 (Low) .. 7 (High))
Save camera-related settings below.
Description: Set camera zoom
Possible values: 0 (wide) to 0x7ac0 (full zoom)
Possible values: auto. indoor, outdoor, onepush, autotrace, manual, outdoor_auto,
sodium_lamp_auto, sodium_lamp_fixed, sodium_lamp_outdoor
Possible values: Range from 0 (60%) to 14 (200%)
Possible values: Range from 0 (60%) to 14 (200%)
Possible values: 0=none, 1, 2, 3
Possible values: 0 to 255
Possible values: 0 to 255
Possible values: 0, 1
Description: Set manual camera focus distance Possible values: 0x1000 to 0xf000
Description: Set focus mode
Possible values: auto, manual
IPv4 adresss
IPv4 netmask
IPv4 default gateway
DNS server primary
DNS server secondary
Control automatic stream start after bootup
Possible values: 1 = do autostart 0 = do not autostart
Control appearance of advanced settings on WebUI
Possible values: off, on
Controls composite output (passthru video from camera)
Set display standard for composite output
Possible values; auto, ntsc, pal
Control serial port terminal server for VISCA
Possible values: client, server
Possible values: clearchannel, telnet
Local TCP port (for server mode)
Remote IP address (for client mode only)
Remote TCP port (for client mode only)
Possible values: 9600, 19200, 38400, 57600, 115200
Add/Update overlay
Encoder channel to add overlay to.
Index to map overlay to.
Type of overlay to be used possible values: text or png.
In the case of text overlay this would be the source text for png overlay this is the path to the png on the encoder. Images must be uploaded to board to be used.
This is the location of the overlay. Possible values: 'top_left', 'top_right', 'top_center', 'bottom_left', 'bottom_right', 'bottom_center', 'x,y' (negative numbers not supported for x or y)
For text overlay this is the character size. Possible values: 16,32,64
This will set the layer for the overly higher numbers will overlay over lower numbers if overlapping.
Sets the transparency of the text. Possible values: 0-255
Encoder channel to remove overlay from.
Index of overly for this channel.
Encoder channel to apply dynamic command to.
var
Variable to modify dynamically. Possible values: vratediv, vrate, gop, analog_gain, telop_text, pip_enable, pip_location, startmulticast, stopmulticast
Value to set dynamic variable to.
Enable/Disable SNTP.
NTP server or list of NTP servers.
Linux TZ database value for Timezone.
Enable/Disable ONVIF.
Maximum ONVIF profiles to allow (1 or 2).
Enable/Disable remote access to terminal server.
Enable/Disable zfinder support.
Write encoder settings to active preset. See Python example code for Seting Configuration below
Requests an update to encoder_status_str variable.
To read the result, you need to POST the “stats” control as shown\ in the Python example code below.
Requests an update to stream_status_str variable.
To read the result, you need to POST the “stats” control as shown\ in the Python example code below.
Requests an update to astream_status_str variable.
To read the result, you need to POST the “stats” control as shown\ in the Python example code below.
Requests an update to source_status_str variable.
To read the result, you need to POST the “stats” control as shown\ in the Python example code below.
To set the encode configuration per channel the SetEncoder action is used with a post. All variables should be present or they will be replaced with a defualt that may not be valid for your application. More than one channel can be set per command. It is recommended you first read the current settings from the encoder then modify them and send the new settings back as in the Python example below:
import requests, json, sys server_url='http://192.168.0.120/cgi-bin/control.cgi' channel = 1 enc_cfg = requests.get(server_url, params='ctrl=enc&chn={}'.format(channel)) print enc_cfg.json() enc_cfg_json=enc_cfg.json() enc_cfg_json['vframeratediv'] = 2 #set frame rate divider to 2 new_cfg = {} new_cfg['action'] = 'SetEncoder' for key, value in enc_cfg_json.iteritems(): print "key = {} value = {}".format(key,value) new_idx = "enc_{}_{}".format(channel,key) print "setting {} to {}".format(new_idx,value) new_cfg[new_idx] = value print new_cfg requests.post(server_url, data=new_cfg)
Python example of updating and reading encoder statistics:
import requests, json, sys server_url='http://192.168.0.120/cgi-bin/control.cgi' requests.post(server_url, data={'action' : 'EncoderStatus'}) requests.post(server_url, data={'action' : 'StreamStatus'}) requests.post(server_url, data={'action' : 'AStreamStatus'}) requests.post(server_url, data={'action' : 'SourceStatus'}) requests.post(server_url, data={'action' : 'TempStatus'}) print requests.get(server_url, params='ctrl=stats&chn=').json()
Example output:
{u'status': u'OK', u'astream_status_str': u'\tChannel 1 Codec fdk_aaclc Frames 8998 +OK', u'temp_status_str': u'+LENS 39 +FPGA 42 +CPU 42 +OK', u'ret': u'0', u'encoder_status_str': u' *** Encode Bitstream Received Statistics *** Elapsed time = 0.0 secs CH | Bitrate (Kbps) | Actual Bitrate | FPS | Actual FPS | Key-frame FPS | Width | Height ------------------------------------------------------------------------------------------------------------ 1 | 2000.00 | 2020.17 | 60.0 | 60.0 | 1.0 | 1920 | 1080 | +OK', u'source_status_str': u'+CAMERA 1920x1080p 60.00 fps +OK', u'stream_status_str': u'Channel 1 URL rtsp Frames 11524 +OK'}