Adding a new MAVLink Message (Code Overview)

Adding a new MAVLink Message (Code Overview)

Data and commands are passed between the ground station (i.e mission planner, Droid Planner, etc) using the MAVLink protocol over a serial interface. This page provides some high level advice for adding a new MAVLink message.

These instructions have only been tested on Linux (to be precise a VM running Ubuntu on a Windows machine). Instructions for setting up a VM are on the SITL page. If you can run SITL, you should be able to follow the advice here. These instructions will not run natively on Windows or a Mac.

Step #1: Ensure you have the latest ArduPilot code installed. Also check mavproxy. Mavproxy can be updated by running this command in a Terminal window:

sudo pip install --upgrade mavproxy

Step #2: Decide what type of message you want to add and how it will fit in with the existingMAVLink messages.

For example you might want to send a new new navigation command to the vehicle so that it can perform a trick (like a flip) in the middle of a mission (i.e. in AUTO mode). In this case you would need a new MAV_CMD_NAV_TRICK similar to the MAV_CMD_NAV_WAYPOINT definition (search for “MAV_CMD_NAV_WAYPOINT” in the MAVLink messages page).

Alternatively you may want to send down a new type of sensor data from the vehicle to the ground station. Perhaps similar to the SCALED_PRESSURE message.

Step #3: Add the new message definition to the common.xml or ardupilotmega.xml file

If this command will hopefully be added to the MAVLink protocol then it should be added to the ../ardupilot/libraries/GCS_MAVLink/message_definitions/common.xml file. If it is only for your personal use or only for use with Copter, Plane, Rover then it should be added to the ardupilotmega.xml file.

Step #4: Regenerate the include files that will allow the new message to be recognised in the main code.

First cd to the ardupilot directory and then run this command:

./libraries/GCS_MAVLink/generate.sh

If the generate completes successfully you should see that some of the following files have been updated.

../libraries/GCS_MAVLink/include/mavlink/v1.0/ardupilotmega/ardupilotmega.h
../libraries/GCS_MAVLink/include/mavlink/v1.0/ardupilotmega/version.h
../libraries/GCS_MAVLink/include/mavlink/v1.0/common/version.h

The version.h files should simply have a date & time updated in the file but the ardupilotmega.h should have your new message defined.

Step #5: Add functions to the main vehicle code to handle sending or receiving the command to/from the ground station.

The top level of this code will most likely be in the vehicle’s GCS_MAVLink.cpp file or in the../libraries/GCS_MAVLink/GCS class.

In the first example where we want to add support for a new navigation command (i.e. a trick) the following would be required:

• Extend the AP_Mission library’s mission_cmd_to_mavlink() and mavlink_to_mission_cmd() functions to convert the MAVProxy command into an AP_Mission::Mission_Command structure.
• Add a new case to the vehicle’s commands_logic.cpp‘s start_command() and verify_command()functions to check for the arrival of the new MAV_CMD_NAV_TRICK. These should call two new functions that you create called do_trick() and verify_trick() (see below).
• Create these two new functions, do_trick() and verify_trick(), that somehow command the vehicleto perform the trick (perhaps by calling another function in control_auto.cpp that sets the auto_mode variable and then calls a new auto_trick_start() function). The do_trick() function will be called when the command is first invoked. The verify_trick() will be called at 10hz (or higher) repeatedly until the trick is complete. The verify_trick() function should return true when the trick has been completed.

Step #6: Consider contributing your code back to the main code base. Email the drones-discuss email list and/or raise a pull request. If you raise a pull request it is best to separate the change into at least three separate commits. One commit for the changes to the .xml files (i.e Step #3), another for the generated files (i.e. Step #4) and then one or more commits for the changes to the vehicle code.