ardupilot/libraries/AP_Filesystem/README.md

AP_Filesystem: The ArduPilot virtual filesystem layer

AP_Filesystem is a filesystem abstraction for ArduPilot that gives ArduPilot access to both local filesystems on the flight controller and a set of virtual filesystem abstractions.

This document is primarily intended to document the VFS interfaces available to ground station authors via the MAVLink FTP transport.

MAVLink FTP

ArduPilot implements the FILE_TRANSFER_PROTOCOL MAVLink message to allow for remote file operations. This protocol allows a GCS to transfer files to and from a flight controller. It also allows the GCS to access some special purpose VFS interfaces for efficient access to flight controller data using a file API.

The VFS interfaces that don't represent local filesystem objects on the flight controller are prefixed with an '@' symbol. Currently there are two interfaces, the @PARAM interface and the @SYS interface.

FTP Protocol Extension

To facilitate more efficient file transfer over commonly used SiK radios I have added an extension to the ftp burst protocol where the 'size' field in the burst read request sets the block size of the burst replies. This helps as SiK radios do badly with very large packets. I have found that the best results with SiK radios is achieved with a burst read size of 110. If the size field is set to zero then the default of the max size (239) is used.

The @PARAM VFS

The @PARAM VFS allows a GCS to very efficiently download full or partial parameter list from the flight controller. Currently the @PARAM filesystem offers only a single file, called @PARAM/param.pck, which is a packed representation of the full parameter list. Downloading the full parameter list via this interface is a lot faster than using the traditional mavlink parameter messages.

The @PARAM/param.pck file has a special restriction that all reads from the file on a single file handle must be of the same size. This allows the server to ensure that filling in of lost transfers cannot cause a parameter value to be split across a network block, which prevents corruption. Attempts to vary the read size after the first read will return a failed read.

The file format of the @PARAM/param.pck file is as follows

File header

There is a 6 byte header, consisting of 3 uint16_t values

  uint16_t magic # 0x671b
  uint16_t num_params
  uint16_t total_params

The magic value is used to give the version of the packing format. It should have a value of 0x671b. The num_params is how many parameters will be sent (may be less than total if client requests a subset, see query strings below). The total_params is the total number of parameters the flight controller has.

The header is little-endian.

Parameter Block

After the header comes a series of variable length parameter blocks, one per parameter. The format is:

    uint8_t type:4;         // AP_Param type NONE=0, INT8=1, INT16=2, INT32=3, FLOAT=4
    uint8_t flags:4;        // bit 0: default value included, bits 1-3: for future use
    uint8_t common_len:4;   // number of name bytes in common with previous entry, 0..15
    uint8_t name_len:4;     // non-common length of param name -1 (0..15)
    uint8_t name[name_len]; // name
    uint8_t data[];         // value, length given by variable type
    uint8_t default[];      // optional default value, included if flags bit 0 is set

There may be any number of leading zero pad bytes before the start of the parameter block. The pad bytes are added to ensure that a parameter value does not cross a MAVLink FTP block boundary. This padding prevents a re-fetch of a missing block from potentially leading to a corrupt value.

The packing format avoids sending common leading characters of parameter names from the previous parameter. It does this by sending a common_len field which says how many characters should be copied from the previous parameter. This is always zero in the first block in the file.

The name_len field is the number of non-common characters, minus one.

The default value is included only if requested by the withdefaults query string and if different from the set value. Otherwise, flags bit 0 will not be set, and default will be of zero length.

Query Strings

The file name @PARAM/param.pck can optionally be extended with query string elements to change the result. For example:

• @PARAM/param.pck?start=50&count=10

that means to download 10 parameters starting with parameter number 50.

• @PARAM/param.pck?withdefaults=1

that means to include the default values in the returned data, where it is different from the parameter's set value.

Parameter Client Examples

The script Tools/scripts/param_unpack.py can be used to unpack a param.pck file. Additionally the MAVProxy mavproxy_param.py module implements parameter download via ftp.

The @SYS VFS

The @SYS VFS gives access to flight controller internals. For now the only file that is accessible is @SYS/threads.txt which gives information on the remaining stack space for all threads. This file is only accessible for ChibiOS builds.