Category:Coax - software

From Skybotix

Jump to: navigation, search

You will find in this section all the software written for the Skybotix Coax®, including the programs used for controling dsPIC.



This document proposes an API for an easy to use CoaX helicopter. The application context here is to have a host computer or the embedded gumstix communicating with the micro-helicopter to send it high level commands. The communication channels are:

  • Serial line between embedded gumstix and micro-controller (reliable, low latency)
  • Bluetooth serial line between host PC and micro-controller (reliable up to 2 metres, variable latency)
  • UDP over WIFI, between host PC and embedded gumstix, the latter forwarding the commands to the micro-controller on the direct serial line (long-range, variable latency)

Most importantly, this API has been written from a user point of view: it shows what I think a user would expect. The 4 points below shows the typical use-cases considered when developing this API.

Typical program 1: basic monitoring

Do forever {
   Request helicopter state
   Display helicopter state

Typical program 2: basic control

Do forever {
   Request helicopter state
   Compute control using state
   Send control commands

Typical program 3: advanced monitoring

Configure communication channels for continous streaming
Do forever {
   Receive helicopter state

Typical program 4: advanced remote control

Configure communication channels for continuous streaming
Do forever {
   Receive helicopter state
   Compute control
   Send control commands

General Remarks

The API provides 3 layers of increasing complexity:

  1. Simplified, defined in sbsimple.h provides a default initialisation function, and only the basic function for doing sensor-based servoing.
  2. Complete, defined in sbapi.h provides access to all the helicopter configuration functions and controls, including raw commands.
  3. Raw communication channels, defined in sbchannel.h, used to send message directly to the helicopter.

Navigation mode

The helicopter has 8 navigation modes:

  • SB NAV STOP: the helicopter is stopped, on the ground, rotors stopped.
  • SB NAV IDLE: the helicopter is on the ground, rotors rotating but not enough for taking-off.
  • SB NAV TAKEOFF: the helicopter takes off, and transition to SB NAV HOVER when take-off succeeded.
  • SB NAV HOVER: the helicopter stays at constant height and yaw angle, with no pitch or roll. No horizontal stabilisation is active. If a watchdog is active, and no sbSetNavMode request is received after this timeout, the helicopter transition to SB NAV SINK.
  • SB NAV LAND: the helicopter comes to the ground, and transition to SB NAV IDLE automatically after touch down.
  • SB NAV CTRLLED: the helicopter is ready to receive user commands using sbSetControl or sbSimpleReachState. If a control timeout is active, and no control is received after this timeout, then the helicopter goes back to SB NAV HOVER.
  • SB_NAV_SINK: the helicopter slowly goes down until shutdown. This is an error mode, and can only be reached when a timeout is triggered while flying.
  • SB_NAV_RAW: the helicopter accept raw commands (servo and motor).

The transition between modes follows the following diagram:


struct SBControlContext

This C structure contains all the information relative to the communication channel and the recep- tion of data. It should be used as an abstract type, without relying on a specific implementation of its content.

All functions in complete API take as arguments a pointer on a SBControlContext struct. Initialisation functions fill in the required contents.

struct SBApiSimpleContext

This C structure contains an instance of SBControlContext, plus numerous useful variables to control the execution of a basic control loop. In particular, it stores information about the data reception thread used to listen for helicopter messages.

An important object in the SBApiSimpleContext structure is 'state'. This is updated each time a new data packet is received from the helicopter.

All functions in the simplified API take as arguments a pointer on a SBApiSimpleContext struct. The initialisation functions fill in the required contents.

Return values

All the functions of this API return 0 on success and anything else on failure. Error codes are not fully documented yet, but should follow the unix errno semantic whenever possible.

The simplified API


int sbSimpleDefaultContext(SBApiSimpleContext *context);

Initialise the context with default values. Should be called before any use of the context variable


int sbSimpleInitialise(SBApiSimpleContext *context);

Initialise the communication, the helicopter and possibly the state reception thread, based on the information in context. All configuration options are only read during this stage.


int sbSimpleReachNavState(SBApiSimpleContext *context, int desired, double timeout_sec);

Reach the desired navigation state within timeout sec. If several intermediary state are re- quired, they will be reached one by one.


int sbSimpleTerminate(SBApiSimpleContext *context);

Terminate the connection to the helicopter and bring it to a safe configuration (landed, motor stopped)


int sbSimpleWaitState(SBApiSimpleContext *context, SBHeliState *state, double timeout_sec);

Wait for a new state to be received. Only make sense in continuous communication mode. If state is not null, the received state is copied inside. If it is null, it is only copied in the internal storage, and in context->stateP pointer if not null


int sbSimpleControl(SBApiSimpleContext *context, double roll, double pitch, double yaw, double altitude);

Send a control command to the helicopter. The meaning of the command depends on the control mode configuration at initialisation, if not changed with sbConfigureControl


int sbSimpleRawControl(SBApiSimpleContext *context, double motor1, double motor2, double servo1, double servo2);

Send a raw control command to the helicopter. Only work in RAW COMMAND control mode.

Further informations

Complete API

Code samples

Using ROS

ROS is a robotic middle-ware developed by WillowGarage. You can find more information about on To simplify the integration of the CoaX in a larger project, we are now providing a basic ROS setup on the CoaX gumstix. This installation is in the ros directory in the coax user's home. The 3 main commands to know are the following:

  • roscore & : starts the ros name server and basic functionalities. It is available in the default path.
  • ~/ros/bin/coax_server /dev/ttyS0 : starts a topic exporting the state of the coax, and the basic functionalities. Documentation will come soon.
  • ~/ros/bin/dcam1394 or ~/ros/bin/cv_capture are serving video images. cv_capture is a basic example of what is possible. It uses opencv to capture a video frame, convert it and transmit it. This extremely slow on the gumstix, and a real application would have to optimise this program.

The sources for the coax_server and all the ros_tree is included on the gumstix micro-sd by default.

Once roscore, coax_server and dcam1394 are running, you can set the ROS_MASTER_URI to http://overo:11311 (replace overo with the hostname of your coax), and use the normal ROS tools to look at the data.

The provided sources contain a coax_ui program, providing a QT4 GUI using the ROS software. The interface is designed to display the coax state, and the video stream. The name of the video_stream is currently hard-coded. Modify it to suit your setup in CoaxGUIHandler.cpp.

The indication above are voluntarily vague, to strongly encourage you to consult the ROS wiki and in particular the tutorials before using this interface to the CoaX.

Cross-compiling for the gumstix

Cross compiling ROS for the gumstix is tricky at best. Cross-compiling a ROS application is not so simple either. A first guide is available on

A simple but slow solution is to create an image of your root file system, and boot it on an arm emulator using qemu. Beware that gcc is extremely slow when running in the emulated environment. Use the qemu documentation, and in particular qemu-img to create the virtual disk, mke2fs to create the file system, and copy the content of the micro-sd to this filesystem when mounted in loopback. Use the following link for more information:

Using qemu is mostly useful to create a development image for the gumstix. Once you can boot the micro-sd content in the emulator, you can use apt-get to install all the -dev packages that you need for compiling other applications. You will then be able to use the file in this image to cross-compile other applications (for instance ROS).

A latest solution is to use the cross-compiler from open-embedded, the loop-mounted development image, and the -sysroot option in GCC. I use the following options when compiling:

export GUMSTIXTOP=$HOME/coax/overo-oe/
export OVEROROOT=$HOME/coax/overobuntu/overo-dev
export PKG_CONFIG_PATH=$OVEROROOT/usr/local/lib/pkgconfig:$OVEROROOT/usr/lib/pkgconfig
export CFLAGS="--sysroot=$OVEROROOT -ggdb -g -I$OVEROROOT/usr/include"
export AR=$GUMSTIXTOP/tmp/cross/armv7a/bin/arm-angstrom-linux-gnueabi-ar
export CPP=$GUMSTIXTOP/tmp/cross/armv7a/bin/arm-angstrom-linux-gnueabi-cpp-sysroot
export CXX=$GUMSTIXTOP/tmp/cross/armv7a/bin/arm-angstrom-linux-gnueabi-g++-sysroot
export CC=$GUMSTIXTOP/tmp/cross/armv7a/bin/arm-angstrom-linux-gnueabi-gcc-sysroot

Note overo-dev is the directory where the root file system is locate (loopback-mounted), and that arm-angstrom-linux-gnueabi-cpp-sysroot is a trivial script:

if test -n "$ARM_SYSROOT"
exec ${0/-sysroot/} $SYSROOT $*

This will include the -sysroot by default when any gcc command is run. This is useful for some library where libtool is not able to transmit this information correctly to gcc.

The latter solution is the most efficient, but it requires a solid piece of expertise to set it up. Please find a linux guru around you to assist you in preparing the environment.

This category currently contains no pages or media.

Personal tools