====== The Server Program ======
<graphviz dot center 500x200>
digraph Overview {
subgraph cluster_0 {
		style=filled;
		color=lightgrey;
		node [style=filled,color=white];
                Server [shape=box];
                ETH [shape=hexagon];
                ATB [shape=hexagon];		
                ETH -> Server;
                Server -> ETH;
                ATB -> Server;
                Server -> ATB;
		label = "Protocol";
	}
        size="12"
        node [shape = box];
        GNSS [shape=hexagon];	
        Mission -> MobotWare;
        GNSS -> MobotWare;
        GNSS -> Server;
        Server -> MobotWare;
        MobotWare -> Server
}
</graphviz>
==== Specs and consideration ====

=== TCP or UDP ===
All data that is transmitted should also be received. If the tractor starts to drive before the cameras are done it will cause error in the images.

Error handling is already implemented in the TCP Protocol. Communication is therefore more secure when using TCP than when using UDP.

There are no Hard Real-Time demands in the communication between the programs, so the time the TCP uses on error handling is not going to be an issue.

The protocol is going to be based on a Socket interface using TCP.

=== Network and IP-range ===
The Network will be a private network using 16-bit IPv4. IP-range on the network will start at 192.168.0.0. The network will be using static IP addresses, the address list is specified below.

The connection between the programs are made with a standard socket on a specified port.

The network is made with a switch
  TrendNet
  10/100 Mbps Fast Ethernet Switch
  Te100-S88Eplus
The network will be tested in January, beacause the current network is also for the [[robots:hako:Navigationcomputer|Navigationcomputer]] and [[robots:hako:Perceptioncomputer|Perceptioncomputer]]. If the 20 Hz data frq has influencen on the current network, the two networks will be seperated.

^ Program              ^ IP-Address  ^ Port        ^
| Server                     | 192.168.0.2  | 51001       |
| ZHAW - Computer            | 192.168.0.52 | Not defined |
| ZHAW - 2D Cam 1            | 192.168.0.53 | Not defined |
| ZHAW - 2D Cam 2            | 192.168.0.54 | Not defined |
| ZHAW - Laserscanner        | 192.168.0.55 | 2112        |
| ATB - LaserScanner (IBEO)  | 192.168.0.5  | 12000       |
| ATB - Computer             | 192.168.0.57 | Not defined |
| UniHo - Trimble AGGps542   | 192.168.0.58 | 5017        |
| UniHo - LaserScanner 1     | 192.168.0.59 | 2111 |
| UniHo - LaserScanner 2     | 192.168.0.60 | 2111 |

If anything is missing please let me know so I can update the list.


