Difference between revisions of "DevGuide/Communications"

From PaparazziUAV
Jump to navigation Jump to search
 
(28 intermediate revisions by 10 users not shown)
Line 1: Line 1:
This page describes the way the communications with the aircrafts are implemented in paparazzi
{{cleanup|Outdated information.}}


We'll start with high level stuff such as sending your own telemtry message or uplink message. We'll then look at the lower layers
== Introduction ==
== sending telemetry message ==
This page describes the way the communications with the aircrafts are implemented in Paparazzi.


We'll start with high level stuff such as sending your own telemetry message or datalink (uplink) message. We'll then look at the lower layers


describe your message in the telemetry section in conf/messages.xml
== Sending telemetry message ==


this should looks like this  
Define the message you would like to have send in the telemetry section in <tt>conf/messages.xml</tt>
 
This should look like this  
   
   
  <message name="MARK" id="32">
  <message name="MARK" id="32">
Line 13: Line 16:
   <field name="lat" type="float" unit="deg"/>
   <field name="lat" type="float" unit="deg"/>
   <field name="long" type="float" unit="deg"/>
   <field name="long" type="float" unit="deg"/>
  <field name="alt" type="uint32" unit="mm" alt_unit="m" alt_unit_coef="1000"/>
  </message>
  </message>


the id has to be unique
The '''id''' has to be unique. The fields can have type '''int8''', '''int16''', '''int32''', '''uint8''', '''uint16''', '''uint32''', '''float''' and arrays of those. They must be aligned on a multiple of their size (c.f. examples with ''pad'' fields).
the fields can have type int8, int16, int32, uint8, uint16, uint32, float and arrays of those
 
The '''alt_unit''' and '''alt_unit_coef''' will be used the [[RTPlotter|Plotter]] and the [[Messages|Messages]] agents to display human readable values.
When '''alt_unit_coef''' is not specified, some basic default conversions are automatic:
* deg <-> rad
* deg/s <-> rad/s
* m <-> cm
* m/s <-> cm/s
* decideg -> deg
 
This enables all the ground system to deal with your message and generate sending code for the airborne system. The code is generated in <tt>var/include/messages.h</tt>.


they must be aligned in order to work on arm7 ( write more on that )
==== TIP: ====


this enable all the ground system to deal with your message and generate some code for the airborne system
Ofcourse one can make a capitalized subdirectory in the ''conf'' directory e.g. a directory called ''MYUSERID'' where you save your personal messages defined XML document with a name like "myuserid_minimal_telemetry_messages.xml" and make a symbolic link to this file via "cd ~/paparazzi/conf/ && mv -v message.xml org.messages.xml && ln -s ./MYUSERID/myuserid_minimal_telemetry_messages.xml messages.xml"
the generated code is in var/include/messages.h


from the airborne code you can send the message by using this code, for example
Note that '''after changing''' your myuserid_minimal_telemetry_messages.xml, one '''always''' must perform a ~/paparazzi/make . This makes sure a refreshed ''message.h'' is generated in the ''~/paparazzi/var'' directory. This file will then be compiled and linked into your autopilot airborne executable.
DOWNLINK_SEND_MARK(&ant_v2x_data.xraw, &ant_v2x_data.yraw, \
                  &ant_v2x_data.xcal, &ant_v2x_data.ycal, \
                  &ant_v2x_data.heading, &ant_v2x_data.magnitude, \
                  &ant_v2x_data.temp, &ant_v2x_data.distor, \
                  &ant_v2x_data.cal_status);


you can alos have the autopilot send it periodically
===Messages Format===
in your telemetry file ( for example conf/telemetry/default.xml you can make your own it is referenced in the airframe file)
you can add a line like
<message name="CALIB_START"    period="1"/>


meaning that CALIB_START will be sent every second
Detail to be found here
[[Messages_Format]]


you can have different modes
=== Airborne ===


when sent by the aircraft the message will be available on the ground ivy bus
From the airborne code you can send the message by using DOWNLINK_SEND_XYZ.


you can watch it using the messages program or with ivyprobe
For '''example''' the MARK message:


