src/main/msp/msp_protocol.h

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