src/main/io/serial_msp.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 #pragma once
  19
  20 #include "io/serial.h"
  21 #include "drivers/serial.h"
  22
  23 /**
  24  * MSP Guidelines, emphasis is used to clarify.
  25  *
  26  * Each FlightController (FC, Server) MUST change the API version when any MSP command is added, deleted, or changed.
  27  *
  28  * If you fork the FC source code and release your own version, you MUST change the Flight Controller Identifier.
  29  *
  30  * NEVER release a modified copy of this code that shares the same Flight controller IDENT and API version
  31  * if the API doesn't match EXACTLY.
  32  *
  33  * Consumers of the API (API clients) SHOULD first attempt to get a response from the MSP_API_VERSION command.
  34  * If no response is obtained then client MAY try the legacy MSP_IDENT command.
  35  *
  36  * API consumers should ALWAYS handle communication failures gracefully and attempt to continue
  37  * without the information if possible.  Clients MAY log/display a suitable message.
  38  *
  39  * API clients should NOT attempt any communication if they can't handle the returned API MAJOR VERSION.
  40  *
  41  * API clients SHOULD attempt communication if the API MINOR VERSION has increased from the time
  42  * the API client was written and handle command failures gracefully.  Clients MAY disable
  43  * functionality that depends on the commands while still leaving other functionality intact.
  44  * Clients SHOULD operate in READ-ONLY mode and SHOULD present a warning to the user to state
  45  * that the newer API version may cause problems before using API commands that change FC state.
  46  *
  47  * It is for this reason that each MSP command should be specific as possible, such that changes
  48  * to commands break as little client functionality as possible.
  49  *
  50  * API client authors MAY use a compatibility matrix/table when determining if they can support
  51  * a given command from a given flight controller at a given api version level.
  52  *
  53  * Developers MUST NOT create new MSP commands that do more than one thing.
  54  *
  55  * Failure to follow these guidelines will likely invoke the wrath of developers trying to write tools
  56  * that use the API and the users of those tools.
  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                   17 // increment when any change is made, reset to zero when major changes are released after changing API_VERSION_MAJOR
  63
  64 #define API_VERSION_LENGTH                  2
  65
  66 #define MULTIWII_IDENTIFIER "MWII";
  67 #define CLEANFLIGHT_IDENTIFIER "CLFL"
  68 #define BETAFLIGHT_IDENTIFIER "BTFL"
  69 #define BASEFLIGHT_IDENTIFIER "BAFL";
  70
  71 #define FLIGHT_CONTROLLER_IDENTIFIER_LENGTH 4
  72 extern const char * const flightControllerIdentifier;
  73
  74 #define FLIGHT_CONTROLLER_VERSION_LENGTH    3
  75 #define FLIGHT_CONTROLLER_VERSION_MASK      0xFFF
  76
  77 static const char * const boardIdentifier = TARGET_BOARD_IDENTIFIER;
  78 #define BOARD_IDENTIFIER_LENGTH             4 // 4 UPPER CASE alpha numeric characters that identify the board being used.
  79 #define BOARD_HARDWARE_REVISION_LENGTH      2
  80
  81 // These are baseflight specific flags but they are useless now since MW 2.3 uses the upper 4 bits for the navigation version.
  82 #define CAP_PLATFORM_32BIT          ((uint32_t)1 << 31)
  83 #define CAP_BASEFLIGHT_CONFIG       ((uint32_t)1 << 30)
  84
  85 // MW 2.3 stores NAVI_VERSION in the top 4 bits of the capability mask.
  86 #define CAP_NAVI_VERSION_BIT_4_MSB  ((uint32_t)1 << 31)
  87 #define CAP_NAVI_VERSION_BIT_3      ((uint32_t)1 << 30)
  88 #define CAP_NAVI_VERSION_BIT_2      ((uint32_t)1 << 29)
  89 #define CAP_NAVI_VERSION_BIT_1_LSB  ((uint32_t)1 << 28)
  90
  91 #define CAP_DYNBALANCE              ((uint32_t)1 << 2)
  92 #define CAP_FLAPS                   ((uint32_t)1 << 3)
  93 #define CAP_NAVCAP                  ((uint32_t)1 << 4)
  94 #define CAP_EXTAUX                  ((uint32_t)1 << 5)
  95
  96 #define MSP_API_VERSION                 1    //out message
  97 #define MSP_FC_VARIANT                  2    //out message
  98 #define MSP_FC_VERSION                  3    //out message
  99 #define MSP_BOARD_INFO                  4    //out message
 100 #define MSP_BUILD_INFO                  5    //out message
 101
 102 //
 103 // MSP commands for Cleanflight original features
 104 //
 105 #define MSP_MODE_RANGES                 34    //out message         Returns all mode ranges
 106 #define MSP_SET_MODE_RANGE              35    //in message          Sets a single mode range
 107
 108 #define MSP_FEATURE                     36
 109 #define MSP_SET_FEATURE                 37
 110
 111 #define MSP_BOARD_ALIGNMENT             38
 112 #define MSP_SET_BOARD_ALIGNMENT         39
 113
 114 #define MSP_CURRENT_METER_CONFIG        40
 115 #define MSP_SET_CURRENT_METER_CONFIG    41
 116
 117 #define MSP_MIXER                       42
 118 #define MSP_SET_MIXER                   43
 119
 120 #define MSP_RX_CONFIG                   44
 121 #define MSP_SET_RX_CONFIG               45
 122
 123 #define MSP_LED_COLORS                  46
 124 #define MSP_SET_LED_COLORS              47
 125
 126 #define MSP_LED_STRIP_CONFIG            48
 127 #define MSP_SET_LED_STRIP_CONFIG        49
 128
 129 #define MSP_RSSI_CONFIG                 50
 130 #define MSP_SET_RSSI_CONFIG             51
 131
 132 #define MSP_ADJUSTMENT_RANGES           52
 133 #define MSP_SET_ADJUSTMENT_RANGE        53
 134
 135 // private - only to be used by the configurator, the commands are likely to change
 136 #define MSP_CF_SERIAL_CONFIG            54
 137 #define MSP_SET_CF_SERIAL_CONFIG        55
 138
 139 #define MSP_VOLTAGE_METER_CONFIG        56
 140 #define MSP_SET_VOLTAGE_METER_CONFIG    57
 141
 142 #define MSP_SONAR_ALTITUDE              58 //out message get sonar altitude [cm]
 143
 144 #define MSP_PID_CONTROLLER              59
 145 #define MSP_SET_PID_CONTROLLER          60
 146
 147 #define MSP_ARMING_CONFIG               61 //out message         Returns auto_disarm_delay and disarm_kill_switch parameters
 148 #define MSP_SET_ARMING_CONFIG           62 //in message          Sets auto_disarm_delay and disarm_kill_switch parameters
 149
 150 #define MSP_DATAFLASH_SUMMARY           70 //out message - get description of dataflash chip
 151 #define MSP_DATAFLASH_READ              71 //out message - get content of dataflash chip
 152 #define MSP_DATAFLASH_ERASE             72 //in message - erase dataflash chip
 153
 154 #define MSP_LOOP_TIME                   73 //out message         Returns FC cycle time i.e looptime parameter
 155 #define MSP_SET_LOOP_TIME               74 //in message          Sets FC cycle time i.e looptime parameter
 156
 157 #define MSP_FAILSAFE_CONFIG             75 //out message         Returns FC Fail-Safe settings
 158 #define MSP_SET_FAILSAFE_CONFIG         76 //in message          Sets FC Fail-Safe settings
 159
 160 #define MSP_RXFAIL_CONFIG               77 //out message         Returns RXFAIL settings
 161 #define MSP_SET_RXFAIL_CONFIG           78 //in message          Sets RXFAIL settings
 162
 163 #define MSP_SDCARD_SUMMARY              79 //out message         Get the state of the SD card
 164
 165 #define MSP_BLACKBOX_CONFIG             80 //out message         Get blackbox settings
 166 #define MSP_SET_BLACKBOX_CONFIG         81 //in message          Set blackbox settings
 167
 168 #define MSP_TRANSPONDER_CONFIG          82 //in message          Get transponder settings
 169 #define MSP_SET_TRANSPONDER_CONFIG      83 //out message         Set transponder settings
 170
 171 #define MSP_OSD_CONFIG                  84 //in message          Get osd settings
 172 #define MSP_SET_OSD_CONFIG              85 //out message         Set osd settings
 173
 174 #define MSP_OSD_CHAR_READ               86 //in message          Get osd settings
 175 #define MSP_OSD_CHAR_WRITE              87 //out message         Set osd settings
 176
 177 #define MSP_VTX_CONFIG                  88 //in message          Get vtx settings
 178 #define MSP_SET_VTX_CONFIG              89 //out message         Set vtx settings
 179
 180 //
 181 // Baseflight MSP commands (if enabled they exist in Cleanflight)
 182 //
 183 #define MSP_RX_MAP                      64 //out message get channel map (also returns number of channels total)
 184 #define MSP_SET_RX_MAP                  65 //in message set rx map, numchannels to set comes from MSP_RX_MAP
 185
 186 // FIXME - Provided for backwards compatibility with configurator code until configurator is updated.
 187 // DEPRECATED - DO NOT USE "MSP_BF_CONFIG" and MSP_SET_BF_CONFIG.  In Cleanflight, isolated commands already exist and should be used instead.
 188 #define MSP_BF_CONFIG                   66 //out message baseflight-specific settings that aren't covered elsewhere
 189 #define MSP_SET_BF_CONFIG               67 //in message baseflight-specific settings save
 190
 191 #define MSP_REBOOT                      68 //in message reboot settings
 192
 193 // DEPRECATED - Use MSP_BUILD_INFO instead
 194 #define MSP_BF_BUILD_INFO               69 //out message build date as well as some space for future expansion
 195
 196 // Betaflight Additional Commands
 197 #define MSP_PID_ADVANCED_CONFIG         90
 198 #define MSP_SET_PID_ADVANCED_CONFIG     91
 199
 200 #define MSP_FILTER_CONFIG               92
 201 #define MSP_SET_FILTER_CONFIG           93
 202
 203 #define MSP_ADVANCED_TUNING             94
 204 #define MSP_SET_ADVANCED_TUNING         95
 205
 206 #define MSP_SENSOR_CONFIG               96
 207 #define MSP_SET_SENSOR_CONFIG           97
 208
 209 #define MSP_TEMPORARY_COMMANDS          98 // Temporary Commands before cleanup
 210 #define MSP_SET_TEMPORARY_COMMANDS      99 // Temporary Commands before cleanup
 211
 212 //
 213 // Multwii original MSP commands
 214 //
 215
 216 // DEPRECATED - See MSP_API_VERSION and MSP_MIXER
 217 #define MSP_IDENT                100    //out message         mixerMode + multiwii version + protocol version + capability variable
 218
 219
 220 #define MSP_STATUS               101    //out message         cycletime & errors_count & sensor present & box activation & current setting number
 221 #define MSP_RAW_IMU              102    //out message         9 DOF
 222 #define MSP_SERVO                103    //out message         servos
 223 #define MSP_MOTOR                104    //out message         motors
 224 #define MSP_RC                   105    //out message         rc channels and more
 225 #define MSP_RAW_GPS              106    //out message         fix, numsat, lat, lon, alt, speed, ground course
 226 #define MSP_COMP_GPS             107    //out message         distance home, direction home
 227 #define MSP_ATTITUDE             108    //out message         2 angles 1 heading
 228 #define MSP_ALTITUDE             109    //out message         altitude, variometer
 229 #define MSP_ANALOG               110    //out message         vbat, powermetersum, rssi if available on RX
 230 #define MSP_RC_TUNING            111    //out message         rc rate, rc expo, rollpitch rate, yaw rate, dyn throttle PID
 231 #define MSP_PID                  112    //out message         P I D coeff (9 are used currently)
 232 #define MSP_BOX                  113    //out message         BOX setup (number is dependant of your setup)
 233 #define MSP_MISC                 114    //out message         powermeter trig
 234 #define MSP_MOTOR_PINS           115    //out message         which pins are in use for motors & servos, for GUI
 235 #define MSP_BOXNAMES             116    //out message         the aux switch names
 236 #define MSP_PIDNAMES             117    //out message         the PID names
 237 #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
 238 #define MSP_BOXIDS               119    //out message         get the permanent IDs associated to BOXes
 239 #define MSP_SERVO_CONFIGURATIONS 120    //out message         All servo configurations.
 240 #define MSP_NAV_STATUS           121    //out message         Returns navigation status
 241 #define MSP_NAV_CONFIG           122    //out message         Returns navigation parameters
 242 #define MSP_3D                   124    //out message         Settings needed for reversible ESCs
 243 #define MSP_RC_DEADBAND          125    //out message         deadbands for yaw alt pitch roll
 244 #define MSP_SENSOR_ALIGNMENT     126    //out message         orientation of acc,gyro,mag
 245
 246 #define MSP_SET_RAW_RC           200    //in message          8 rc chan
 247 #define MSP_SET_RAW_GPS          201    //in message          fix, numsat, lat, lon, alt, speed
 248 #define MSP_SET_PID              202    //in message          P I D coeff (9 are used currently)
 249 #define MSP_SET_BOX              203    //in message          BOX setup (number is dependant of your setup)
 250 #define MSP_SET_RC_TUNING        204    //in message          rc rate, rc expo, rollpitch rate, yaw rate, dyn throttle PID, yaw expo
 251 #define MSP_ACC_CALIBRATION      205    //in message          no param
 252 #define MSP_MAG_CALIBRATION      206    //in message          no param
 253 #define MSP_SET_MISC             207    //in message          powermeter trig + 8 free for future use
 254 #define MSP_RESET_CONF           208    //in message          no param
 255 #define MSP_SET_WP               209    //in message          sets a given WP (WP#,lat, lon, alt, flags)
 256 #define MSP_SELECT_SETTING       210    //in message          Select Setting Number (0-2)
 257 #define MSP_SET_HEAD             211    //in message          define a new heading hold direction
 258 #define MSP_SET_SERVO_CONFIGURATION 212    //in message          Servo settings
 259 #define MSP_SET_MOTOR            214    //in message          PropBalance function
 260 #define MSP_SET_NAV_CONFIG       215    //in message          Sets nav config parameters - write to the eeprom
 261 #define MSP_SET_3D               217    //in message          Settings needed for reversible ESCs
 262 #define MSP_SET_RC_DEADBAND      218    //in message          deadbands for yaw alt pitch roll
 263 #define MSP_SET_RESET_CURR_PID   219    //in message          resetting the current pid profile to defaults
 264 #define MSP_SET_SENSOR_ALIGNMENT 220    //in message          set the orientation of the acc,gyro,mag
 265
 266 // #define MSP_BIND                 240    //in message          no param
 267 // #define MSP_ALARMS               242
 268
 269 #define MSP_EEPROM_WRITE         250    //in message          no param
 270
 271 #define MSP_DEBUGMSG             253    //out message         debug string buffer
 272 #define MSP_DEBUG                254    //out message         debug1,debug2,debug3,debug4
 273
 274 // Additional commands that are not compatible with MultiWii
 275 #define MSP_STATUS_EX            150    //out message         cycletime, errors_count, CPU load, sensor present etc
 276 #define MSP_UID                  160    //out message         Unique device ID
 277 #define MSP_GPSSVINFO            164    //out message         get Signal Strength (only U-Blox)
 278 #define MSP_ACC_TRIM             240    //out message         get acc angle trim values
 279 #define MSP_SET_ACC_TRIM         239    //in message          set acc angle trim values
 280 #define MSP_SERVO_MIX_RULES      241    //out message         Returns servo mixer configuration
 281 #define MSP_SET_SERVO_MIX_RULE   242    //in message          Sets servo mixer configuration
 282 #define MSP_SET_4WAY_IF          245    //in message          Sets 4way interface
 283
 284 // Each MSP port requires state and a receive buffer, revisit this default if someone needs more than 2 MSP ports.
 285 #define MAX_MSP_PORT_COUNT 2
 286
 287 typedef enum {
 288     IDLE,
 289     HEADER_START,
 290     HEADER_M,
 291     HEADER_ARROW,
 292     HEADER_SIZE,
 293     HEADER_CMD,
 294     COMMAND_RECEIVED
 295 } mspState_e;
 296
 297 #define MSP_PORT_INBUF_SIZE 64
 298
 299 typedef struct mspPort_s {
 300     serialPort_t *port; // null when port unused.
 301     uint8_t offset;
 302     uint8_t dataSize;
 303     uint8_t checksum;
 304     uint8_t indRX;
 305     uint8_t inBuf[MSP_PORT_INBUF_SIZE];
 306     mspState_e c_state;
 307     uint8_t cmdMSP;
 308 } mspPort_t;
 309
 310 void mspInit(serialConfig_t *serialConfig);
 311 void mspProcess(void);
 312 void mspAllocateSerialPorts(serialConfig_t *serialConfig);
 313 void mspReleasePortIfAllocated(serialPort_t *serialPort);