This is an old revision of the document!
Table of Contents
HTTP API for Z3CAM / HE2K-DCK / HE4K-DCK / FV2K-DCK / FV4K-DCK/ FSDI-DCK / DME-10 / HE1080-RPS
For HE4K-01 / HE4K-R4 / MVE-150 / MVE-100R / SME-01 / DME-02/03/04 use Old API
Configuration API Syntax
Reading Configuration
To read configuration variable, simply perform an HTTP POST 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, POST with this body:
ctrl=sys&chn=null
To read encoder channel configuration variables for channel 1, POST 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}
Encoder Channel Configuration
aenable
Description: Enable audio channel
Possible values: yes, no
acodec
Description: Audio encoder algorithm selection
Possible values: dsp_aaclc, fdk_aaclc, fdk_aache, fdk_aache_v2
abitrate
Description: Audio encode bitrate
Possible values: Depends on codec; in units of bits per second
asamplerate
Description: Audio sample rate
Possible values: 48000, 44100
asource
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)
apid
Description: Audio PID for transport stream.
Possible values: 32 to 8191 - must not conflict with other PID assignments.
aport
Description: Destination UDP port for RTP audio
aptspcr
Description: For transport stream modes only – intial PTS to PCR offset for audio, in milliseconds
Possible values: 100 to 2000
auth_passwd
Description: Password for RTMP authentication.
auth_user
Description: Username for RTMP authentication.
authonoff
Description: Enable or disable RTMP authentication. Default: off Possible values: on, off
channel
Description: Encoder channel number
Possible values: 1, 2, 3
feccol
Description: Column count for ProMPEG.
Possible values: integer greater than 1
feconoff
Description: Enable ProMPEG if supported.
Possible values: on, off
fecrow
Description: Row count for ProMPEG.
Possible values: integer greater than 1
filesize
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).
fprefix
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.
storage
Absolute path to mounted media device (e.g. /media/sda1/)
telopcharsize
OSD overlay text character size in pixels
Possible values: 16, 32, or 64
telopenable
Enable or disable telop (i.e. OSD overlay of text).
Possible values: on, off
teloplocation
Where to overlay text in the encoded video
Possible values: top_left top_right top_center bottom_left bottom_right bottom_center
teloptext
Text string for OSD overlay
vgopsize
Description: Distance between I frames (key frames) in GOP sequence
Possible values: 1 through 240
vbitrate
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.
vdelay
Description: Video maximum burst size in milliseconds.
Possible values: 100 to 2000
vdest
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
vframeratediv
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
vgdr
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
vprofile
Description: H.264 profile (see https://en.wikipedia.org/wiki/H.264/MPEG-4_AVC#Profiles for full description)
Possible values: baseline, main, high
vprotocol
Description: Protocol used to transport the encoded bitstream.
Possible values: rtp, rtmp, udp, asi, tsfile, mts, tsrtp
vquality
Description: Set balance between low latency, and higher quality+bitrate compliance.
Possible values: lowlat, balanced, high
vratectrl
Description: Rate control mode for encoder.
Possible values: cbr, vbr
vbr mode may be burstier than cbr.
vres
Description: Video resolution
Possible values: follow_input preserve video source resolution, no resize
WxH resize to width W and height H
vsource
Description: Video input from which encoder will source its video
Possible values: Board-dependent
Transport Stream Parameters
The following parameters only apply to transport stream encoding (transport is set to udp, asi, tsfile, mts, or tsrtp).
vpid
Description: Video PID for transport stream.
Possible values: 32 to 8191 – must not conflict with other PID assignments
apid
Description: Audio PID for transport stream.
Possible values: 32 to 8191 – must not conflict with other PID assignments
pcrpid
Description: PCR PID for transport stream.
Possible values: 32 to 8191 – must not conflict with other PID assignments
pmtpid
Description: PMT PID for transport stream.
Possible values: 16 to 31 – must not conflict with other PID assignments
tsrate
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.
tslowlat
Description: Low latency transport stream mode (VBR).
Possible values: off, on
auxonoff
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.
klvbrate
Description: Bitrate to allocate in transport stream for KLV data.
klvenable
Description: Enable KLV capture from SDI, if supported.
Possible values: off, on
klvpid
Description: PID for KLV data in transport stream
klvsrc
Description: Source device for KLV metadata
pcrinterval
Description: Interval between PCR packets in milliseconds.
Possible values: 30 - 100
Global Configuration
Action Syntax
Generic Actions
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
StartChannel
Transition the encoder channel into the running state.
Once you start the channel, it will not transmit data until the
video input is detected.
StopChannel
Transition the encoder channel into the stopped state.
SaveUser
Save current settings to non-volatile memory, so they will be used on the next startup.
RestartBoard
Reboot the board
CameraControl
Send VISCA commands to camera.
The commands use the same syntax as the serial menu “V” command, as shown below
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))
SaveCamera
Save camera-related settings below.
zoom_direct_value
Description: Set camera zoom
Possible values: 0 (wide) to 0x7ac0 (full zoom)
white_balance_mode
Possible values: auto. indoor, outdoor, onepush, autotrace, manual, outdoor_auto,
sodium_lamp_auto, sodium_lamp_fixed, sodium_lamp_outdoor
color_gain
Possible values: Range from 0 (60%) to 14 (200%)
color_hue
Possible values: Range from 0 (60%) to 14 (200%)
chroma_suppress
Possible values: 0=none, 1, 2, 3
wb_manual_rgain_direct
Possible values: 0 to 255
wb_manual_bgain_direct
Possible values: 0 to 255
optical_zoom_only
Possible values: 0, 1
focus_direct_value
Description: Set manual camera focus distance Possible values: 0x1000 to 0xf000
manual_focus
Description: Set focus mode
Possible values: auto, manual
SetIp
local_ip
IPv4 adresss
local_netmask
IPv4 netmask
default_gw
IPv4 default gateway
local_dnsip
DNS server primary
local dnsip2
DNS server secondary
do_autostart
Control automatic stream start after bootup
Possible values: 1 = do autostart 0 = do not autostart
enc_adv_setting
Control appearance of advanced settings on WebUI
Possible values: off, on
SetDisplay
Controls composite output (passthru video from camera)
disp_std
Set display standard for composite output
Possible values; auto, ntsc, pal
UpdateTerm
Control serial port terminal server for VISCA
term_mode
Possible values: client, server
term_protocol
Possible values: clearchannel, telnet
term_localport
Local TCP port (for server mode)
term_servaddr
Remote IP address (for client mode only)
term_servport
Remote TCP port (for client mode only)
term_baudrate
Possible values: 9600, 19200, 38400, 57600, 115200
term_devicefile
Overlay
Add/Update overlay
chn
Encoder channel to add overlay to.
rgn_idx
Index to map overlay to.
type
Type of overlay to be used possible values: text or png.
source
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.
location
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)
char_size
For text overlay this is the character size. Possible values: 16,32,64
layer
This will set the layer for the overly higher numbers will overlay over lower numbers if overlapping.
alpha
Sets the transparency of the text. Possible values: 0-255
OverlayStop
chn
Encoder channel to remove overlay from.
rgn_idx
Index of overly for this channel.
Dynamic
chn
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
val
Value to set dynamic variable to.
Encoder Actions
SetEncoder
Write encoder settings to active preset. See Python example code for Seting Configuration below
EncoderStatus
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.
StreamStatus
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.
AStreamStatus
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.
SourceStatus
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.
Setting Encoder Configuration
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)
Reading Statistics
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'}
