You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

161 lines
7.3 KiB

  1. # MSP Extensions
  2. INAV includes a number of extensions to the MultiWii Serial Protocol (MSP). This document describes
  3. those extensions in order that 3rd party tools may identify INAV firmware and react appropriately.
  4. Issue the MSP_API_VERSION command to find out if the firmware supports them.
  5. ## Mode Ranges
  6. ### MSP\_MODE\_RANGES
  7. The MSP\_MODE\_RANGES returns the current auxiliary mode settings from the flight controller. It should be invoked
  8. before any modification is made to the configuration.
  9. The message returns a group of 4 unsigned bytes for each 'slot' available in the flight controller. The number of
  10. slots should be calculated from the size of the returned message.
  11. | Command | Msg Id | Direction | Notes |
  12. |---------|--------|-----------|-------|
  13. | MSP\_MODE\_RANGES | 34 | to FC | Following this command, the FC returns a block of 4 bytes for each auxiliary mode 'slot'|
  14. Unassigned slots have rangeStartStep == rangeEndStep. Each element contains the following fields.
  15. | Data | Type | Notes |
  16. |------|------|-------|
  17. | permanentId | uint8 | See Modes.md for a definition of the permanent ids |
  18. | auxChannelIndex | uint8 | The Aux switch number (indexed from 0) |
  19. | rangeStartStep | uint8 | The start value for this element in 'blocks' of 25 where 0 == 900 and 48 == 2100 |
  20. | rangeEndStep | uint8 | The end value for this element in 'blocks' of 25 where 0 == 900 and 48 == 2100 |
  21. Thus, for a INAV firmware with 40 slots 160 bytes would be returned in response to MSP\_MODE\_RANGES,
  22. ### MSP\_SET\_MODE\_RANGE
  23. The MSP\_SET\_MODE\_RANGE is used to inform the flight controller of
  24. auxiliary mode settings. The client *must* return all auxiliary
  25. elements, including those that have been disabled or are undefined, by
  26. sending this message for all auxiliary slots.
  27. | Command | Msg Id | Direction |
  28. |---------|--------|-----------|
  29. | MSP\_SET\_MODE\_RANGE | 35 | to FC |
  30. | Data | Type | Notes |
  31. |------|------|-------|
  32. | sequence id | uint8 | A monotonically increasing ID, from 0 to the number of slots -1 |
  33. | permanentId | uint8 | See Modes.md for a definition of the permanent ids |
  34. | auxChannelIndex | uint8 | The Aux channel number (indexed from 0) |
  35. | rangeStartStep | uint8 | The start value for this element in 'blocks' of 25 where 0 == 900 and 48 == 2100 |
  36. | rangeEndStep | uint8 | The end value for this element in 'blocks' of 25 where 0 == 900 and 48 == 2100 |
  37. ### Implementation Notes
  38. * The client should make no assumptions about the number of slots available. Rather, the number should be computed
  39. from the size of the MSP\_MODE\_RANGES message divided by the size of the returned data element (4 bytes);
  40. * The client should ensure that all changed items are returned to the flight controller, including those where a
  41. switch or range has been disabled;
  42. * A 'null' return, with all values other than the sequence id set to 0, must be made for all unused slots, up to
  43. the maximum number of slots calculated from the initial message.
  44. ## Adjustment Ranges
  45. ### MSP\_ADJUSTMENT\_RANGES
  46. The MSP\_ADJUSTMENT\_RANGES returns the current adjustment range settings from
  47. the flight controller. It should be invoked before any modification is
  48. made to the configuration.
  49. The message returns a group of 6 unsigned bytes for each 'slot'
  50. available in the flight controller. The number of slots should be
  51. calculated from the size of the returned message.
  52. | Command | Msg Id | Direction | Notes |
  53. |---------|--------|-----------|-------|
  54. | MSP\_ADJUSTMENT\_RANGES | 52 | to FC | Following this command, the FC returns a block of 6 bytes for each adjustment range 'slot'|
  55. Unassigned slots have rangeStartStep == rangeEndStep. Each element contains the following fields.
  56. | Data | Type | Notes |
  57. |------|------|-------|
  58. | adjustmentStateIndex | uint8 | See below |
  59. | auxChannelIndex | uint8 | The Aux channel number (indexed from 0) used to activate the adjustment |
  60. | rangeStartStep | uint8 | The start value for this element in 'blocks' of 25 where 0 == 900 and 48 == 2100 |
  61. | rangeEndStep | uint8 | The end value for this element in 'blocks' of 25 where 0 == 900 and 48 == 2100 |
  62. | adjustmentFunction | uint8 | See below |
  63. | auxSwitchChannelIndex | uint8 | The Aux channel number used to perform the function (indexed from 0) |
  64. Thus, for a INAV firmware with 12 slots 72 bytes would be returned in response to MSP\_ADJUSTMENT\_RANGES,
  65. ### MSP\_SET\_ADJUSTMENT\_RANGE
  66. The MSP\_SET\_ADJUSTMENT\_RANGE is used to inform the flight controller of
  67. adjustment range settings. The client *must* return all adjustment range
  68. elements, including those that have been disabled or are undefined, by
  69. sending this message for all adjustment range slots.
  70. | Command | Msg Id | Direction |
  71. |---------|--------|-----------|
  72. | MSP\_SET\_ADJUSTMENT\_RANGE | 53 | to FC |
  73. | Data | Type | Notes |
  74. |------|------|-------|
  75. | sequence id | uint8 | A monotonically increasing ID, from 0 to the number of slots -1 |
  76. | adjustmentStateIndex | uint8 | See below |
  77. | auxChannelIndex | uint8 | The Aux channel number (indexed from 0) |
  78. | rangeStartStep | uint8 | The start value for this element in 'blocks' of 25 where 0 == 900 and 48 == 2100 |
  79. | rangeEndStep | uint8 | The end value for this element in 'blocks' of 25 where 0 == 900 and 48 == 2100 |
  80. | adjustmentFunction | uint8 | See below |
  81. | auxSwitchChannelIndex | uint8 | The Aux channel number used to perform the function (indexed from 0) |
  82. ### MSP\_SET\_1WIRE
  83. The MSP\_SET\_1WIRE is used to enable serial1wire passthrough
  84. note: it would be ideal to disable this when armed
  85. | Command | Msg Id | Direction |
  86. |---------|--------|-----------|
  87. | MSP\_SET\_1WIRE | 243 | to FC |
  88. | Data | Type | Notes |
  89. |------|------|-------|
  90. | esc id | uint8 | A monotonically increasing ID, from 0 to the number of escs -1 |
  91. #### AdjustmentIndex
  92. The FC maintains internal state for each adjustmentStateIndex, currently 4 simultaneous adjustment states are maintained. Multiple adjustment ranges
  93. can be configured to use the same state but care should be taken not to send multiple adjustment ranges that when active would confict.
  94. e.g. Configuring two identical adjustment ranges using the same slot would conflict, but configuring two adjustment ranges that used
  95. only one half of the possible channel range each but used the same adjustmentStateIndex would not conflict.
  96. The FC does NOT check for conflicts.
  97. #### AdjustmentFunction
  98. There are many adjustments that can be made, the numbers of them and their use is found in the documentation of the cli `adjrange` command in the 'Inflight Adjustents' section.
  99. ### Implementation Notes
  100. * The client should make no assumptions about the number of slots available. Rather, the number should be computed
  101. from the size of the MSP\_ADJUSTMENT\_RANGES message divided by the size of the returned data element (6 bytes);
  102. * The client should ensure that all changed items are returned to the flight controller, including those where a
  103. switch or range has been disabled;
  104. * A 'null' return, with all values except for the sequence id set to 0, must be made for all unused slots,
  105. up to the maximum number of slots calculated from the initial message.
  106. ## Deprecated MSP
  107. The following MSP commands are replaced by the MSP\_MODE\_RANGES and
  108. MSP\_SET\_MODE\_RANGE extensions, and are not recognised by
  109. INAV.
  110. * MSP\_BOX
  111. * MSP\_SET\_BOX
  112. See also
  113. --------
  114. Modes.md describes the user visible implementation for the INAV
  115. modes extension.