docs/USB_Mass_Storage_(MSC)_mode.md

   1 ## Overview
   2
   3 iNav (after 2.3.0) offers USB MSC (mass storage device class) SD card and internal flash access, meaning you can mount the FC (SD card / internal flash) as an OS file system via USB to read BB logs (and delete them from an SD card).
   4
   5 When MSC mode is used with **internal flash** there are a few differences compared to **SD card** as it's a virtual file system:
   6
   7 * The file system is read-only. In order to delete logs it is necessary to erase the flash as usual (configurator, CLI or other tool).
   8 * The logs are presented as a single, consolidated file (`inav_all.bbl`) as well as individual logs (`inav_001.bbl` etc.).
   9 * Other informative files (e.g. `readme.txt`) may also exist in the virtual file system.
  10
  11
  12 ## Usage
  13
  14 To put the FC in MSC mode:
  15
  16 * Enter the CLI
  17 * Enter the CLI command `msc` ; the FC will reboot
  18 * Close the CLI tool (`cliterm`, configurator etc.)
  19 * Wait for the device to be recognised as USB storage device by the operating system (may take some time, 10-15 seconds perhaps).
  20 * Copy files off the MSC mounted FC (sd card) (`cp`, file manager)
  21 * Dismount / eject the FC (sd card) card using the standard OS method
  22 * Power-cycle the FC to exit MSC mode.
  23
  24 ## Performance
  25
  26 Internal flash is quite fast.
  27
  28 For an SD card, reading is quite slow, typically c. 340kBs, for example:
  29
  30 ```
  31 ####################
  32 ## Using MSC mode ##
  33 ####################
  34 # FC is automounted to /run/media/jrh/BBOX-QUAD by the OS
  35 $ rsync -P /run/media/jrh/BBOX-QUAD/LOGS/LOG00035.TXT /tmp/msclogs/
  36 LOG00035.TXT
  37      55,856,827 100%  339.15kB/s    0:02:40 (xfr#1, to-chk=0/1)
  38 ```
  39
  40 ```
  41 #########################
  42 ## Using a card-reader ##
  43 #########################
  44 # SD Card is automounted to /run/media/jrh/BBOX-QUAD by the OS
  45 $ rsync -P /run/media/jrh/BBOX-QUAD/LOGS/LOG00035.TXT /tmp/sdclogs/
  46 LOG00035.TXT
  47      55,856,827 100%   19.26MB/s    0:00:02 (xfr#1, to-chk=0/1)
  48 ```
  49 i.e c. 2.5 seconds for the card reader, 2 minutes 40 seconds for MSC (60 times slower). However, if the card is relatively inaccessible, this is a reasonable trade-off
  50
  51 ## Comparison and Integrity
  52
  53 The same file (`LOG00035.TXT`, c 55MB) is copied by MSC to `/tmp/msclogs` and directly (SD Card Reader) to `/tmp/sdclogs`.
  54
  55 ```
  56 $ cmp /tmp/{msc,sdc}logs/LOG00035.TXT
  57 # no differences reported ...
  58 ```
  59
  60 ```
  61 $ md5sum /tmp/{msc,sdc}logs/LOG00035.TXT
  62 7cd259777ba4f29ecbde2f76882b1840  /tmp/msclogs/LOG00035.TXT
  63 7cd259777ba4f29ecbde2f76882b1840  /tmp/sdclogs/LOG00035.TXT
  64 ```
  65 You should also be able to run blackbox utilities (e.g. the iNav specific `blackbox_decode`) without errors on the files, e.g.
  66
  67 ```
  68 $ blackbox_decode --stdout --merge-gps > /dev/null /tmp/msclogs/LOG00035.TXT
  69 Log 1 of 1, start 36:00.888, end 62:00.851, duration 25:59.963
  70
  71 Statistics
  72 Looptime           1006 avg            9.2 std dev (0.9%)
  73 I frames   48405  104.6 bytes avg  5062215 bytes total
  74 P frames  726064   69.2 bytes avg 50246994 bytes total
  75 H frames     380   10.0 bytes avg     3800 bytes total
  76 G frames   15674   21.4 bytes avg   334701 bytes total
  77 S frames    6198   33.0 bytes avg   204534 bytes total
  78 Frames    774469   71.4 bytes avg 55309209 bytes total
  79 Data rate  496Hz  35806 bytes/s     358100 baud
  80
  81 3 frames failed to decode, rendering 4 loop iterations unreadable. 4 iterations are missing in total (4ms, 0.00%)
  82 774472 loop iterations weren't logged because of your blackbox_rate settings (779980ms, 50.00%)
  83 ```
  84 ## Developer Notes
  85
  86 Providing MSC is automatically enabled for all F4 and up targets that support
  87 `ONBOARDFLASH` and /or `SDCARD`.