Standalone VGA Grid User Guide
You are here: Maintenance > Third party integration > Control with HTTP commands

Control with HTTP commands

Standalone VGA Grid has an HTTP API interface for configuration and control by a third party application or with a script that sends commands to the system as a series of URLs. This section covers the following topics:

HTTP command syntax

Control of the Standalone VGA Grid by HTTP is done by sending commands to one of two URLs and specifying the target configuration item. Syntax for the get and set commands follows.

Many commands require a channel or recorder index as an argument. A channel's index is found by looking at the Channels list in the Admin panel. In the screen capture below, the channel with index 1 is currently recording (it's index number is red). To address this channel via http commands, use the index channel1.

For commands requiring a recorder index, determine your recorder's index by combining the recorder's number with the prefix channelm. In the example below, the second recorder's index is 2. To access this recorder via http commands, use the index channelm2.

To Get configuration settings:

http://<address>/admin/channel<N>/get_params.cgi?key

(or for recorders, add 'm' before the recorder number, i.e. channelm1 for recorder 1)
http://<address>/admin/channelm<N>/get_params.cgi?key

To Set configuration settings:

http://<address>/admin/channel<N>/set_params.cgi?key=value

(or for recorders, add 'm' before the recorder number, i.e. channelm1 for recorder 1)
http://<address>/admin/channelm<N>/get_params.cgi?key

Where <address> is the IP address of the system, channel<N> is the channel number (i.e. channel2 for channel number two), channelm2 for recorder two, key is the key for the configuration item being checked or changed (see the list in Configuration keys for third party APIs ), and value is the value to set for the configuration item.

Multiple requests at once

You can include multiple key/value pairs in a single command by separating the statements with &.

For example, the key for product name is product_name and the key for firmware version is firmware_version. To send a request for both the product name and the firmware version, use the following command:

http://<address>/admin/channel1/get_params.cgi?product_name&firmware_version

Or, to turnoff publishing (set to 0) and set the bitrate (vbitrate) to 256,000:

http://<address>/admin/channel1/set_params.cgi?publish_type=0&vbitrate=256K

Third party applications like wget

If you’re using a third party application like wget to send commands to the system, always include the admin username and password when viewing or setting configuration items.

The syntax for wget commands is shown below. Specify your system’s IP address, password and the key(s) or value(s) you wish to query. Note your system may require use of single quotes around the password to handle special characters such as exclamation marks.

get_param using wget:

wget --http-user=admin --http-passwd=<password> http://<address>/admin/channel<N>/get_params.cgi?<key>[&<key>]

set_param using wget:

wget --http-user=admin --http-passwd=<password> http://<address>/admin/channel<N>/set_params.cgi?<key>=<value>[&<key>=<value>]

HTTP command examples

Some configuration of the Standalone VGA Grid can be done by non-interactive http commands. The following examples demonstrate how to use wget to exercise some of the HTTP commands supported by the system.

For values with spaces, encode space as %20. i.e.: set_params.cgi?framesize=640%20x%20480

The examples assume a system IP address of 192.30.23.45 and admin password pass123.

1. To get the type of stream being published and frame size for channel 1:

wget --http-user=admin --http-passwd=pass123 http://192.30.23.45/admin/channel1/get_params.cgi?publish_type&framesize

2. To set the publish stream type to RTMP Push (6) and at the title “System Stream” for channel 2:

wget --http-user=admin --http-passwd=pass123 http://192.30.23.45/admin/channel2/set_params.cgi?publish_type=6&title=System%20Stream

3. To start recording on channel 2:

wget --http-user=admin --http-passwd=pass123 http://192.30.23.45/admin/channel2/set_params.cgi?rec_enabled=on

4. To stop recording on channel 2:

wget --http-user=admin --http-passwd=pass123 http://192.30.23.45/admin/channel2/set_params.cgi?rec_enabled=""

5. To start recording on recorder 2:

wget --http-user=admin --http-passwd=pass123 http://192.30.23.45/admin/channelm2/set_params.cgi?rec_enabled=on

Global variable HTTP command syntax for custom layouts

Your Standalone VGA Grid can create global variables via HTTP for use specifically with custom layout as responsive text overlay elements. See Add a text overlay (custom channel) for more information on adding a global variable into a custom layout.

Important considerations for global custom layout variables
  • Each system variable must have its own unique name
  • System variable names and variable values are case sensitive
  • Each variable must start with a letter or underscore sign and is followed by any combination of letters, digits and underscore characters [A-Za-z_0-9]{0,32} to a limit of 32 total characters (note that saving an empty string to a variable will clear the variable value)
  • There is a limit of 12 total unique system variables per Standalone VGA Grid system
  • System variables can be used in text labels across any number of channels
  • System variable commands can be issued at a frequency of 5 per second, and up to 6 variables may be set in a single command (for example, variables "gpsvar1", "gpsvar2" and "gpsvar3" can be updated in a single command, five times per second). After issuing a set command, all channels using the specified variable(s) are updated. The frequency of commands issued is not influenced by the number of channels on your Standalone VGA Grid system.
  • System variables are considered volatile data and are erased when your Standalone VGA Grid system reboots
Set variables – syntax and example

A set command saves a value to a variable, where <address> is the IP address of the Standalone VGA Grid, name is the unique name for each variable, and value is the text/character content stored in each variable.

You can set multiple variables at the same time by separating each variable with an "&" (as shown within the square brackets in the syntax below).

To "set" variables, use the following syntax:

http://<address>/admin/set_variables.cgi?name1=value1[&nameN=valueN]

For values with spaces, encode space as %20. (i.e.: set_variables.cgi?name1=640%20x%20480)

To erase a previously set variable, simply set the variable's name with an empty space.

Example: "http://192.168.0.129/admin/set_variables.cgi?gpsvar1=N103%2068201%20W765%2029712&gpsvar2=S490%2018731%20E756%2019890&gpsvar3=N123%2046891%20W345%2065431&gpsvar4=S767%2033410%20E770%2004513"

sets:
"gpsvar1" to "N103 68201 W765 29712"
"gpsvar2" to "S490 18731 E756 19890"
"gpsvar3" to "N123 46891 W345 65431"
"gpsvar4" to "S767 33410 E770 04513"

Get variables – syntax and example

A get command returns the value of a variable (called name in the syntax). You can return multiple variables at the same time by separating each variable with an "&" (as shown within the square brackets in the syntax below).

To "get" a variable (or a list of specified variables), use the following syntax:

http://<address>/admin/get_variables.cgi?name1[&nameN]

Example: "http://192.168.0.129/admin/get_variables.cgi?gpsvar1"

returns:
"gpsvar1=N103 68201 W765 29712"

To "get" a list of all variables saved to your Standalone VGA Grid, use the following syntax:

http://<address>/admin/get_variables.cgi

Example: "http://192.168.0.129/admin/get_variables.cgi"

returns:
"gpsvar1=N103 68201 W765 29712
gpsvar2=S490 18731 E756 19890
gpsvar3=N123 46891 W345 65431
gpsvar4=S767 33410 E770 04513"

To learn how to use global variables as text overlays in custom channels, see Add a text overlay (custom channel).

Copyright © 2017 Epiphan Systems Inc.