Table of Contents  MOBOTIX Online Help

The Remote Configuration API

Table of Contents
The Remote Configuration API
Using the Remote Configuration API
Explanation of the HTTP POST Request in the Example
Commands of the Remote Configuration API
Available Commands
Output of the Remote Configuration API
Example: Activating the Microphone
Example: Returning a List of Commands Using help
Example: Changing a Profile Line Using write

The remote configuration API (Application Programming Interface) http://192.168.171.236/admin/remoteconfig provides the methods used for remotely changing configuration parameters directly on the camera.

Using the Remote Configuration API

The camera's HTTP interface processes commands and configuration parameters in an HTTP POST request as in the following example:

POST /admin/remoteconfig HTTP/1.0
Content-type: application/x-www-form-urlencoded
Authorization: Basic YWRtaW46bWVpbnNt
Content-length: 87
helo
view section audio
write params
audio/MICRO=1
view section audio
update
store
quit
 

Explanation of the HTTP POST Request in the Example

Part

Description

 
POST /admin/remoteconfig HTTP/1.0
Content-type: application/x-www-form-urlencoded
Authorization: Basic YWRtaW46bWVpbnNt
Content-length: 87

Header of the HTTP POST Request.

 

Empty line; separates the request's header from its content.

 
helo

Beginning of the command sequence.

 
view section audio
write params
audio/MICRO=1
view section audio
update
store

Command sequence with specific commands, as described in the Commands of the Remote Configuration API section. 

quit
 

End of the command sequence.

Remarks

  • Make sure to close the command sequence with a blank and a line break at the end.

  • The content type (Content-type: application/x-www-form-urlencoded) does not need to be specified, but it is expected by the camera's web server.

  • The web server handles authentication (in this case, Basic authentication is used). User name and password are concatenated by a colon (":") and Base64-encoded. See the line above for the "admin:meinsm" user name and password.

  • The length of the content (Content-length) is the length of the entire data that follows the blank line after the header.

  • The content of the request itself is processed line by line.

  • Note that you need to URL-encode special characters in the parameters, as described in the Command Conventions section of the The HTTP API help page.

This example is discussed in detail in Output of the Remote Configuration API using the cURL command line application.

Commands of the Remote Configuration API

You can use the commands as shown in the following syntax samples:

Available Commands

Command

Description

reset

Resets the entire camera configuration or individual sections thereof to the factory default values.

Keyword

Result

configfile

Resets the entire configuration.

section

Only resets the sections of the configuration that are specified as parameters.

exceptsection

Resets all sections of the configuration except the ones specified as parameters.

restore

Restores the configuration from the copy in Flash storage.

Keyword

Result

configfile

Restores the entire configuration.

section

Only restores the sections of the configuration that are specified as parameters.

delete

Deletes the entire configuration, specific sections or individual parameters.

Keyword

Result

configfile

Deletes the entire configuration.

section

Only deletes the sections of the configuration that are specified as parameters.

params

Only deletes the parameters of the configuration that are specified in the following lines. The parameters for deletion are specified by the section name followed by "/" as separator: 

<section name>/<parameter>

When dealing with profiles, the profile name is expanding the section name, again separated by a "/". 

<section name>/<profile name>/<parameter>

In order to access a profile such as

SECTION ipnotify
profile=ip0:<value> 
ENDSECTION ipnotify

use the following string

ipnotify/ip0/profile

write

Writes entire sections or − when used with the params keyword in front − individual parameters of the configuration.

Keyword

Result

(not specified)

Writes the sections of the configuration that are specified in the following lines. Note that the sections need to be specified with start and end lines: 

SECTION <section name1>
<parameter>=<value> 
<parameter>=<value> 
ENDSECTION <section name1>
SECTION <section name2>
<parameter>=<value> 
ENDSECTION <section name2>

params

Writes the parameters of the configuration that are specified in the following lines. The parameters are specified by the section name followed by "/" as separator: 

<section name>/<parameter>=<value> 

