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()
andmavlink_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()
andverify_command()
functions to check for the arrival of the newMAV_CMD_NAV_TRICK
. These should call two new functions that you create calleddo_trick()
andverify_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). Thedo_trick()
function will be called when the command is first invoked. Theverify_trick()
will be called at 10hz (or higher) repeatedly until the trick is complete. Theverify_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.