The Manual Control Protocol enables controlling a system using a "standard joystick" (or joystick-like input device that supports the same axes nomenclature).
The protocol is implemented with just the
MANUAL_CONTROL message. It defines the
target system to be controlled, the movement in four primary axes (
r) and two extension axes (
t), and two 16-bit fields to represent the states of up to 32 buttons (
buttons2). Unused axes can be disabled, and the extension axes must be explicitly enabled using bits 0 and 1 of the
The protocol is by intent relatively simple and abstract, and provides a simple way of controlling the main motion of a vehicle, along with several arbitrary features that can be triggered using buttons.
This allows GCS software to provide a simple level of control for many types of vehicles, and allows new vehicle types with unusual functions to operate with minimal (if any) changes to the MAVLink protocol or existing ground control station (GCS) software.
Manual control is performed in the vehicle-frame. All axis values are normalised to the range -1000 to 1000.
The typical axis assignments for a thrust- and rotation-controlled vehicle (e.g. planes, multicopters) are listed below.
Vehicles with direct control over vehicle translation directions (multicopters) typically use the following mappings.
Button functions are vehicle/flight-stack dependent:
- ArduPilot treats button values as user-configurable using firmware parameters (e.g. ArduCopter's
BTNn_FUNCTION), through the Parameter or Extended Parameter protocols.
- PX4 defines fixed meanings to some of the
buttonsvalues, and these are mapped to user-selected functions by the ground station.
buttons field is required, and corresponds to the first 16 buttons.
buttons2 is an extension, and corresponds to the optional second set of 16 buttons.
Vehicles may alternatively be controlled by sending information as a set of up to 18 channel values using
RC_CHANNELS_OVERRIDE. Channels can be mapped to firmware parameters using
PARAM_MAP_RC, and the autopilot can use the current parameter values at each point in time to determine control actions.
It's worth noting that the generality of RC channels control is a double-edged sword. It is incredibly versatile, and can be used to provide support for several arbitrary control axes, but the user-defined in-vehicle nature of the mapped parameters means additional setup is frequently required for compatibility with GCSs, and there are no guarantees that multiple vehicles running the same firmware will have the same channel-parameter mapping. This is a similar issue to the
MANUAL_CONTROL buttons, so to minimise firmware complexity and maximise interoperability between a vehicle type and GCSs it's recommended to use targetted MAVLink commands where possible.
The protocol has been implemented in various GCSs and vehicle firmwares. These implementations can be used in your own code within the terms of their software licenses.
The protocol has been implemented in QGroundControl and Mission Planner.
- src/Joystick/Joystick.cc (in
- MainV2.cs (in
The protocol has been implemented in PX4, and in the Copter, Plane, Rover, and Sub vehicle firmwares in ArduPilot.
- mavlink_receiver.cpp (in
- ArduCopter/GCS_Mavlink.cpp (in
- ArduPlane/GCS_Mavlink.cpp (in
- ArduRover/GCS_Mavlink.cpp (in
- ArduSub/joystick.cpp (in
Future extensions are likely to be handled with additional targetted MAVLink commands rather than mapping functionality in the flight controller (i.e. handling more complex inputs in the GCS to reduce vehicle firmware complexity).