docs/Blackbox.md

   1 # Blackbox flight data recorder
   2
   3 ![Rendered flight log frame](Screenshots/blackbox-screenshot-1.jpg)
   4
   5 ## Introduction
   6
   7 This feature transmits your flight data information on every control loop iteration over a serial port to an external
   8 logging device to be recorded, or to a dataflash chip which is present on some flight controllers.
   9
  10 After your flight, you can view the resulting logs using the interactive log viewer:
  11
  12 https://github.com/iNavFlight/blackbox-log-viewer
  13
  14 You can also use the `blackbox_decode` tool to turn the logs into CSV files for analysis, or render your flight log as a
  15 video using the `blackbox_render` tool. Those tools can be found in this repository:
  16
  17 https://github.com/cleanflight/blackbox-tools
  18
  19 ## Logged data
  20 The blackbox records flight data on every iteration of the flight control loop. It records the current time in
  21 microseconds, P, I and D corrections for each axis, your RC command stick positions (after applying expo curves),
  22 gyroscope data, accelerometer data (after your configured low-pass filtering), barometer and rangefinder readings, 3-axis
  23 magnetometer readings, raw VBAT and current measurements, RSSI, and the command being sent to each motor speed
  24 controller. This is all stored without any approximation or loss of precision, so even quite subtle problems should be
  25 detectable from the fight data log.
  26
  27 GPS data is logged whenever new GPS data is available. Although the CSV decoder will decode this data, the video
  28 renderer does not yet show any of the GPS information (this will be added later).
  29
  30 ## Supported configurations
  31
  32 The maximum data rate that can be recorded to the flight log is fairly restricted, so anything that increases the load
  33 can cause the flight log to drop frames and contain errors.
  34
  35 The Blackbox is typically used on tricopters and quadcopters. Although it will work on hexacopters and octocopters,
  36 because these craft have more motors to record, they must transmit more data to the flight log. This can increase the
  37 number of dropped frames. Although the browser-based log viewer supports hexacopters and octocopters, the command-line
  38 `blackbox_render` tool currently only supports tri- and quadcopters.
  39
  40 INAV's `looptime` setting decides how frequently an update is saved to the flight log. The default looptime on
  41 INAV is 2000us. If you're using a looptime smaller than about 2400, you may experience some dropped frames due to
  42 the high required data rate. In that case you will need to reduce the sampling rate in the Blackbox settings, or
  43 increase your logger's baudrate to 250000. See the later section on configuring the Blackbox feature for details.
  44
  45 ## Setting up logging
  46
  47 First, you must enable the Blackbox feature. In the [INAV Configurator][] enter the Configuration tab,
  48 tick the "BLACKBOX" feature at the bottom of the page, and click "Save and reboot"
  49
  50 Now you must decide which device to store your flight logs on. You can either transmit the log data over a serial port
  51 to an external logging device like the [OpenLog serial data logger][] to be recorded to a microSDHC card, or if you have
  52 a compatible flight controller you can store the logs on the onboard dataflash storage instead.
  53
  54 ### OpenLog serial data logger
  55
  56 The OpenLog is a small logging device which attaches to your flight controller using a serial port and logs your
  57 flights to a MicroSD card.
  58
  59 The OpenLog ships from SparkFun with standard "OpenLog 3" firmware installed. Although this original OpenLog firmware
  60 will work with the Blackbox, in order to reduce the number of dropped frames it should be reflashed with the
  61 higher performance [OpenLog Blackbox firmware][]. The special Blackbox variant of the OpenLog firmware also ensures that
  62 the OpenLog is using INAV compatible settings, and defaults to 115200 baud.
  63
  64 You can find the Blackbox version of the OpenLog firmware [here](https://github.com/cleanflight/blackbox-firmware),
  65 along with instructions for installing it onto your OpenLog.
  66
  67 [OpenLog serial data logger]: https://www.sparkfun.com/products/9530
  68 [OpenLog Blackbox firmware]: https://github.com/cleanflight/blackbox-firmware
  69
  70 #### microSDHC
  71
  72 Your choice of microSDHC card is very important to the performance of the system. The OpenLog relies on being able to
  73 make many small writes to the card with minimal delay, which not every card is good at. A faster SD-card speed rating is
  74 not a guarantee of better performance.
  75
  76 ##### microSDHC cards known to have poor performance
  77
  78  - Generic 4GB Class 4 microSDHC card - the rate of missing frames is about 1%, and is concentrated around the most
  79    interesting parts of the log!
  80  - Sandisk Ultra 32GB (unlike the smaller 16GB version, this version has poor write latency)
  81
  82 ##### microSDHC cards known to have good performance
  83
  84  - Transcend 16GB Class 10 UHS-I microSDHC (typical error rate < 0.1%)
  85  - Sandisk Extreme 16GB Class 10 UHS-I microSDHC (typical error rate < 0.1%)
  86  - Sandisk Ultra 16GB (it performs only half as well as the Extreme in theory, but still very good)
  87
  88 You should format any card you use with the [SD Association's special formatting tool][] , as it will give the OpenLog
  89 the best chance of writing at high speed. You must format it with either FAT, or with FAT32 (recommended).
  90
  91 [SD Association's special formatting tool]: https://www.sdcard.org/downloads/formatter_4/
  92
  93 ### Choosing a serial port for the OpenLog
  94 First, tell the Blackbox to log using a serial port (rather than to an onboard dataflash chip). Go to the
  95 Configurator's CLI tab, enter `set blackbox_device=SERIAL` to switch logging to serial, and
  96 save.
  97
  98 You need to let INAV know which of [your serial ports][] you connect your OpenLog to (i.e. the Blackbox port),
  99 which you can do on the Configurator's Ports tab.
 100
 101 You should use a hardware serial port. SoftSerial ports can be used for the Blackbox. However, because they are limited to 19200 baud, your logging
 102 rate will need to be severely reduced to compensate. Therefore the use of SoftSerial is not recommended.
 103
 104 When using a hardware serial port, Blackbox should be set to at least 115200 baud on that port. When using fast
 105 looptimes (<2500), a baud rate of 250000 should be used instead in order to reduce dropped frames.
 106
 107 The serial port used for Blackbox cannot be shared with any other function (e.g. GPS, telemetry) except the MSP
 108 protocol. If MSP is used on the same port as Blackbox, then MSP will be active when the board is disarmed, and Blackbox
 109 will be active when the board is armed. This will mean that you can't use the Configurator or any other function that
 110 requires MSP, such as an OSD or a Bluetooth wireless configuration app, while the board is armed.
 111
 112 Connect the "TX" pin of the serial port you've chosen to the OpenLog's "RXI" pin. Don't connect the serial port's RX
 113 pin to the OpenLog, as this will cause the OpenLog to interfere with any shared functions on the serial port while
 114 disarmed.
 115
 116 The key criteria to choose a serial port are:
 117
 118 * Should be a hardware serial port rather than SoftSerial.
 119 * Cannot be shared with any other function (GPS, telemetry) except MSP.
 120 * If MSP is used on the same UART, MSP will stop working when the board is armed.
 121
 122 #### OpenLog configuration
 123
 124 Power up the OpenLog with a microSD card inside, wait 10 seconds or so, then power it down and plug the microSD card
 125 into your computer. You should find a "CONFIG.TXT" file on the card, open it up in a text editor. You should see the
 126 baud rate that the OpenLog has been configured for (usually 115200 or 9600 from the factory). Set the baud rate to match
 127 the rate you entered for the Blackbox in the Configurator's Port tab (typically 115200 or 250000).
 128
 129 Save the file and put the card back into your OpenLog, it will use those settings from now on.
 130
 131 If your OpenLog didn't write a CONFIG.TXT file, create a CONFIG.TXT file with these contents and store it in the root
 132 of the MicroSD card:
 133
 134 ```
 135 115200
 136 baud
 137 ```
 138
 139 If you are using the original OpenLog firmware, use this configuration instead:
 140
 141 ```
 142 115200,26,0,0,1,0,1
 143 baud,escape,esc#,mode,verb,echo,ignoreRX
 144 ```
 145
 146 #### OpenLog protection
 147
 148 The OpenLog can be wrapped in black electrical tape or heat-shrink in order to insulate it from conductive frames (like
 149 carbon fiber), but this makes its status LEDs impossible to see. I recommend wrapping it with some clear heatshrink
 150 tubing instead.
 151
 152 ![OpenLog installed](Wiring/blackbox-installation-1.jpg "OpenLog installed with double-sided tape, SDCard slot pointing outward")
 153
 154 ### Onboard dataflash storage
 155 Some flight controllers have an onboard SPI NOR dataflash chip which can be used to store flight logs instead of using
 156 an OpenLog.
 157
 158 The SPRacingF3 has a 8 megabyte dataflash chip onboard which allows for longer recording times.
 159
 160 These chips are also supported:
 161
 162 * Micron/ST M25P16 - 16 Mbit / 2 MByte
 163 * Micron N25Q064 - 64 Mbit / 8 MByte
 164 * Winbond W25Q64 - 64 Mbit / 8 MByte
 165 * Micron N25Q0128 - 128 Mbit / 16 MByte
 166 * Winbond W25Q128 - 128 Mbit / 16 MByte
 167
 168 #### Enable recording to dataflash
 169 On the Configurator's CLI tab, you must enter `set blackbox_device=SPIFLASH` to switch to logging to an onboard dataflash chip,
 170 then save.
 171
 172 [your serial ports]: https://github.com/iNavFlight/inav/blob/master/docs/Serial.md
 173 [INAV Configurator]: https://chrome.google.com/webstore/detail/inav-configurator/fmaidjmgkdkpafmbnmigkpdnpdhopgel
 174
 175 ## Configuring the Blackbox
 176
 177 The Blackbox currently provides two settings (`blackbox_rate_num` and `blackbox_rate_denom`) that allow you to control
 178 the rate at which data is logged. These two together form a fraction (`blackbox_rate_num / blackbox_rate_denom`) which
 179 decides what portion of the flight controller's control loop iterations should be logged. The default is 1/1 which logs
 180 every iteration.
 181
 182 If you're using a slower MicroSD card, you may need to reduce your logging rate to reduce the number of corrupted
 183 logged frames that `blackbox_decode` complains about. A rate of 1/2 is likely to work for most craft.
 184
 185 You can change the logging rate settings by entering the CLI tab in the [INAV Configurator][] and using the `set`
 186 command, like so:
 187
 188 ```
 189 set blackbox_rate_num = 1
 190 set blackbox_rate_denom = 2
 191 ```
 192
 193 The data rate for my quadcopter using a looptime of 2400 and a rate of 1/1 is about 10.25kB/s. This allows about 18
 194 days of flight logs to fit on my OpenLog's 16GB MicroSD card, which ought to be enough for anybody :).
 195
 196 If you are logging using SoftSerial, you will almost certainly need to reduce your logging rate to 1/32. Even at that
 197 logging rate, looptimes faster than about 1000 cannot be successfully logged.
 198
 199 If you're logging to an onboard dataflash chip instead of an OpenLog, be aware that the 2MB of storage space it offers
 200 is pretty small. At the default 1/1 logging rate, and a 2400 looptime, this is only enough for about 3 minutes of
 201 flight. This could be long enough for you to investigate some flying problem with your craft, but you may want to reduce
 202 the logging rate in order to extend your recording time.
 203
 204 To maximize your recording time, you could drop the rate all the way down to 1/32 (the smallest possible rate) which
 205 would result in a logging rate of about 10-20Hz and about 650 bytes/second of data. At that logging rate, a 2MB
 206 dataflash chip can store around 50 minutes of flight data, though the level of detail is severely reduced and you could
 207 not diagnose flight problems like vibration or PID setting issues.
 208
 209 ## Usage
 210
 211 The Blackbox starts recording data as soon as you arm your craft, and stops when you disarm.
 212
 213 If your craft has a buzzer attached, you can use INAV's arming beep to synchronize your Blackbox log with your
 214 flight video. INAV's arming beep is a "long, short" pattern. The beginning of the first long beep will be shown
 215 as a blue line in the flight data log, which you can sync against your recorded audio track.
 216
 217 You should wait a few seconds after disarming your craft to allow the Blackbox to finish saving its data.
 218
 219 ### Usage - OpenLog
 220 Each time the OpenLog is power-cycled, it begins a fresh new log file. If you arm and disarm several times without
 221 cycling the power (recording several flights), those logs will be combined together into one file. The command line
 222 tools will ask you to pick which one of these flights you want to display/decode.
 223
 224 Don't insert or remove the SD card while the OpenLog is powered up.
 225
 226 ### Usage - Dataflash chip
 227 After your flights, you can use the [INAV Configurator][] to download the contents of the dataflash to your
 228 computer. Go to the "dataflash" tab and click the "save flash to file..." button. Saving the log can take 2 or 3
 229 minutes.
 230
 231 ![Dataflash tab in Configurator](Screenshots/blackbox-dataflash.png)
 232
 233 After downloading the log, be sure to erase the chip to make it ready for reuse by clicking the "erase flash" button.
 234
 235 If you try to start recording a new flight when the dataflash is already full, Blackbox logging will be disabled and
 236 nothing will be recorded.
 237
 238 ### Usage - Logging switch
 239 If you're recording to an onboard flash chip, you probably want to disable Blackbox recording when not required in order
 240 to save storage space. To do this, you can add a Blackbox flight mode to one of your AUX channels on the Configurator's
 241 modes tab. Once you've added a mode, Blackbox will only log flight data when the mode is active.
 242
 243 A log header will always be recorded at arming time, even if logging is paused. You can freely pause and resume logging
 244 while in flight.
 245
 246 ## Viewing recorded logs
 247 After your flights, you'll have a series of flight log files with a .TXT extension.
 248
 249 You can view these .TXT flight log files interactively using your web browser with the INAV Blackbox Explorer:
 250
 251 https://github.com/iNavFlight/blackbox-log-viewer
 252
 253 This allows you to scroll around a graphed version of your log and examine your log in detail. You can also export a
 254 video of your log to share it with others!
 255
 256 You can decode your logs with the `blackbox_decode` tool to create CSV (comma-separated values) files for analysis,
 257 or render them into a series of PNG frames with `blackbox_render` tool, which you could then convert into a video using
 258 another software package.
 259
 260 You'll find those tools along with instructions for using them in this repository:
 261
 262 https://github.com/iNavFlight/blackbox-log-viewer