When dealing with profiles, the profile name is expanding the section name, again separated by a "/". 

<section name>/<profile name>/<parameter>=<value> 

In order to access a profile such as

SECTION ipnotify
profile=ip0:<value> 
ENDSECTION ipnotify

use the following string

ipnotify/ip0/profile

Note

Profiles can only be written as a whole. Accessing individual parameters of a profile is not possible.

append

Appends data to configuration sections. The parameters to append to a section are specified line by line between SECTION and ENDSECTION as in the following: 

SECTION <section name>
Parameter=<value>
Parameter=<value>
ENDSECTION <section name>

view

Returns (shows) the entire configuration or specific sections.

Keyword

Result

configfile

Returns the entire configuration.

section

Only returns the sections of the configuration that are specified as parameters.

store

Permanently stores the configuration in the camera's Flash memory.

reboot

Reboots the camera.

update

Applies all changes to the configuration that can be activated without rebooting the camera.

Keyword

Result

all (or without keyword)

Activates all changes.

section

Only applies the changes to the sections that are specified as parameters.

profile

Returns one line with the name of the current configuration profile. This line is empty, if no profile is active.

activate_profile

Activates the configuration profile specified as parameter: activate_profile <profile name>

reboot_needed

Returns all changed configuration sections, which require a reboot before they can be applied. This line is empty, if no change requires a reboot.

Note

After changing the entire configuration (using write, reset, delete or after uploading/editing the configuration from the web interface), the camera does not know if certain configuration sections have been changed. In this case, the command returns the answer "unknown".

exit quit

Identical meaning. Both commands end the preceding command and close the API command sequence. Note that you can only use one of these two commands in a command sequence.

help

Returns a list of available commands (see Returning a List of Commands Using help).

Output of the Remote Configuration API

The camera API returns its answers line by line:

Example: Activating the Microphone

