DevGuide/Server GCS com

The communication between the server and the GCS is based on the Ivy middleware as described in the system overview.
The mechanism described below apply mainly to the Ocaml library provided by paparazzi (sw/lib/ocaml/pprz.ml*), even if the basic send/bind functions of Ivy can be used directly in C programs.
= How Ivy is used =
== Normal bind/send mechanism ==
Ivy is based on message subscription (based on regular expression):
* the bind function takes two parameters: a regular expression and a callback function.
* the send function sends strings and is used like the 'printf' C function.
when someone has a message to send that is matching the regular expression of one or more bind, it will trigger the associated callback with the string as a parameter.
== Advanced request mechanism ==
In order to let a agent ask for some information, a answer/request mechanism has been integrated using the normal bind/send mechanism.
* the answerer function takes a message name (ex: MSG_NAME) and a callback function as parameters
** it binds to MSG_NAME_REQ messages
** it sends back a MSG_NAME message when the MSG_NAME_REQ callback is triggered
* the request function takes a message name (ex: MSG_NAME), a callback function and some values as parameters
** it binds to MSG_NAME message with the callback function given as parameter
** it sends a MSG_NAME_REQ message with the values given as parameters
** after receiving the reply from the answer and applying the callback function to the returned values, it unbinds from the message MSG_NAME
= Format of messages =
The messages used in paparazzi are described in the file conf/messages.xml. Most of the messages used by the GCS or the server are from the class ground. Each message is composed of:
* a unique name (among all the messages)
* a unique ID (among its class)
* a list of fields with a name and a type
In the following subsections, anything means that a field can match any string that doesn't have whitespace, anything... means that the field can contain several or none anything separated by whitespace.
== Normal format ==
The normal format of the message when using the send function:
 [timestamp] sender_name msg_name anything...
timestamp is optional, default is false.
The normal bind function looks for messages of the form:
 [timestamp or nothing] sender_name msg_name anything... when a sender name is given as a parameter
 [timestamp or nothing] anything msg_name anything... else
This allow to receive the messages coming from a given sender or from anyone.
== Advanced format ==
When using the answer/request mechanism a unique request ID is added to the normal format. The format of this ID is pid_index. The Unix Process ID (pid) is unique for each running program, the index is incremented at each request. There is no timestamp.
The request send format:
 sender_name request_id msg_name_REQ anything...
The request bind format:
 request_id anything msg_name anything...
The answerer send format:
 request_id sender_name msg_name anything...
The answerer bind format:
 anything anything msg_name_REQ anything...
= Server <-> GCS communication =
== Server ==
The server sends synthetic messages based on the telemetry data received from the UAVs (normal period is 500ms, 1s for alarms, 5s for WIND):
* NEW_AIRCRAFT (when a telemetry message ALIVE is received (and correct) for the first time)
* FLIGHT_PARAM
* NAV_STATUS
* ENGINE_STATUS
* AP_STATUS
* FLY_BY_WIRE
* DL_VALUES
* WAYPOINT_MOVED
* CAM_STATUS
* CIRCLE_STATUS
* SEGMENT_STATUS
* SURVEY_STATUS
* WIND
* TELEMETRY_STATUS
* TELEMETRY_ERROR
* BAT_LOW (trigger alarm)
* AIRPROX (alarm but not used anymore)
It answer to some requests:
* AIRCRAFTS (sends the list of all running aircraft known by the server)
* CONFIG (sends the configuration of a given aircraft)
It binds to:
* MOVE_WAYPOINT
* DL_SETTING
* GET_DL_SETTING
* JUMP_TO_BLOCK
* RAW_DATALINK
* WIND_CLEAR
* all messages of the class telemetry
== GCS ==
The GCS binds to all the messages sent by the server (except AIRPROX). It also binds the the messages TCAS_TA, TCAS_RA and DC_SHOT, which are direct telemetry messages.
It sends messages:
* MOVE_WAYPOINT
* DL_SETTING
* GET_DL_SETTING
* JUMP_TO_BLOCK
* RAW_DATALINK
It can request for CONFIG and AIRCRAFTS.
== Initialization sequence ==
When the server starts, the initialization is as follow:
* bind to ALIVE message and send a NEW_AIRCRAFT message when the callback is triggered
* bind to the messages sent by the GCS
* set answerer for AIRCRAFTS and CONFIG
When the GCS starts, the initialization is as follow:
* send request for AIRCRAFTS
** when the callback function is triggered with the list of working aircraft, send requests CONFIG for each of them
* bind to NEW_AIRCRAFT
** when the callback function is triggered with a new aircraft, send request CONFIG for it
* bind to messages sent by the server + some extra messages
The result is that the GCS asks for the aircraft already known by the server and then receives new aircraft as they appear.
Category:Software Category:Developer_Documentation