src/main/msp/msp_protocol.h

   1 /*
   2  * This file is part of Cleanflight and Betaflight.
   3  *
   4  * Cleanflight and Betaflight are free software. You can redistribute
   5  * this software and/or modify this software under the terms of the
   6  * GNU General Public License as published by the Free Software
   7  * Foundation, either version 3 of the License, or (at your option)
   8  * any later version.
   9  *
  10  * Cleanflight and Betaflight are distributed in the hope that they
  11  * will be useful, but WITHOUT ANY WARRANTY; without even the implied
  12  * warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
  13  * See the GNU General Public License for more details.
  14  *
  15  * You should have received a copy of the GNU General Public License
  16  * along with this software.
  17  *
  18  * If not, see <http://www.gnu.org/licenses/>.
  19  */
  20
  21 /**
  22  * MSP Guidelines, emphasis is used to clarify.
  23  *
  24  * Each FlightController (FC, Server) MUST change the API version when any MSP command is added, deleted, or changed.
  25  *
  26  * If you fork the FC source code and release your own version, you MUST change the Flight Controller Identifier.
  27  *
  28  * NEVER release a modified copy of this code that shares the same Flight controller IDENT and API version
  29  * if the API doesn't match EXACTLY.
  30  *
  31  * Consumers of the API (API clients) SHOULD first attempt to get a response from the MSP_API_VERSION command.
  32  * If no response is obtained then client MAY try the legacy MSP_IDENT command.
  33  *
  34  * API consumers should ALWAYS handle communication failures gracefully and attempt to continue
  35  * without the information if possible.  Clients MAY log/display a suitable message.
  36  *
  37  * API clients should NOT attempt any communication if they can't handle the returned API MAJOR VERSION.
  38  *
  39  * API clients SHOULD attempt communication if the API MINOR VERSION has increased from the time
  40  * the API client was written and handle command failures gracefully.  Clients MAY disable
  41  * functionality that depends on the commands while still leaving other functionality intact.
  42  * that the newer API version may cause problems before using API commands that change FC state.
  43  *
  44  * It is for this reason that each MSP command should be specific as possible, such that changes
  45  * to commands break as little functionality as possible.
  46  *
  47  * API client authors MAY use a compatibility matrix/table when determining if they can support
  48  * a given command from a given flight controller at a given api version level.
  49  *
  50  * Developers MUST NOT create new MSP commands that do more than one thing.
  51  *
  52  * Failure to follow these guidelines will likely invoke the wrath of developers trying to write tools
  53  * that use the API and the users of those tools.
  54  */
  55
  56 #pragma once
  57
  58 /* Protocol numbers used both by the wire format, config system, and
  59    field setters.
  60 */
  61
  62 #define MSP_PROTOCOL_VERSION                0
  63
  64 #define API_VERSION_MAJOR                   1  // increment when major changes are made
  65 #define API_VERSION_MINOR                   44 // increment after a release, to set the version for all changes to go into the following release (if no changes to MSP are made between the releases, this can be reverted before the release)
  66
  67 #define API_VERSION_LENGTH                  2
  68
  69 #define MULTIWII_IDENTIFIER "MWII";
  70 #define BASEFLIGHT_IDENTIFIER "BAFL";
  71 //#define BETAFLIGHT_IDENTIFIER "BTFL" Actual value stored in FC_FIRMWARE_IDENTIFIER in build/version.h
  72 #define CLEANFLIGHT_IDENTIFIER "CLFL"
  73 #define INAV_IDENTIFIER "INAV"
  74 #define RACEFLIGHT_IDENTIFIER "RCFL"
  75
  76 #define FLIGHT_CONTROLLER_IDENTIFIER_LENGTH 4
  77 #define FLIGHT_CONTROLLER_VERSION_LENGTH    3
  78 #define FLIGHT_CONTROLLER_VERSION_MASK      0xFFF
  79
  80 #define BOARD_IDENTIFIER_LENGTH             4 // 4 UPPER CASE alpha numeric characters that identify the board being used.
  81 #define BOARD_HARDWARE_REVISION_LENGTH      2
  82
  83 // These are baseflight specific flags but they are useless now since MW 2.3 uses the upper 4 bits for the navigation version.
  84 #define CAP_PLATFORM_32BIT          ((uint32_t)1 << 31)
  85 #define CAP_BASEFLIGHT_CONFIG       ((uint32_t)1 << 30)
  86
  87 // MW 2.3 stores NAVI_VERSION in the top 4 bits of the capability mask.
  88 #define CAP_NAVI_VERSION_BIT_4_MSB  ((uint32_t)1 << 31)
  89 #define CAP_NAVI_VERSION_BIT_3      ((uint32_t)1 << 30)
  90 #define CAP_NAVI_VERSION_BIT_2      ((uint32_t)1 << 29)
  91 #define CAP_NAVI_VERSION_BIT_1_LSB  ((uint32_t)1 << 28)
  92
  93 #define CAP_DYNBALANCE              ((uint32_t)1 << 2)
  94 #define CAP_FLAPS                   ((uint32_t)1 << 3)
  95 #define CAP_NAVCAP                  ((uint32_t)1 << 4)
  96 #define CAP_EXTAUX                  ((uint32_t)1 << 5)
  97
  98 #define MSP_API_VERSION                 1    //out message
  99 #define MSP_FC_VARIANT                  2    //out message
 100 #define MSP_FC_VERSION                  3    //out message
 101 #define MSP_BOARD_INFO                  4    //out message
 102 #define MSP_BUILD_INFO                  5    //out message
 103
 104 #define MSP_NAME                        10   //out message          Returns user set board name - betaflight
 105 #define MSP_SET_NAME                    11   //in message           Sets board name - betaflight
 106
 107 //
 108 // MSP commands for Cleanflight original features
 109 //
 110 #define MSP_BATTERY_CONFIG              32
 111 #define MSP_SET_BATTERY_CONFIG          33
 112
 113 #define MSP_MODE_RANGES                 34    //out message         Returns all mode ranges
 114 #define MSP_SET_MODE_RANGE              35    //in message          Sets a single mode range
 115
 116 #define MSP_FEATURE_CONFIG              36
 117 #define MSP_SET_FEATURE_CONFIG          37
 118
 119 #define MSP_BOARD_ALIGNMENT_CONFIG      38
 120 #define MSP_SET_BOARD_ALIGNMENT_CONFIG  39
 121
 122 #define MSP_CURRENT_METER_CONFIG        40
 123 #define MSP_SET_CURRENT_METER_CONFIG    41
 124
 125 #define MSP_MIXER_CONFIG                42
 126 #define MSP_SET_MIXER_CONFIG            43
 127
 128 #define MSP_RX_CONFIG                   44
 129 #define MSP_SET_RX_CONFIG               45
 130
 131 #define MSP_LED_COLORS                  46
 132 #define MSP_SET_LED_COLORS              47
 133
 134 #define MSP_LED_STRIP_CONFIG            48
 135 #define MSP_SET_LED_STRIP_CONFIG        49
 136
 137 #define MSP_RSSI_CONFIG                 50
 138 #define MSP_SET_RSSI_CONFIG             51
 139
 140 #define MSP_ADJUSTMENT_RANGES           52
 141 #define MSP_SET_ADJUSTMENT_RANGE        53
 142
 143 // private - only to be used by the configurator, the commands are likely to change
 144 #define MSP_CF_SERIAL_CONFIG            54
 145 #define MSP_SET_CF_SERIAL_CONFIG        55
 146
 147 #define MSP_VOLTAGE_METER_CONFIG        56
 148 #define MSP_SET_VOLTAGE_METER_CONFIG    57
 149
 150 #define MSP_SONAR_ALTITUDE              58 //out message get sonar altitude [cm]
 151
 152 #define MSP_PID_CONTROLLER              59
 153 #define MSP_SET_PID_CONTROLLER          60
 154
 155 #define MSP_ARMING_CONFIG               61
 156 #define MSP_SET_ARMING_CONFIG           62
 157
 158 //
 159 // Baseflight MSP commands (if enabled they exist in Cleanflight)
 160 //
 161 #define MSP_RX_MAP                      64 //out message get channel map (also returns number of channels total)
 162 #define MSP_SET_RX_MAP                  65 //in message set rx map, numchannels to set comes from MSP_RX_MAP
 163
 164 // DEPRECATED - DO NOT USE "MSP_BF_CONFIG" and MSP_SET_BF_CONFIG.  In Cleanflight, isolated commands already exist and should be used instead.
 165 // DEPRECATED - #define MSP_BF_CONFIG                   66 //out message baseflight-specific settings that aren't covered elsewhere
 166 // DEPRECATED - #define MSP_SET_BF_CONFIG               67 //in message baseflight-specific settings save
 167
 168 #define MSP_REBOOT                      68 //in message reboot settings
 169
 170 // Use MSP_BUILD_INFO instead
 171 // DEPRECATED - #define MSP_BF_BUILD_INFO               69 //out message build date as well as some space for future expansion
 172
 173 #define MSP_DATAFLASH_SUMMARY           70 //out message - get description of dataflash chip
 174 #define MSP_DATAFLASH_READ              71 //out message - get content of dataflash chip
 175 #define MSP_DATAFLASH_ERASE             72 //in message - erase dataflash chip
 176
 177 // No-longer needed
 178 // DEPRECATED - #define MSP_LOOP_TIME                   73 //out message         Returns FC cycle time i.e looptime parameter // DEPRECATED
 179 // DEPRECATED - #define MSP_SET_LOOP_TIME               74 //in message          Sets FC cycle time i.e looptime parameter    // DEPRECATED
 180
 181 #define MSP_FAILSAFE_CONFIG             75 //out message         Returns FC Fail-Safe settings
 182 #define MSP_SET_FAILSAFE_CONFIG         76 //in message          Sets FC Fail-Safe settings
 183
 184 #define MSP_RXFAIL_CONFIG               77 //out message         Returns RXFAIL settings
 185 #define MSP_SET_RXFAIL_CONFIG           78 //in message          Sets RXFAIL settings
 186
 187 #define MSP_SDCARD_SUMMARY              79 //out message         Get the state of the SD card
 188
 189 #define MSP_BLACKBOX_CONFIG             80 //out message         Get blackbox settings
 190 #define MSP_SET_BLACKBOX_CONFIG         81 //in message          Set blackbox settings
 191
 192 #define MSP_TRANSPONDER_CONFIG          82 //out message         Get transponder settings
 193 #define MSP_SET_TRANSPONDER_CONFIG      83 //in message          Set transponder settings
 194
 195 #define MSP_OSD_CONFIG                  84 //out message         Get osd settings - betaflight
 196 #define MSP_SET_OSD_CONFIG              85 //in message          Set osd settings - betaflight
 197
 198 #define MSP_OSD_CHAR_READ               86 //out message         Get osd settings - betaflight
 199 #define MSP_OSD_CHAR_WRITE              87 //in message          Set osd settings - betaflight
 200
 201 #define MSP_VTX_CONFIG                  88 //out message         Get vtx settings - betaflight
 202 #define MSP_SET_VTX_CONFIG              89 //in message          Set vtx settings - betaflight
 203
 204 // Betaflight Additional Commands
 205 #define MSP_ADVANCED_CONFIG             90
 206 #define MSP_SET_ADVANCED_CONFIG         91
 207
 208 #define MSP_FILTER_CONFIG               92
 209 #define MSP_SET_FILTER_CONFIG           93
 210
 211 #define MSP_PID_ADVANCED                94
 212 #define MSP_SET_PID_ADVANCED            95
 213
 214 #define MSP_SENSOR_CONFIG               96
 215 #define MSP_SET_SENSOR_CONFIG           97
 216
 217 #define MSP_CAMERA_CONTROL              98
 218
 219 #define MSP_SET_ARMING_DISABLED         99
 220
 221 //
 222 // OSD specific
 223 //
 224 #define MSP_OSD_VIDEO_CONFIG            180
 225 #define MSP_SET_OSD_VIDEO_CONFIG        181
 226
 227 // External OSD displayport mode messages
 228 #define MSP_DISPLAYPORT                 182
 229
 230 #define MSP_COPY_PROFILE                183
 231
 232 #define MSP_BEEPER_CONFIG               184
 233 #define MSP_SET_BEEPER_CONFIG           185
 234
 235 #define MSP_SET_TX_INFO                 186 // in message           Used to send runtime information from TX lua scripts to the firmware
 236 #define MSP_TX_INFO                     187 // out message          Used by TX lua scripts to read information from the firmware
 237
 238 //
 239 // Multwii original MSP commands
 240 //
 241
 242 // See MSP_API_VERSION and MSP_MIXER_CONFIG
 243 //DEPRECATED - #define MSP_IDENT                100    //out message         mixerMode + multiwii version + protocol version + capability variable
 244
 245
 246 #define MSP_STATUS               101    //out message         cycletime & errors_count & sensor present & box activation & current setting number
 247 #define MSP_RAW_IMU              102    //out message         9 DOF
 248 #define MSP_SERVO                103    //out message         servos
 249 #define MSP_MOTOR                104    //out message         motors
 250 #define MSP_RC                   105    //out message         rc channels and more
 251 #define MSP_RAW_GPS              106    //out message         fix, numsat, lat, lon, alt, speed, ground course
 252 #define MSP_COMP_GPS             107    //out message         distance home, direction home
 253 #define MSP_ATTITUDE             108    //out message         2 angles 1 heading
 254 #define MSP_ALTITUDE             109    //out message         altitude, variometer
 255 #define MSP_ANALOG               110    //out message         vbat, powermetersum, rssi if available on RX
 256 #define MSP_RC_TUNING            111    //out message         rc rate, rc expo, rollpitch rate, yaw rate, dyn throttle PID
 257 #define MSP_PID                  112    //out message         P I D coeff (9 are used currently)
 258 // Legacy Multiicommand that was never used.
 259 //DEPRECATED - #define MSP_BOX                  113    //out message         BOX setup (number is dependant of your setup)
 260 // Legacy command that was under constant change due to the naming vagueness, avoid at all costs - use more specific commands instead.
 261 //DEPRECATED - #define MSP_MISC                 114    //out message         powermeter trig
 262 // Legacy Multiicommand that was never used and always wrong
 263 //DEPRECATED - #define MSP_MOTOR_PINS           115    //out message         which pins are in use for motors & servos, for GUI
 264 #define MSP_BOXNAMES             116    //out message         the aux switch names
 265 #define MSP_PIDNAMES             117    //out message         the PID names
 266 #define MSP_WP                   118    //out message         get a WP, WP# is in the payload, returns (WP#, lat, lon, alt, flags) WP#0-home, WP#16-poshold
 267 #define MSP_BOXIDS               119    //out message         get the permanent IDs associated to BOXes
 268 #define MSP_SERVO_CONFIGURATIONS 120    //out message         All servo configurations.
 269 #define MSP_NAV_STATUS           121    //out message         Returns navigation status
 270 #define MSP_NAV_CONFIG           122    //out message         Returns navigation parameters
 271 #define MSP_MOTOR_3D_CONFIG      124    //out message         Settings needed for reversible ESCs
 272 #define MSP_RC_DEADBAND          125    //out message         deadbands for yaw alt pitch roll
 273 #define MSP_SENSOR_ALIGNMENT     126    //out message         orientation of acc,gyro,mag
 274 #define MSP_LED_STRIP_MODECOLOR  127    //out message         Get LED strip mode_color settings
 275 #define MSP_VOLTAGE_METERS       128    //out message         Voltage (per meter)
 276 #define MSP_CURRENT_METERS       129    //out message         Amperage (per meter)
 277 #define MSP_BATTERY_STATE        130    //out message         Connected/Disconnected, Voltage, Current Used
 278 #define MSP_MOTOR_CONFIG         131    //out message         Motor configuration (min/max throttle, etc)
 279 #define MSP_GPS_CONFIG           132    //out message         GPS configuration
 280 //DEPRECATED - #define MSP_COMPASS_CONFIG       133    //out message         Compass configuration
 281 #define MSP_ESC_SENSOR_DATA      134    //out message         Extra ESC data from 32-Bit ESCs (Temperature, RPM)
 282 #define MSP_GPS_RESCUE           135    //out message         GPS Rescues's angle, initialAltitude, descentDistance, rescueGroundSpeed, sanityChecks and minSats
 283 #define MSP_GPS_RESCUE_PIDS      136    //out message         GPS Rescues's throttleP and velocity PIDS + yaw P
 284 #define MSP_VTXTABLE_BAND        137    //out message         vtxTable band/channel data
 285 #define MSP_VTXTABLE_POWERLEVEL  138    //out message         vtxTable powerLevel data
 286 #define MSP_MOTOR_TELEMETRY      139    //out message         Per-motor telemetry data (RPM, packet stats, ESC temp, etc.)
 287
 288 #define MSP_SIMPLIFIED_TUNING             140    //out message    Simplified tuning values and enabled state
 289 #define MSP_SET_SIMPLIFIED_TUNING         141    //in message     Set simplified tuning positions and apply the calculated tuning
 290 #define MSP_CALCULATE_SIMPLIFIED_PID      142    //out message    Requests calculations of PID values based on sliders. Sends the calculated values back. But don't save anything to the firmware
 291 #define MSP_CALCULATE_SIMPLIFIED_GYRO     143    //out message    Requests calculations of gyro filter values based on sliders. Sends the calculated values back. But don't save anything to the firmware
 292 #define MSP_CALCULATE_SIMPLIFIED_DTERM    144    //out message    Requests calculations of gyro filter values based on sliders. Sends the calculated values back. But don't save anything to the firmware
 293 #define MSP_VALIDATE_SIMPLIFIED_TUNING    145    //out message    Returns an array of true/false showing which simpligfied tuning groups are matching with value and which are not
 294
 295 #define MSP_SET_RAW_RC           200    //in message          8 rc chan
 296 #define MSP_SET_RAW_GPS          201    //in message          fix, numsat, lat, lon, alt, speed
 297 #define MSP_SET_PID              202    //in message          P I D coeff (9 are used currently)
 298 // Legacy multiiwii command that was never used.
 299 //DEPRECATED - #define MSP_SET_BOX              203    //in message          BOX setup (number is dependant of your setup)
 300 #define MSP_SET_RC_TUNING        204    //in message          rc rate, rc expo, rollpitch rate, yaw rate, dyn throttle PID, yaw expo
 301 #define MSP_ACC_CALIBRATION      205    //in message          no param
 302 #define MSP_MAG_CALIBRATION      206    //in message          no param
 303 // Legacy command that was under constant change due to the naming vagueness, avoid at all costs - use more specific commands instead.
 304 //DEPRECATED - #define MSP_SET_MISC             207    //in message          powermeter trig + 8 free for future use
 305 #define MSP_RESET_CONF           208    //in message          no param
 306 #define MSP_SET_WP               209    //in message          sets a given WP (WP#,lat, lon, alt, flags)
 307 #define MSP_SELECT_SETTING       210    //in message          Select Setting Number (0-2)
 308 #define MSP_SET_HEADING          211    //in message          define a new heading hold direction
 309 #define MSP_SET_SERVO_CONFIGURATION 212    //in message          Servo settings
 310 #define MSP_SET_MOTOR            214    //in message          PropBalance function
 311 #define MSP_SET_NAV_CONFIG       215    //in message          Sets nav config parameters - write to the eeprom
 312 #define MSP_SET_MOTOR_3D_CONFIG  217    //in message          Settings needed for reversible ESCs
 313 #define MSP_SET_RC_DEADBAND      218    //in message          deadbands for yaw alt pitch roll
 314 #define MSP_SET_RESET_CURR_PID   219    //in message          resetting the current pid profile to defaults
 315 #define MSP_SET_SENSOR_ALIGNMENT 220    //in message          set the orientation of the acc,gyro,mag
 316 #define MSP_SET_LED_STRIP_MODECOLOR 221 //in  message         Set LED strip mode_color settings
 317 #define MSP_SET_MOTOR_CONFIG     222    //out message         Motor configuration (min/max throttle, etc)
 318 #define MSP_SET_GPS_CONFIG       223    //out message         GPS configuration
 319 //DEPRECATED - #define MSP_SET_COMPASS_CONFIG   224    //out message         Compass configuration
 320 #define MSP_SET_GPS_RESCUE       225    //in message          GPS Rescues's angle, initialAltitude, descentDistance, rescueGroundSpeed, sanityChecks and minSats
 321 #define MSP_SET_GPS_RESCUE_PIDS  226    //in message          GPS Rescues's throttleP and velocity PIDS + yaw P
 322 #define MSP_SET_VTXTABLE_BAND    227    //in message          set vtxTable band/channel data (one band at a time)
 323 #define MSP_SET_VTXTABLE_POWERLEVEL 228 //in message          set vtxTable powerLevel data (one powerLevel at a time)
 324
 325 // #define MSP_BIND                 240    //in message          no param
 326 // #define MSP_ALARMS               242
 327
 328 #define MSP_EEPROM_WRITE         250    //in message          no param
 329 #define MSP_RESERVE_1            251    //reserved for system usage
 330 #define MSP_RESERVE_2            252    //reserved for system usage
 331 #define MSP_DEBUGMSG             253    //out message         debug string buffer
 332 #define MSP_DEBUG                254    //out message         debug1,debug2,debug3,debug4
 333 #define MSP_V2_FRAME             255    //MSPv2 payload indicator
 334
 335 // Additional commands that are not compatible with MultiWii
 336 #define MSP_STATUS_EX            150    //out message         cycletime, errors_count, CPU load, sensor present etc
 337 #define MSP_UID                  160    //out message         Unique device ID
 338 #define MSP_GPSSVINFO            164    //out message         get Signal Strength (only U-Blox)
 339 #define MSP_GPSSTATISTICS        166    //out message         get GPS debugging data
 340 #define MSP_MULTIPLE_MSP         230    //out message         request multiple MSPs in one request - limit is the TX buffer; returns each MSP in the order they were requested starting with length of MSP; MSPs with input arguments are not supported
 341 #define MSP_MODE_RANGES_EXTRA    238    //out message         Reads the extra mode range data
 342 #define MSP_ACC_TRIM             240    //out message         get acc angle trim values
 343 #define MSP_SET_ACC_TRIM         239    //in message          set acc angle trim values
 344 #define MSP_SERVO_MIX_RULES      241    //out message         Returns servo mixer configuration
 345 #define MSP_SET_SERVO_MIX_RULE   242    //in message          Sets servo mixer configuration
 346 #define MSP_SET_PASSTHROUGH      245    //in message          Sets up passthrough to different peripherals (4way interface, uart, etc...)
 347 #define MSP_SET_RTC              246    //in message          Sets the RTC clock
 348 #define MSP_RTC                  247    //out message         Gets the RTC clock
 349 #define MSP_SET_BOARD_INFO       248    //in message          Sets the board information for this board
 350 #define MSP_SET_SIGNATURE        249    //in message          Sets the signature of the board and serial number