the file sw/ground_segment/cockpit/ant_track.c shows how to receive a message in a C program
DOWNLINK_SEND_MARK(DefaultChannel, &mark_id, &mark_lat, &mark_long, &mark_alt);
for ocaml, we have a higher level library to receive messages
 
The first parameter of the DOWNLINK_SEND_XYZ macro is the channel you want to send it over, in most cases you want to use the DefaultChannel.
You can also have the autopilot send the message '''periodically'''.
 
To make that happen, in your telemetry XML document,for example <tt>conf/telemetry/MYUSERID/myuserid_new_telemetry_test.xml</tt>, you can make your own. Make sure the airframe also uses this file. In the [[conf.xml|<tt>conf/conf.xml</tt>]] file). You can add a line like
<message name="MARK" period="1.4"/>


meaning that '''MARK''' will be sent every 1.4 seconds. You then need to specify the arguments to your message in the <tt>sw/airborne/firmwares/fixedwing/ap_downlink.h</tt> or <tt>sw/airborne/firmwares/rotorcraft/telemetry.h</tt> header by providing a macro


== adding datalink ( uplink ) messages ==
#define PERIODIC_SEND_MARK() DOWNLINK_SEND_MARK(DefaultChannel, &mark_id, &mark_lat, &mark_long, &mark_alt)


You can have different telemetry modes having different rates for each message. For example you might want a verbose mode and a low bandwith mode.


this is similar to the above
=== On the IVY bus ===


add you message in the datalink section of messages.xml
After the data is sent by the aircraft the message will be available on the ground IVY bus. You can monitor you message values using the '''Messages''' program in the tools menu of the Paparazzi Center. One can also use the <tt>ivyprobe</tt> command line ( <tt>ivyprobe '(.*)'</tt> to debug passing messages).


this will generate parsing code for the airborne program
The file <tt>sw/ground_segment/cockpit/ant_track.c</tt> is a good example that shows how to receive a message in a C program. In the <tt>sw/ground_segment/tmtc</tt> are even some more examples ( <tt>c_ivy_client_example*.c</tt> ).
For OCAML, there is a higher level library to receive messages (<tt>sw/lib/ocaml/pprz.ml</tt>). If you are using Python take a look in <tt>/sw/ground_segment/python/</tt> directory for example


you can add your handler in the sw/airborne/datalink.c code ( must find a way to include external code in that )
== Adding datalink (uplink) messages ==


or you can just rewrite your own dl_parse_msg() function, for exzample in a test program where you want to receive only your own messages
This is similar to the above. Add your message in the <tt>datalink</tt> section of <tt>messages.xml</tt>
This will generate parsing code for the airborne program (<tt>var/include/dl_protocol.h</tt>).


There are several possibilities to parse the uplink messages:
# add your handler in the <tt>sw/airborne/firmwares/fixedwing/datalink.c</tt> or <tt>sw/airborne/firmwares/rotorcraft/datalink.c</tt> code
# use a [[Modules|module]] with a <tt>datalink</tt> node where you specify the message to be parsed and the function to be called when the messages arrives
# or you can just rewrite your own <tt>dl_parse_msg()</tt> function, for example in a test program where you want to receive only your own messages.


== The "transport" layer ==


== The "transport" layer
Paparazzi can use the built-in transport layer of different hardware (currently only wavecards and xbee/xtends) and also provides his own layer for hardware lacking it (showing as remote serial ports). C sourcecode (.c) and belonging header (.h) -files are:
<tt>xbee.c, xbee.h</tt>
and
<tt>pprz_transport.c, pprz_transport.h</tt>


Paparazzi can use the builtin transport layer of different hardware ( currently only wavecards and xbee/xtends ) and also provides his own layer for hardware lacking it ( showing as remote serial ports )
[[Category:Software]] [[Category:Developer_Documentation]]

Latest revision as of 04:00, 15 March 2016

Introduction

This page describes the way the communications with the aircrafts are implemented in Paparazzi.

We'll start with high level stuff such as sending your own telemetry message or datalink (uplink) message. We'll then look at the lower layers

Sending telemetry message

Define the message you would like to have send in the telemetry section in conf/messages.xml

This should look like this

