docs/Cli.md

   1 # Command Line Interface (CLI)
   2
   3 INAV has a command line interface (CLI) that can be used to change settings and configure the FC.
   4
   5 ## Accessing the CLI.
   6
   7 The CLI can be accessed via the GUI tool or via a terminal emulator connected to the CLI serial port.
   8
   9 1. Connect your terminal emulator to the CLI serial port (which, by default, is the same as the MSP serial port)
  10 2. Use the baudrate specified by msp_baudrate (115200 by default).
  11 3. Send a `#` character.
  12
  13 To save your settings type in 'save', saving will reboot the flight controller.
  14
  15 To exit the CLI without saving power off the flight controller or type in 'exit'.
  16
  17 To see a list of other commands type in 'help' and press return.
  18
  19 To dump your configuration (including the current profile), use the 'dump' or 'diff' command.
  20
  21 See the other documentation sections for details of the cli commands and settings that are available.
  22
  23 ## Backup via CLI
  24
  25 Disconnect main power, connect to cli via USB/FTDI.
  26
  27 dump using cli
  28
  29 ```
  30 profile 0
  31 dump
  32 ```
  33
  34 dump profiles using cli if you use them
  35
  36 ```
  37 profile 1
  38 dump profile
  39 profile 2
  40 dump profile
  41 ```
  42
  43 copy screen output to a file and save it.
  44
  45 Alternatively, use the `diff` command to dump only those settings that differ from their default values (those that have been changed).
  46
  47
  48 ## Restore via CLI.
  49
  50 Use the cli `defaults` command first.
  51
  52 When restoring from backup it's a good idea to do a dump of the latest defaults so you know what has changed - if you do this each time a firmware release is created you will be able to see the cli changes between firmware versions. If you blindly restore your backup you would not benefit from these new defaults or may even end up with completely wrong settings in case some parameters changed semantics and/or value ranges.
  53
  54 It may be good idea to restore settings using the `diff` output rather than complete `dump`. This way you can have more control on what is restored and the risk of mistakenly restoring bad values if the semantics changes is minimised.
  55
  56 To perform the restore simply paste the saved commands in the Configurator CLI tab and then type `save`.
  57
  58 After restoring it's always a good idea to `dump` or `diff` the settings once again and compare the output with previous one to verify if everything is set as it should be.
  59
  60 ## Flight Controller opereration while connected to the CLI
  61
  62 While connected to the CLI, all Logical Switches are temporarily disabled (5.1.0 onwards).
  63
  64 ## CLI Command Reference
  65
  66 | `Command` | Description |
  67 |-----------| ----------- |
  68 | `adjrange` | Configure adjustment ranges |
  69 | `assert` |  |
  70 | `aux` | Configure modes |
  71 | `batch` | Start or end a batch of commands |
  72 | `battery_profile` | Change battery profile |
  73 | `beeper` | Show/set beeper (buzzer) [usage](Buzzer.md) |
  74 | `bind_rx` | Initiate binding for SRXL2 or CRSF receivers |
  75 | `blackbox` | Configure blackbox fields |
  76 | `bootlog` | Show boot events |
  77 | `color` | Configure colors |
  78 | `defaults` | Reset to defaults and reboot |
  79 | `dfu` | DFU mode on reboot |
  80 | `diff` | List configuration changes from default |
  81 | `dump` | Dump configuration |
  82 | `exit` |  |
  83 | `feature` | List or enable <val> or disable <-val> |
  84 | `flash_erase` | Erase flash chip |
  85 | `flash_info` | Show flash chip info |
  86 | `flash_read` |  |
  87 | `flash_write` |  |
  88 | `get` | Get variable value |
  89 | `gpspassthrough` | Passthrough gps to serial |
  90 | `gvar` | Configure global variables |
  91 | `help` | Displays CLI help and command parameters / options |
  92 | `led` | Configure leds |
  93 | `logic` | Configure logic conditions |
  94 | `map` | Configure rc channel order |
  95 | `memory` | View memory usage |
  96 | `mmix` | Custom motor mixer |
  97 | `mode_color` | Configure mode and special colors |
  98 | `motor` | Get/set motor |
  99 | `msc` | Enter USB Mass storage mode. See [USB MSC documentation](USB_Mass_Storage_(MSC)_mode.md) for usage information. |
 100 | `osd_layout` | Get or set the layout of OSD items |
 101 | `pid` | Configurable PID controllers |
 102 | `play_sound` | `<index>`, or none for next item |
 103 | `profile` | Change profile |
 104 | `resource` | View currently used resources |
 105 | `rxrange` | Configure rx channel ranges |
 106 | `safehome` | Define safe home locations. See the [safehome documentation](Safehomes.md) for usage information. |
 107 | `save` | Save and reboot |
 108 | `sd_info` | Sdcard info |
 109 | `serial` | Configure serial ports. [Usage](Serial.md) |
 110 | `serialpassthrough` | Passthrough serial data to port, with `<id> <baud> <mode> <options>`, where `id` is the zero based port index, `baud` is a standard baud rate, mode is `rx`, `tx`, or both (`rxtx`), and options is a short string like `8N1` or `8E2` |
 111 | `servo` | Configure servos |
 112 | `set` | Change setting with name=value or blank or * for list |
 113 | `smix` | Custom servo mixer |
 114 | `status` | Show status. Error codes can be looked up [here](https://github.com/iNavFlight/inav/wiki/%22Something%22-is-disabled----Reasons) |
 115 | `tasks` | Show task stats |
 116 | `temp_sensor` | List or configure temperature sensor(s). See [temperature sensors documentation](Temperature-sensors.md) for more information. |
 117 |  `timer_output_mode`  | Override automatic timer /  pwm function allocation. [Additional Information](#timer_outout_mode)|
 118 | `version` | Show version |
 119 | `wp` | List or configure waypoints. See the [navigation documentation](Navigation.md#cli-command-wp-to-manage-waypoints). |
 120
 121 Notes:
 122
 123 * Available commands depend upon hardware specific and debug build options. Not all commands are available in every FC.
 124 * The above list shows the output available in the CLI `help` command. This may also show additional information.
 125
 126 ### serial
 127
 128 The syntax of the `serial` command is `serial <id>  <function_value> <msp-baudrate> <gps-baudrate> <telemetry-baudate> <peripheral-baudrate>`.
 129
 130 A shorter form is also supported to enable and disable a single function using `serial <id> +n` and `serial <id> -n`, where n is the a serial function identifier. The following values are available:
 131
 132 | Function              | Bit Identifier | Numeric value |
 133 |-----------------------|---------------|----------------|
 134 | MSP                   | 0             | 1 |
 135 | GPS                   | 1             | 2 |
 136 | TELEMETRY_FRSKY       | 2             | 4 |
 137 | TELEMETRY_HOTT        | 3             | 8 |
 138 | TELEMETRY_LTM         | 4             | 16 |
 139 | TELEMETRY_SMARTPORT   | 5             | 32 |
 140 | RX_SERIAL             | 6             | 64 |
 141 | BLACKBOX              | 7             | 128 |
 142 | TELEMETRY_MAVLINK     | 8             | 256 |
 143 | TELEMETRY_IBUS        | 9             | 512 |
 144 | RCDEVICE              | 10            | 1024 |
 145 | VTX_SMARTAUDIO        | 11            | 2048 |
 146 | VTX_TRAMP             | 12            | 4096 |
 147 | UAV_INTERCONNECT      | 13            | 8192 |
 148 | OPTICAL_FLOW          | 14            | 16384 |
 149 | LOG                   | 15            | 32768 |
 150 | RANGEFINDER           | 16            | 65536 |
 151 | VTX_FFPV              | 17            | 131072 |
 152 | ESCSERIAL             | 18            | 262144 |
 153 | TELEMETRY_SIM         | 19            | 524288 |
 154 | FRSKY_OSD             | 20            | 1048576 |
 155 | DJI_HD_OSD            | 21            | 2097152 |
 156 | SERVO_SERIAL          | 22            | 4194304 |
 157 | TELEMETRY_SMARTPORT_MASTER | 23       | 8388608 |
 158 | UNUSED                | 24            | 16777216 |
 159 | MSP_DISPLAYPORT       | 25            | 33554432 |
 160 | GIMBAL_SERIAL         | 26            | 67108864 |
 161 | HEADTRACKER_SERIAL    | 27            | 134217728 |
 162
 163 Thus, to enable MSP and LTM on a port, one would use the function **value** of 17 (1 << 0)+(1<<4), aka 1+16, aka 17.
 164
 165 ```
 166 serial 0 17 57600 57600 57600 57600
 167 ```
 168 but to remove LTM using the +/- shorthand, use the **bit Id** (4, TELEMETRY_LTM):
 169
 170 ```
 171 serial 0 -4
 172 ```
 173
 174 `serial` can also be used without any argument to print the current configuration of all the serial ports.
 175
 176 ### `timer_output_mode`
 177
 178 Since INAV 7, the firmware can dynamically allocate servo and motor outputs. This removes the need for bespoke targets for special cases (e.g. `MATEKF405` and `MATEKF405_SERVOS6`).
 179
 180 #### Syntax
 181
 182 ```
 183 timer_output_mode [timer [function]]
 184 ```
 185 where:
 186 * Without parameters, lists the current timers and modes
 187 * With just a `timer` lists the mode for that timer
 188 * With both `timer` and `function`, sets the function for that timers
 189
 190 Note:
 191
 192 * `timer` identifies the timer **index** (from 0); thus is one less than the corresponding `TIMn` definition in a target's `target.c`.
 193 * The function is one of `AUTO` (the default), `MOTORS` or `SERVOS`.
 194
 195 Motors are allocated first, hence having a servo before a motor may require use of `timer_output_mode`.
 196
 197 #### Example
 198
 199 The original `MATEKF405` target defined a multi-rotor (MR) servo on output S1. The later `MATEKF405_SERVOS6` target defined (for MR) S1 as a motor and S6 as a servo. This was more logical, but annoying for anyone who had a legacy `MATEKF405` tricopter with the servo on S1.
 200
 201 #### Solution
 202
 203 There is now a single `MATEKF405` target. The `target.c` sets the relevant  outputs as:
 204
 205 ```
 206 DEF_TIM(TIM3, CH1, PC6,  TIM_USE_OUTPUT_AUTO, 0, 0), // S1
 207 DEF_TIM(TIM8, CH2, PC7,  TIM_USE_OUTPUT_AUTO, 0, 1), // S2  UP(2,1)
 208 DEF_TIM(TIM8, CH3, PC8,  TIM_USE_OUTPUT_AUTO, 0, 1), // S3  UP(2,1)
 209 DEF_TIM(TIM8, CH4, PC9,  TIM_USE_OUTPUT_AUTO, 0, 0), // S4  UP(2,1)
 210 DEF_TIM(TIM2, CH1, PA15, TIM_USE_MC_MOTOR | TIM_USE_LED, 0, 0), // S5  UP(1,7)
 211 DEF_TIM(TIM1, CH1, PA8,  TIM_USE_OUTPUT_AUTO, 0, 0), // S6  UP(2,5)
 212 DEF_TIM(TIM4, CH3, PB8,  TIM_USE_OUTPUT_AUTO, 0, 0), // S7  D(1,7)!S5 UP(2,6)
 213 ```
 214
 215 Using the "motors first" allocation, the servo would end up on S6, which in the legacy "tricopter servo on S1" case is not desired.
 216
 217 Forcing the S1 output (`TIM3`) to servo is achieved by:
 218
 219 ```
 220 timer_output_mode 2 SERVOS
 221 ```
 222
 223 with resulting `resource` output:
 224
 225 ```
 226 C06: SERVO4 OUT
 227 C07: MOTOR1 OUT
 228 C08: MOTOR2 OUT
 229 C09: MOTOR3 OUT
 230 ```
 231
 232 Note that the `timer` **index** in the `timer_output_mode` line is one less than the mnemonic in `target.c`, `timer` of 2 for `TIM3`.
 233
 234 Note that the usual caveat that one should not share a timer with both a motor and a servo still apply.
 235
 236 ## Flash chip management
 237
 238 For targets that have a flash data chip, typically used for blackbox logs, the following additional comamnds are provided.
 239
 240 | Command | Effect |
 241 | ------- | ------ |
 242 | `flash_erase` | Erases the  flash chip |
 243 | `flash_info` | Displays flash chip information (used, free etc.) |
 244 | `flash_read <length> <address>` | Reads `length` bytes from `address` |
 245 | `flash_write <address> <data>` | Writes `data` to `address` |
 246
 247 ## CLI Variable Reference
 248 See [Settings.md](Settings.md).