Bosch Video IP
RCP+ over CGI
www.boschsecurity.com
Overview
1.1
Reading parameters
Bosch IP Video products in video management system
Various parameters can be read from a Bosch IP video
environments are mainly controlled and managed using
product, e.g. the hardware or firmware version, the
an enhanced version of Remote Control Protocol, RCP+,
name of the camera(s), or the CPU performance values.
pronounced RCP plus. This protocol defines com-
To check our Dinion IPs encoder load, part of the values
mands and messages that allow to configure the units
displayed with the performance bar in the web browser,
and to establish communication between units, or units
the URL must look like:
and management systems.
HTTP://160.10.0.1/rcp.xml?command=0x0a07
&type=T_DWORD&direction=READ&num=1
Since firmware version 3.0, RCP+ commands can be encapsulated into CGI requests. The command structure of
The return value provides a recent snapshot value of the
RCP+ must be translated into parameters and values
CPU performance required for encoding video. The web
handed over to the units XML-based CGI interpreter as
browser is able to display the returned XML message in
a query string. Using HTTP as transportation protocol,
a readable format.
e.g. with a Web browser, an URL may look like:
The return value is presented in the <result> section and
HTTP://160.10.0.1/rcp.xml?<<query_string>>
in this example shows a value of 51 %.
Each RCP+ command is a fixed predefined 16 bit value
The XML return message is displayed in the web browser
followed by a structured set of parameters, some man-
like this:
datory, some optional. The RCP+ command and the
required structure can be taken from the RCP+ documentation. All message elements in the query string
must resemble an appropriate pair of parameter and
value. The following examples shall give a principle overview of how to use RCP+ commands with CGI.
<rcp>
<command>
<hex>0x0a07</hex>
<dec>2567</dec>
</command>
<type>T_DWORD</type>
The following examples assume having installed a Dinion
<direction>READ</direction>
IP camera at IP address 160.10.0.1.
<num>1</num>
The <<query_string>> syntax and valid parameters are
<idstring />
described in section 2.
<payload />
<cltid>0xd2f9</cltid>
<auth>2</auth>
<result>
<hex>0x00000033</hex>
<dec>51</dec>
</result>
</rcp>
2 | RCP+ over CGI
The return message displayed in the web browser also
1.2
contains unused and optional parameters that are repre-
Writing parameters
RCP+ over CGI can also be used to change the various
sented by an empty XML tag in the form of
parameters of a Bosch IP Video product, e.g. the device
<xmltag />
name or the relay state. Parameter writing or setting is
(e.g. <idstring /> or <payload/> in the example above).
done in a similar way like reading them. Except the direc-
These may be disregarded.
tion tag is set to WRITE instead of READ and a payload
To check our Dinion IPs camera name the URL must look
has to be specified. To set the state of the first (num=1)
like:
relay of our Dinion IP to 0 (payload=0x0; = off) the URL
must look like:
HTTP://160.10.0.1/rcp.xml?command=0x0019
&type=P_UNICODE&direction=READ&num=1
http://160.10.0.1/rcp.xml?command=0x01c1
&type=F_FLAG&direction=WRITE&num=1
&payload=0x0
The XML return message is displayed in the web browser
like this:
The XML return message is displayed in the web browser
<rcp>
like this:
<command>
<rcp>
<hex>0x0019</hex>
<command>
<dec>25</dec>
<hex>0x01c1</hex>
</command>
<dec>449</dec>
<type>P_UNICODE</type>
</command>
<direction>READ</direction>
<type>F_FLAG</type>
<num>1</num>
<direction>WRITE</direction>
<idstring />
<num>1</num>
<payload />
<idstring/>
<cltid>0xd82d</cltid>
<payload/>
<auth>2</auth>
<cltid>0x4d2d</cltid>
<result>
<sessionid>0x00000000</sessionid>
<str>00 43 00 61 00 6d 00 65 00 72 00 61
<auth>2</auth>
00 20 00 31 00 00</str>
<protocol>TCP</protocol>
</result>
<result>
</rcp>
<hex>0x00</hex>
<dec>0</dec>
The camera name as return value is coded in Unicode
</result>
which is not clearly visible to humans but easily inter-
</rcp>
preted by a computer. The Unicode string in this example resembles the string Camera 1.
STDN/SPP
2012-10
www.boschsecurity.com
RCP+ over CGI | 3
CGI <<query_string>>
reference
2.1.4
Parameter num
The numeric descriptor parameter. This parameter is
mandatory for certain RCP+ commands.
As described and shown in section 1, the CGI query
string consist of different parameter, value pairs. The pa-
Values:
rameters and their possible values are described in the
The numeric descriptor.
following sections. Some of them are mandatory, some
of them are optional. First the mandatory parameters are
2.1.5
Parameter payload
described, followed by the optional ones.
The payload for a specific RCP+ command. The payload
structure is depending on the commands payload type
2.1
Mandatory parameters
as described above.
2.1.1
Parameter command
Values:
This is the most important part of the CGI request and
The payload as readable string for payload type P_STRING
represents the RCP+ command tag.
The payload as octet array with no spaces preceded with
0x for payload type P_OCTET and P_UNICODE
Values:
The payload value in hex or decimal notion for all other
RCP+ command tag value.
payload types.
2.1.2
Parameter type
The payload type for a specific RCP+ command tag.
2.2
Optional CGI parameters
Values:
2.2.1
Parameter idstring
F_FLAG
Values:
T_OCTET
User defined parameter which will not be processed by the
unit; will return unchanged in the reply.
T_WORD
T_INT
2.2.2
Parameter sessionid
T_DWORD
Values:
P_OCTET
Context specific session ID for this command
P_STRING
P_UNICODE
2.1.3
Parameter direction
Defines, whether the call is getting or setting the parameter in question.
Values:
READ
WRITE
www.boschsecurity.com
2012-10
STDN/SPP
4 | RCP+ over CGI
2.3
The XML return message is displayed in the web browser
Message handling
like this:
RCP+ messages will be processed and received by the
<message_list>
CGI client using a poll mechanism.
<stats>
A CGI command with the requested messages command
<msgcnt>2</msgcnt>
tag values needs to be issued. After issuing a request,
<over>0</over>
the reply returns immediately after a message has been
<clip>0</clip>
sent or the default timeout of 1000 ms has been expired.
<poll>1</poll>
When the timeout expires, a message count of 0 is re-
</stats>
turned. Otherwise the number of received messages is
<cltid>0x002a</cltid>
signaled. The default timeout can be altered by setting
<msg>
the collectms CGI value to the appropriate number of
<no>1</no>
milliseconds.
<command>0xffcc</command>
A parameter description can be found below.
<num>0</num>
<sessionID>0x7063001f</sessionID>
2.3.1
Parameter message
<hex>0xa00a0034000000000
101000001010001</hex>
Values:
</msg>
One or a list of requested message RCP+ command tag val-
<msg>
ues separated by $
2.3.2
<no>2</no>
<command>0xffcc</command>
Parameter collectms
<num>0</num>
Values:
<sessionID>0x70630020</sessionID>
Time in milliseconds to collect messages before returning
<hex>0xa00a0034000000000
101000001010001</hex>
with No messages
</msg>
Default is 1000 ms.
</message_list>
The <msgcnt> section contains the number of valid
<msg> sections inside the reply.
2.3.3
Message reply
A buffer mechanism (depth 64) ensures that no messages will be lost during two consecutive poll cycles. The
<over> section represents the number of lost messages.
The <clip> value that the internal buffers were too small;
this should never occur. The <poll> section counts the
number of issued poll requests.
A sample request to receive all connection related messages (CONF_CONNECT_TO) will look like:
HTTP://160.10.0.1/rcp.xml?message=0xffcc
&collectms=5000
STDN/SPP
2012-10
www.boschsecurity.com
RCP+ over CGI | 5
Authentication
The RCP+ server need proper authentication to process
protected commands. The CGI interface provides three
basic authentication schemes to be used.
3.1
Using http authentication
In this case, HTTP header authentication (basic or digest) must be present in the request. The internal HTTP
server will pass the login information to the RCP+ server.
3.2
Using session cookie
For each successful HTTP authentication (for all available resources like html pages, images ) a session
cookie will be returned by the HTTP server. When this
cookie is present in any further HTTP connections, the
same authorization level will be granted as in the originating connection. The session cookie will remain active
as long as at least one HTTP connection remains open. In
this case the internal HTTP server will pass the login information to the RCP+ server.
3.3
CGI inline
By passing the CGI parameter pwd with a value
of the identification string as defined in the
CONF_RCP_CLIENT_REGISTRATION section for normal
method. This information will be directly passed to
the RCP+ server for validation.
www.boschsecurity.com
2012-10
STDN/SPP