User Tools

Site Tools


remoteprotocolgeneral

Remote Protocol

A V-Control system that offers its service via network or RS232 communication is called a node. Via this service, nodes can communicate with other nodes or applications. The service give access to the tasks and attached devices. V-Control services are available via TCP, UDP, RS232 and, thanks to the build in webserver, HTTP. The communication protocol for TCP, UDP and RS232 connections is the same, the HTTP protocol differs a little.

To enable one or more of the services, see the Program Preferences chapter.

TCP, UDP and RS232 Message Format

Start of Transmission MSG Type (as string) Separator CMD ( as string) Separator Parameter (as string) End of Transmission
Chr(4)0=command 1=result 2=event 3=ProgressMSGchr(5)command stringchr(5)strings separated by chr(2)Chr(6)

Websocket Message Format

There are two valid ways to control V-Control via web interface. The first one is to use a link in the page such as <a href=“cgi-bin/scrRunTask%05AllLightsOff” target=“ack”>All LightsOff</a>. This is very convinient if a simple GUI is needed. For complex, self updating GUIs the best solution is to use Websockets. The built in V-Control web server supports websockets from version 3.8 and later.

Start of Transmission MSG Type (as string) Separator CMD ( as string) Separator Parameter (as string) End of Transmission
%040=command 1=result 2=event 3=ProgressMSG%05command string%05strings separated by %02%06

Start of Transmission

The beginning of a new message is always $H04 or ASCII Code 4. If used in http protocol, this the “/cgi-bin/” string is used instead (see Examples).

Msg Type

ID Description
0 Command, a message was sent from the client to the Server (V-Control).
1 Result, this message contain the result of a client's request. The Data is stored in the Parameter Field.
2 Event, the server sent a message without a leading client request.
3 ProgressMSG, the server sent a message that contain a progress status

Separator

The ASCII code 5 ($H05 in hex.) separates the individual parts of the message. If using http, the separator is the string “%05”.

CMD

The Command sent to the server.

Parameter

Parameters used by the command (optional in some cases)

End of Transmission

The end of a message is always $H06 or ASCII Code

Web Interface

The connection from the html page to a task or command is made by a link. Usually, a link is used to navigate to another web page. Clicking on a link opens a new browser window, or replaces the current windows content with the linked page. But if we make a link to a task, there is no web page returned (and we do not want this). The task is launched and the return is only an acknowledge, saying that the task is executed or not. So we have to take care that the acknowledge message is not replacing our current browser content. One solution is to work with frames.

Frames divide a web page into two or more sections. In this example, we have 2 sections (frames). The ack frame is a located at the bottom with 30 pixel height, the main frame uses the remaining space at the top of the ack frame. The frame definition is done in the file index.html, located in V-Control httpRoot folder. index.html is the page that is shown if you type the V-Control web server url in your browser (i.e. http://192.168.1.45:8080). The listing below shows the content of index.html.

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Frameset//EN"
"http://www.w3.org/TR/html4/frameset.dtd">
<html>
<head>
<title>V-Control Web Example</title>
</head>
<frameset rows="*,30">
<frame src="main.html" name="main">
<frame src="ack.html" name="ack">
<noframes>
 <body>


 </body>
</noframes>
</frameset>
</html>

The definition of the two frames is done by <frameset rows=“*,30”>, saying that the bottom frame is using 30 pixel, and the top frame the remaining space. Then, the top frame is linked to the file main.html, and its name is set to “main”. The bottom frame is linked to ack.html and its name is set to ack. Via this name, the frame is accessible as target for a link. The page (file) main.html can contain a link to a task, and set the target for this link to ack.

<a href=“cgi-bin/scrRunTask%05AllLightsOff” target=“ack”>All LightsOff</a>

The link refers to the directory cgi-bin, which is a virtual directory. All links to this directory are interpreted as command. A task with the name “AllLightsOff” is called. Notice that the target is set to ack. The browser will show the result of the command in the frame ack. The “%05” is used as separator between the command (scrRunTask) and the parameter (AllLightsOff). If a command has more than one parameter, the parameters are separated by “%02”.

If you like more information about html coding have a look at http://www.htmlcodetutorial.com and http://www.w3schools.com .

HTTP Message Format

Start of Transmission CMD ( as string) Separator Parameter (as string)
/cgi-bin/ command string %05 strings separated by %02
remoteprotocolgeneral.txt · Last modified: 2013/10/23 09:45 by admin