This example demonstrates how to activate the microphone using an HTTP request. For easily testing the remote configuration API, the cURL command line tool (http://curl.haxx.se/download.html) can be downloaded for Windows. It is automatically installed on Mac OS X and most Linux computers.

Using cURL allows quickly and easily testing the commands, since this tool handles the communication with the camera. For example, cURL automatically sends the correct header and calculates the length of the command sequence.

Commands

Description

 
helo
view section audio
write params
audio/MICRO=1
view section audio
update
store
quit
 
 
# Beginning of the command sequence.
# Output the audio section.
# Write the parameter specified in the following line.
# Set the MICRO parameter in the audio section to the value "1".
# Output audio section once more.
# Apply the changes without rebooting.
# Store the configuration in the camera's flash memory.
# End of the command sequence.
 
Step-by-step instruction:

  • Open a command shell (Windows) or a terminal (Mac OS X, Linux).

  • Enter the following command line and replace <user name>, <password> and <IP address> by the actual data of your camera: 

    curl -q -v -u "<user name>:<password>" --data-binary @- "http://<IP address>/admin/remoteconfig"

  • Press the [Return] key; cURL is now waiting for commands.

  • Copy the text block from the left column of the last table from helo to quit.

  • Copy the contents of the clipboard to the command shell or terminal.

  • Press the [Ctrl+D] key combination twice (Windows, Linux) or once (Mac OS X) to send the command sequence to the camera.

Output of the command sequence with the following data:

  • <user name>: admin

  • <password>: meinsm

  • <IP address>: 10.8.0.118

* About to connect() to 10.8.0.118 port 80 (#0)
* Trying 10.8.0.118... connected
* Connected to 10.8.0.118 port 80 (#0)
* Server auth using Basic with user 'admin'
> POST /admin/remoteconfig HTTP/1.1
> Authorization: Basic YWRtaW46bWVpbnNt
> User-Agent: curl/7.18.2 (i486-pc-linux-gnu) libcurl/7.18.2 OpenSSL/0.9.8g zlib/1.2.3.3 libidn/1.8 libssh2/0.18
> Host: 10.8.0.118
> Accept: */*
> Content-Length: 87
> Content-Type: application/x-www-form-urlencoded
>
* HTTP 1.0, assume close after body
< HTTP/1.0 200 OK
< Content-Type: text/plain; charset=utf-8
< Cache-Control: no-cache
<
#read:helo:
#read:view section audio:
#exec cmd=view section audio
SECTION audio
SPEAKER=1
MICRO=0
PREAMPLIFIER=2
SPEAKERLEVEL=0
ENDSECTION audio
#read:write params:
#exec cmd=write params
#read:view section audio:
#exec cmd=view section audio
SECTION audio
SPEAKER=1
MICRO=1
PREAMPLIFIER=2
SPEAKERLEVEL=0
ENDSECTION audio
#read:update:
#exec cmd=update
#updating daemons!
#read:store:
#exec cmd=store
#Storing to flash...
#read:quit:
OK
#bye
* Closing connection #0

Note

Output beginning with a "*", "<" or ">" character is generated by cURL. In the output, ">" precedes the commands sent to the camera, while "<" precedes the messages returned by the camera's web server. The remaining lines are returned by the remote configuration API, as described in the Output of the Remote Configuration API section.

Example: Returning a List of Commands Using help

Commands

Description

 
helo
help
quit
 
 
# Beginning of the command sequence.
# Call the help of the Remote Configuration API
# End of the command sequence.
 
Step-by-step instruction:

  • Open a command shell (Windows) or a terminal (Mac OS X, Linux).

  • Enter the following command line and replace <user name>, <password> and <IP address> by the actual data of your camera: 

    curl -q -v -u "<user name>:<password>" --data-binary @- "http://<IP address>/admin/remoteconfig"

  • Press the [Return] key; cURL is now waiting for commands.

  • Copy the text block from the left column of the last table from helo to quit.

  • Copy the contents of the clipboard to the command shell or terminal.

  • Press the [Ctrl+D] key combination twice to send the command sequence to the camera.

Output of the command sequence with the following data:

  • <user name>: admin

  • <password>: meinsm

  • <IP address>: 10.8.0.118 

* About to connect() to 10.8.0.118 port 80 (#0)
* Trying 10.8.0.118... connected
* Connected to 10.8.0.118 port 80 (#0)
* Server auth using Basic with user 'admin'
> POST /admin/remoteconfig HTTP/1.1
> Authorization: Basic YWRtaW46bWVpbnNt
> User-Agent: curl/7.18.2 (i486-pc-linux-gnu) libcurl/7.18.2 OpenSSL/0.9.8g zlib/1.2.3.3 libidn/1.8 libssh2/0.18
> Host: 10.8.0.118
> Accept: */*
> Content-Length: 87
> Content-Type: application/x-www-form-urlencoded
>
* HTTP 1.0, assume close after body
< HTTP/1.0 200 OK
< Content-Type: text/plain; charset=utf-8
< Cache-Control: no-cache
<
#read:helo:
#read:help:
The following commands are currently implemented:
append
reboot_needed
view
reboot
write
profile
restore
activate_profile
reset
update
delete
store
exit
quit
help
#read:quit:
OK
#bye
* Closing connection #0

Note

Output beginning with a "*", "<" or ">" character is generated by cURL. In the output, ">" precedes the commands sent to the camera, while "<" precedes the messages returned by the camera's web server. The remaining lines are returned by the remote configuration API, as described in the Output of the Remote Configuration API section.

Example: Changing a Profile Line Using write

The ipnotifyaddress target address of the network message profile ip0 in the ipnotify configuration section is to be changed from 10.0.0.42:8000 to 10.11.12.13:6750.

Note

Make sure that you always need to write the entire profile line. It is not possible to change individual values within a profile.

Commands

Description

 
helo
view section ipnotify
write params
ipnotify/ip0/profile=ip0:_profilename=MxCC-Alarm
:preset=mxpeg_alarm:ackn_time=60
:ipnotifyaddress=10.11.12.13%3A6750
:send=on_error:protocol=raw
:boundary=--next-image--:httppath=:httpauth=
:data=msg:ipnotifymessage=Hello World!
:filetype=mxg:rate100=100:antetime=1
:posttime=1:systime=1440:ipnotifyport=0
view section ipnotify
update
store
quit
 
 
# Beginning of the command sequence.
# Output the ipnotify section.
# Write the profile specified in the following line.
# Set profile ip0 in section ipnotify with the address
# "10.11.12.13" and the port 6750 ...
# ...
# ...
# ...
# ...
# ...
# ...
# Again output the ipnotify section.
# Apply the changes without rebooting.
# Store the configuration in the camera's flash memory.
# End of the command sequence.
 
Step-by-step instruction:

  • Open a command shell (Windows) or a terminal (Mac OS X, Linux).

  • Enter the following command line and replace <user name>, <password> and <IP address> by the actual data of your camera: 

    curl -q -v -u "<user name>:<password>" --data-binary @- "http://<IP address>/admin/remoteconfig"

  • Press the [Return] key; cURL is now waiting for commands.

  • Copy the text block from the left column of the last table from helo to quit.

  • Copy the contents of the clipboard to the command shell or terminal.

  • Press the [Ctrl+D] key combination twice to send the command sequence to the camera.

Output of the command sequence with the following data:

  • <user name>: admin

  • <password>: meinsm

  • <IP address>: 10.8.0.118 

* About to connect() to 10.8.0.118 port 80 (#0)
* Trying 10.8.0.118... connected
* Connected to 10.8.0.118 port 80 (#0)
* Server auth using Basic with user 'admin'
> POST /admin/remoteconfig HTTP/1.1
> Authorization: Basic YWRtaW46bWVpbnNt
> User-Agent: curl/7.18.2 (i486-pc-linux-gnu) libcurl/7.18.2 OpenSSL/0.9.8g zlib/1.2.3.3 libidn/1.8 libssh2/0.18
> Host: 10.8.0.118
> Accept: */*
> Content-Length: 87
> Content-Type: application/x-www-form-urlencoded
>
* HTTP 1.0, assume close after body
< HTTP/1.0 200 OK
< Content-Type: text/plain; charset=utf-8
< Cache-Control: no-cache
<
#read:helo:
#read:view section ipnotify:
#exec cmd=view section ipnotify
SECTION ipnotify
ipnotify/ip0/profile=ip0:_profilename=MxCC-Alarm
:preset=mxpeg_alarm:ackn_time=60
:ipnotifyaddress=10.0.0.42%3A8000
:send=on_error:protocol=raw
:boundary=--next-image--:httppath=:httpauth=
:data=msg:ipnotifymessage=Hello World!
:filetype=mxg:rate100=100:antetime=1
:posttime=1:systime=1440:ipnotifyport=0
...
ENDSECTION ipnotify
#read:write params:
#exec cmd=write params
#read:view section ipnotify:
#exec cmd=view section ipnotify
SECTION ipnotify
ipnotify/ip0/profile=ip0:_profilename=MxCC-Alarm
:preset=mxpeg_alarm:ackn_time=60
:ipnotifyaddress= 10.11.12.13%3A6750
:send=on_error:protocol=raw
:boundary=--next-image--:httppath=:httpauth=
:data=msg:ipnotifymessage=Hello World!
:filetype=mxg:rate100=100:antetime=1
:posttime=1:systime=1440:ipnotifyport=0
...
ENDSECTION ipnotify
#read:update:
#exec cmd=update
#updating daemons!
#read:store:
#exec cmd=store
#Storing to flash...
#read:quit:
OK
#bye
* Closing connection 0

Note

Output beginning with a "*", "<" or ">" character is generated by cURL. In the output, ">" precedes the commands sent to the camera, while "<" precedes the messages returned by the camera's web server. The remaining lines are returned by the remote configuration API, as described in the Output of the Remote Configuration API section.

© 2001-2024 MOBOTIX · https://www.mobotix.com