=== Protocol ===
The protocol will be based on the XML format((http://www.w3.org/TR/REC-xml/#sec-well-formed)). The server will not transmit an entire xml-document for each update. It will transmit data in XML-format, see example below. 

Most guidelines recommend that data goes in elements, metadata in attributes. This protocol will be compliant with these guidelines((http://www.ibm.com/developerworks/xml/library/x-eleatt/index.html)) .

== Tags & Attributes ==
  <programID>
Is used to indentify each program connected to the server.
  [Program ID]
is the name you chose for your program. The server will use this name for identification. It is stored as a string in the server program. It may contain letters (a-z), numbers (0-9) and spaces ( ). I do not not how Java deals with special charecters (ä,ö,ü,...) so for now they are not allowed.

It will be encoded in ISO-8859-1 (ISO Latin Alphabet No. 1, a.k.a. ISO-LATIN-1) see [[http://docs.oracle.com/javase/1.4.2/docs/api/java/nio/charset/Charset.html|Charset]] documentaion for Javafor further information.

== Detailed description ==
Programs that want to communicate with the server must send this after succesful connecting to the Socket of The Server Program
<sxh xml;>
<programID id="[Program ID]" status="sent" pictureStatus="[true/false]"/>
</sxh>
if the program needs to take a picture, pictureStatus should be true otherwise false.\\
The server will respond with
<sxh xml>
<programID id="[Program ID]" status="received" />
</sxh>
When the server is ready it will send this to the client
<sxh xml>
<programID id="[Program ID]" status="ready" />
<starttime>
	<server-start>[hh:mm:ss.ss]</server-start>
	<gnss-time>[hh:mm:ss.ss]</gnss-time>
</starttime>
</sxh>
when the server has transmitted the <starttime>-tag it will start to send data to the client program in the next 20 Hz program cycle.
This will be sent at 20 Hz to all clients

Latitude and longitude will be given in degrees minutes; 17 15' 30" -> 1715.5
<sxh xml>
<!--Sent from the server-->
<data>
	<position GNSS-Lock="[0-5]">
		<northing coordinateType="UTM">xx</northing>
		<easting coordinateType="UTM">xx</easting>
		<latitude coordinateType="WGS84">xx</latitude>
		<longitude coordinateType="WGS84">xx</longitude>
                <height unit="m">xx</height>
	</position>
	<timestamp>
		<server-time>[hh:mm:ss.ss (server time)]</server-time>
		<gnss-time>[hh:mm:ss.ss (sensor time)]</gnss-time>
	</timestamp>
	<picture>
		<tractor>[moving/stopped]</tractor>
		<takepicture>[false/true]</takepicture>
	</picture>
	<laserscanner>
		<tractor>[moving/stopped]</tractor>
		<startlaser>[false/true]</startlaser>
	</laserscanner>
</data>
</sxh>

When the tractor has stopped and is waiting for the cameras to take their pictures, the server will wait for this command from the clients
<sxh xml>
<picturedone id="[Program ID]" />
</sxh>
There will be a 2 min timeout on this command. So if there is a problem with one of the clients the rest will continue with the mission. If anyone need more than 2 min let me know.

If one of the clientprograms need a break from the data send this to the server
<sxh xml>
<break id="[Program ID]" />
</sxh>
This will stop the data transmission to the client, but the client will still be connected to the server. The sever will respond with
<sxh xml>
<break id="[Program ID]" status="true" />
</sxh>

When the client wants to receive data again send
<sxh xml>
<stopBreak id="[Program ID]" />
</sxh>
The sever will respond with
<sxh xml>
<break id="[Program ID]" status="false" />
</sxh>
and transmit data in the next 20 Hz program cycle.

If the client wants to disconnect from the server send this
<sxh xml>
<disconnect id="[Program ID]" />
</sxh>
The sever will respond with
<sxh xml>
<disconnect id="[Program ID]" status="true" />
</sxh>
and disconnect the client from th socket. The Server Programm will close the socket 1 second after transmitting the last command.

== Download examplefile ==
<file xml protocol.xml>
<!--Sent from the server-->
<data>
	<position GNSS-Quality="[0-5]">
		<northing coordinateType="UTM">xx</northing>
		<easting coordinateType="UTM">xx</easting>
		<latitude coordinateType="WGS84">xx</latitude>
		<longitude coordinateType="WGS84">xx</longitude>
                <height unit="m">xx</height>
	</position>
	<timestamp>
		<server-time>[hh:mm:ss.ss (server time)]</server-time>
		<gnss-time>[hh:mm:ss.ss (sensor time)]</gnss-time>
	</timestamp>
	<picture>
		<tractor>[moving/stopped]</tractor>
		<takepicture>[false/true]</takepicture>
	</picture>
	<laserscanner>
		<tractor>[moving/stopped]</tractor>
		<startlaser>[false/true]</startlaser>
	</laserscanner>
</data>

<!--Sent from the clients-->
<picturedone id="[Program ID]" />
	
<!--when connected to the server sent your program ID to the server-->
<programID id="[Program ID]" status="sent"/>[Promgram ID]</porgramID>

<!--the server will respond with-->
<programID id="[Program ID]" status="[received/ready]" />
<starttime>
	<server-start>[hh:mm:ss.ss]</server-start>
	<gnss-time>[hh:mm:ss.ss]</gnss-time>
<starttime>

<!--If the client program needs a break-->
<break id="[Program ID]" />
<!--the server will respond with-->
<break id="[Program ID]" status="true" />

<!--When the break is over-->
<stopBreak id="[Program ID]" />
<!--the server will respond with-->
<break id="[Program ID]" status="false" />

<!--disconnect the client promgram from the server-->
<disconnect id="[Program ID]" />

</file>

==== The Server Program ====
The program will be developed in Java. It will accept multiple clients.

Each new tag will be sent in a new string. This means that the <data> tag will be sent as one string.
<sxh xml>
<data>
	<position GNSS-Quality="[0-5]">
		<northing coordinateType="UTM">xx</northing>
		<easting coordinateType="UTM">xx</easting>
		<!--these may be omitted in the implementation-->
		<latitude coordinateType="WGS84">xx</latitude>
		<longitude coordinateType="WGS84">xx</longitude>
		<!---------------------------------------------->
	</position>
	<timestamp>
		<server-time>[hh:mm:ss.ss (server time)]</server-time>
		<gnss-time>[hh:mm:ss.ss (sensor time)]</gnss-time>
	</timestamp>
	<picture>
		<tractor>[moving/stopped]</tractor>
		<takepicture>[false/true]</takepicture>
	</picture>
	<laserscanner>
		<tractor>[moving/stopped]</tractor>
		<startlaser>[false/true]</startlaser>
	</laserscanner>
</data>
</sxh>

The <programID> tag will be sent as one string
<sxh xml>
<programID id="[Program ID]" status="ready" />
</sxh>

The <starttime> tag will be sent as one string
<sxh xml>
<starttime>
	<server-start>[hh:mm:ss.ss]</server-start>
	<gnss-time>[hh:mm:ss.ss]</gnss-time>
<starttime>
</sxh>
==== References ====
[[http://www.ibm.com/developerworks/xml/library/x-eleatt/index.html|XML Guidelines]]

[[http://www.w3schools.com/dtd/dtd_el_vs_attr.asp|W3 Schools XML DTD]]

[[http://www.w3schools.com/xml/xml_attributes.asp|W3 Schools XML]]