<message name="MARK" id="32">
  <field name="ac_id" type="uint8"/>
  <field name="lat" type="float" unit="deg"/>
  <field name="long" type="float" unit="deg"/>
  <field name="alt" type="uint32" unit="mm" alt_unit="m" alt_unit_coef="1000"/>
</message>

The id has to be unique. The fields can have type int8, int16, int32, uint8, uint16, uint32, float and arrays of those. They must be aligned on a multiple of their size (c.f. examples with pad fields).

The alt_unit and alt_unit_coef will be used the Plotter and the Messages agents to display human readable values. When alt_unit_coef is not specified, some basic default conversions are automatic:

  • deg <-> rad
  • deg/s <-> rad/s
  • m <-> cm
  • m/s <-> cm/s
  • decideg -> deg

This enables all the ground system to deal with your message and generate sending code for the airborne system. The code is generated in var/include/messages.h.

TIP:

Ofcourse one can make a capitalized subdirectory in the conf directory e.g. a directory called MYUSERID where you save your personal messages defined XML document with a name like "myuserid_minimal_telemetry_messages.xml" and make a symbolic link to this file via "cd ~/paparazzi/conf/ && mv -v message.xml org.messages.xml && ln -s ./MYUSERID/myuserid_minimal_telemetry_messages.xml messages.xml"

Note that after changing your myuserid_minimal_telemetry_messages.xml, one always must perform a ~/paparazzi/make . This makes sure a refreshed message.h is generated in the ~/paparazzi/var directory. This file will then be compiled and linked into your autopilot airborne executable.

Messages Format

Detail to be found here Messages_Format

Airborne

From the airborne code you can send the message by using DOWNLINK_SEND_XYZ.

For example the MARK message:

DOWNLINK_SEND_MARK(DefaultChannel, &mark_id, &mark_lat, &mark_long, &mark_alt);

The first parameter of the DOWNLINK_SEND_XYZ macro is the channel you want to send it over, in most cases you want to use the DefaultChannel.

You can also have the autopilot send the message periodically.

To make that happen, in your telemetry XML document,for example conf/telemetry/MYUSERID/myuserid_new_telemetry_test.xml, you can make your own. Make sure the airframe also uses this file. In the conf/conf.xml file). You can add a line like

<message name="MARK" period="1.4"/>

meaning that MARK will be sent every 1.4 seconds. You then need to specify the arguments to your message in the sw/airborne/firmwares/fixedwing/ap_downlink.h or sw/airborne/firmwares/rotorcraft/telemetry.h header by providing a macro

#define PERIODIC_SEND_MARK() DOWNLINK_SEND_MARK(DefaultChannel, &mark_id, &mark_lat, &mark_long, &mark_alt)

You can have different telemetry modes having different rates for each message. For example you might want a verbose mode and a low bandwith mode.

On the IVY bus

After the data is sent by the aircraft the message will be available on the ground IVY bus. You can monitor you message values using the Messages program in the tools menu of the Paparazzi Center. One can also use the ivyprobe command line ( ivyprobe '(.*)' to debug passing messages).

The file sw/ground_segment/cockpit/ant_track.c is a good example that shows how to receive a message in a C program. In the sw/ground_segment/tmtc are even some more examples ( c_ivy_client_example*.c ). For OCAML, there is a higher level library to receive messages (sw/lib/ocaml/pprz.ml). If you are using Python take a look in /sw/ground_segment/python/ directory for example

Adding datalink (uplink) messages

This is similar to the above. Add your message in the datalink section of messages.xml This will generate parsing code for the airborne program (var/include/dl_protocol.h).

There are several possibilities to parse the uplink messages:

  1. add your handler in the sw/airborne/firmwares/fixedwing/datalink.c or sw/airborne/firmwares/rotorcraft/datalink.c code
  2. use a module with a datalink node where you specify the message to be parsed and the function to be called when the messages arrives
  3. or you can just rewrite your own dl_parse_msg() function, for example in a test program where you want to receive only your own messages.

The "transport" layer

Paparazzi can use the built-in transport layer of different hardware (currently only wavecards and xbee/xtends) and also provides his own layer for hardware lacking it (showing as remote serial ports). C sourcecode (.c) and belonging header (.h) -files are: xbee.c, xbee.h and pprz_transport.c, pprz_transport.h