About HTTP/HTTPS commands
Your Pearl system has an HTTP API interface. You can swap the HTTP for HTTPS in the URL without affecting the API commands. The HTTP/HTTPS API is used for configuration and control by third party applications or scripts that send commands as a series of URLs. Commands are sent to one of two URLs and specify the target configuration item.
Some commands require a channel or recorder name as an argument. A channel's index is found by looking at the Channels list in the . In the following example, the channel with index 1 is currently recording (its index number is red). To address this channel using HTTP commands, use the index channel1.
Since Pearl Nano is a single-channel encoder, the channel index number is always 1.
For recorders, combine the recorder's number with the prefix m, as in channelm. In the following example, the second recorder's index is 2. To access this recorder using http commands, use the index channelm2.
Sample Get configuration settings:
http://<address>/admin/channel<N>/get_params.cgi?key
or
https://<address>/admin/channel<N>/get_params.cgi?key
For recorders, add 'm' before the recorder number (i.e. channelm1 for recorder 1), for example:
http://<address>/admin/channelm<N>/get_params.cgi?key
Sample Set configuration settings:
http://<address>/admin/channel<N>/set_params.cgi?key=value
or
https://<address>/admin/channel<N>/set_params.cgi?key=value
For recorders, add 'm' before the recorder number (i.e. channelm1 for recorder 1), for example:
http://<address>/admin/channelm<N>/set_params.cgi?key
Where <address> is the IP address of the Pearl system, channel<N> is the channel number (i.e. channel2 for channel number two), and channelm<N> is for recorders (i.e. channelm2 for recorder two), key is the configuration key for the item being checked or changed (see Configuration keys for third party APIs), and value is the value to set for the configuration item.
The following examples show how to use wget to exercise some of the supported HTTP/HTTPS commands. You can substitute https for http in the urls.
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 is pass123.
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
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
To start recording on channel 1:
wget --http-user=admin --http-passwd=pass123 http://192.30.23.45/admin/channel1/set_params.cgi?rec_enabled=on
To stop recording on channel 1:
wget --http-user=admin --http-passwd=pass123 http://192.30.23.45/admin/channel1/set_params.cgi?rec_enabled=""
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
Pearl Nano doesn't support multiple channels, multiple layouts, recorders, touch screen, and the Motion JPEG codec. Commands related to these are either ignored (for example, you cannot delete the channel or create a new layout on Pearl Nano), or applied to only a single target item, such as the single channel or layout on Pearl Nano.
Multiple requests
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.
The command to request both the product name and the firmware version is:
http://<address>/admin/channel1/get_params.cgi?product_name&firmware_version
To turn off publishing (i.e. set to 0) and set the bitrate (vbitrate) to 256,000:
http://<address>/admin/channel1/set_params.cgi?publish_type=0&vbitrate=256K
You can substitute https for http in the urls.
Third party applications like wget
If you’re using a third party application like wget to send commands to your Pearl system, always include the admin username and password when viewing or setting configuration items.
Specify your Pearl system’s IP address, password and the key(s) or value(s) you want to query using the following syntax. Note that your system may require use of single quotes around the password to handle special characters such as exclamation marks. You can substitute https for http in the urls.
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>]
Where <address> is the IP address of the Pearl system, channel<N> is the channel number (i.e. channel2 for channel number two), key is the configuration key for the item being checked or changed (see Configuration keys for third party APIs), and value is the value to set for the configuration item.
Global variable HTTP commands for custom layouts
Pearl-2 can create global variables using HTTP commands embedded in a custom layout as responsive text overlay elements. For information about text overlays and adding a global variables to a custom layout, see the user guide for your Pearl system. You cannot substitute https for http in the global variable HTTP commands.
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 name 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 1024 total unique system variables per 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 Pearl system.
- System variables are considered volatile data and are erased when your Pearl system reboots.
Set variables – syntax and example
A set command saves a value to a variable, where <address> is the IP address of the Pearl system, 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 "&".
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. You can return multiple variables at the same time by separating each variable with an "&".
To "get" a variable or a list of specific variablesx:
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 the Pearl system:
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"
