Manual Control Protocol (Joystick)
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 (x, y, z, r) and two extension axes (s, t), and two 16-bit fields to represent the states of up to 32 buttons (buttons, buttons2). Unused axes can be disabled, and the extension axes must be explicitly enabled using bits 0 and 1 of the enabled_extensions field.
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.
Mapping Axes
Manual control is performed in the vehicle-frame. All axis values are normalised to the range -1000 to 1000.
Rotation-Focused Control
The typical axis assignments for a thrust- and rotation-controlled vehicle (e.g. planes, multicopters) are listed below.
| field | motion axis | +ve direction | -ve direction |
|---|---|---|---|
x | pitch | forward/nose-down | backward/nose-up |
y | roll | right-down | left-down |
z | thrust | positive | negative |
r | yaw | counter-clockwise | clockwise |
Directional Control
Vehicles with direct control over vehicle translation directions (multicopters) typically use the following mappings.
| field | motion axis | +ve direction | -ve direction |
|---|---|---|---|
x | forward | forward | backward |
y | lateral | right | left |
z | vertical | up | down |
r | yaw | counter-clockwise | clockwise |
s | pitch | forward/nose-down | backward/nose-up |
t | roll | right-down | left-down |
Mapping Buttons
Button functions are vehicle/flight-stack dependent:
- ArduPilot treats button values as user-configurable using firmware parameters (e.g. ArduCopter's
BTN_FUNCnor ArduSub'sBTNn_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.
The 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.
Alternatives
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.
Implementations
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.
Ground Control Stations
The protocol has been implemented in QGroundControl and Mission Planner.
QGroundControl implementation:
- src/Joystick/Joystick.cc (in
_handleAxismethod)
MissionPlanner implementation:
- MainV2.cs (in
joysticksendmethod)
Vehicle Firmwares
The protocol has been implemented in PX4, and in the Copter, Plane, Rover, and Sub vehicle firmwares in ArduPilot.
PX4 Implementation:
- mavlink_receiver.cpp (in
handle_message_manual_controlmethod)
ArduPilot Implementations:
- ArduCopter/GCS_Mavlink.cpp (in
handleMessagemethod) - ArduPlane/GCS_Mavlink.cpp (in
handleMessagemethod) - ArduRover/GCS_Mavlink.cpp (in
handle_manual_controlmethod) - ArduSub/joystick.cpp (in
transform_manual_control_to_rc_overridemethod)
Future Extensions
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).