Reprint: Pixhawk Source note five: storage and EEPROM management

Turn from: Sina @walkant

Part VI Storage and EEPROM Management

Detailed reference: http://dev.ardupilot.com/wiki/learning-ardupilot-storage-and-eeprom-management/

User parameters, waypoints, staging points, map data, and other useful information need to be stored. The Ardupilot provides 4 basic storage interfaces:

1,ap_hal::storage object: hal.storage;

2,storagemanager library , is hal.storage more high-level package;

3,DataFlash for log storage;

4,Posix IO function , is a traditional file system read and write function.

Other libraries for storing information permanently are based on the above 4 implementations. For example: the Ap_param library (for handling user configurable parameters) is built on top of the StorageManager library, while the StorageManager library is based on Ap_hal::storage. The Ap_terrain library (for processing terrain data) is built on the POSIX IO functions for manipulating the terrain database.

1. Ap_hal::storage Library

The Ap_hal::storage object is suitable for all ardupilot hardware platforms. Minimum support for 4096 bytes of storage, some similar PX4V1 board has 8 K Eeprom,pixhawk 16K FRAM. All of this is encapsulated in the Ap_hal::storage API.

Hal.storage API, very simple, only 3 functions:

1, init (), initialize the storage system;

2, Read_block (), read block data;

3, Write_block (), write block data.

It's so simple because the APM team encourages developers to use the StorageManager API instead of Hal.storage. It is convenient to use Hal.storage when code is ported or debugged (original: You should just be delving to hal.storage when doing bringup of a new board, or when D Ebugging.).

The size of the storage space, as defined in the hal_storage_size macro in the ap_hal/ap_hal_boards.h file, is as follows:

#define Config_hal_board_subtype HAL_BOARD_SUBTYPE_PX4_V2

#define hal_storage_size 16384//Storage space 16KB

#endif

In other words, we do not support the definition of dynamic storage space. If you want to use dynamic storage space, you can use Posix IO.

2. StorageManager Library

The Hal.storage API is simple when porting Ardupilot code to a new hardware board, but it is less useful when operating the store. We will use StorageManager. The StorageManager library provides access to the storage area "pseudo-contiguous blocks" (typically used for different functions and purposes). That's why we have different functions assigned to the storage area:

1, parameter area;

2, the flight area limit point data area;

3. Waypoint data area;

4. Aggregation point data area.

See also: libraries/storagemanager/storagemanager.cpp, we can see the partitioning of the storage area:

Const Storagemanager::storagearea Storagemanager::layout_copter[storage_num_areas] Progmem = {

------------------------0-4096 is assigned to the AVR version of APM

{storageparam, 0, 1536},//0x600 param bytes

{storagemission, 1536, 2422},

{storagerally, 3958, Rally},//6 points

{storagefence, 4048, fence},//6 points

#if Storage_num_areas >= 8

------------------------4096-8192 assigned to the PX4 version

{Storageparam, 4096, 1280},

{storagerally, 5376, 300},

{storagefence, 5676, 256},

{storagemission, 5932, 2132},//Leave Byte gap for

Expansion and PX4 Sentinal

#endif

#if storage_num_areas >=//Pixhawk

------------------------8192-16384 assigned to the Pixhawk version

{Storageparam, 8192, 1280},//type offset length

{storagerally, 9472, 300},

{storagefence, 9772, 256},

{storagemission, 10028, 6228},//Leave Byte gap for expansion

#endif

};

For the above storage distribution, we can observe that the AVR version with the storage address is 0-4095, and PX4 use the address is 4096-8191,pixhawk used to address is 8192-16383. Such a structure is intended to be better compatible with previous versions. As a result, when the user updates the latest firmware, all previously configured parameters will not change and will continue to function.

The StorageManager API also provides read and write access to similar integers, and this API is used in ap_mission to store and restore waypoint data.

The correlation routines (libraries/storagemanager/examples/storagetest.pde) test the Stoagemanager layer and the Ap_hal::storage object. It has random IO operations on random offsets and random lengths. This also means that cross-border access may occur. This routine is useful for rigorous testing of the StorageManager API and is also extremely useful for porting ardupilot to a new hardware platform because it rigorously tests the access functions of the EEPROM.

Note that Storagetest is a destructive test that will delete the parameters and waypoints you previously stored. Be sure to remember to back up your configuration before testing.

The declaration of the stored object is generally as follows:

Storageaccess ap_param::_storage (Storagemanager::storageparam);

Or

Storageaccess ap_rally::_storage (storagemanager::storagerally);

Storageaccess ap_mission::_storage (storagemanager::storagemission);

Storageaccess ap_limit_geofence::_storage (storagemanager::storagefence);

3. DataFlash Library

Another type of storage is the flight log storage, which is based on the DataFlash library. The name of this library looks a little strange, in fact, the library was originally designed for the APM1 DataFlash chip, it is a hardware driver library, and then slowly evolved into a general-purpose log system, which can be found in the code (these are traces of the previous, Not the best way to implement the code).

The DataFlash API is now primarily used to implement log storage. It allows you to customize the data structure of the log messages. For example, GPS messages are used to record log data for GPS sensors. It can store this data very efficiently, and it also provides APIs for other libraries for log callbacks and downloads.

The log data structure is custom, and its structure allows you to view the FMT messages for the log files. The format in which the FMT message should be stored in other data.

Related Routines Libraries/dataflash/examples/dataflash_test/dataflash_test.pde. The storage structure and data format of the data are described here. Here's a brief list:

1th , in the. log file, we can see the expression in the following format:

FMT, Type,length,name,format,columns, Bbnnz, FMT,

FMT, 129, 23°c, PARM, Nf, Name,value

FMT, Bihbclleeeefi,status,timems,week,nsats,hdop,lat,lng,relalt,alt,spd,gcrs,vz,t, GPS,

FMT, 131, IFFFFFF, IMU, TIMEMS,GYRX,GYRY,GYRZ,ACCX,ACCY,ACCZ

FMT, PPI,%, MSG, Z, Message

2nd , the above format, the corresponding code (see DATAFLASH.H):

#define Log_base_structures \

{log_format_msg, sizeof (Log_format), \

"FMT", "Bbnnz", "type,length,name,format,columns"}, \

{log_parameter_msg, sizeof (log_parameter), \

"PARM", "Nf", "Name,value"}, \

{log_gps_msg, sizeof (LOG_GPS), \

"GPS", "Bihbclleeeefi", "status,timems,week,nsats,hdop,lat,lng,relalt,alt,spd,gcrs,vz,t"}, \

{log_imu_msg, sizeof (LOG_IMU), \

"IMU", "Iffffff", "Timems,gyrx,gyry,gyrz,accx,accy,accz"}, \

The above structure, take log_imu_msg as an example to explain:

sizeof ()

valign= width= "Top" Log_imu "" >

Information type ID	Data size	Information name	Data type	Data 1	Data 3	Data 4	Data 5	Data	Data 7
log_imu_msg	IMU	Iffffff	Timems	Gyrx	Gyry	Gyrz	ACCX	Accy	Accz
131	31 (bytes)	Imu	L: Integral type; F: Floating point	Integral type 46481	0.000703	-0.000190	-0.000359	-0.133995	0.034236	-9.748702

3rd , a log file (. log) is one of the following data:

IMU, 46481, 0.000703,-0.000190,-0.000359,-0.133995, 0.034236,-9.748702

4th , the definition of the message type:

Message types for common messages

Message type,, corresponding to the type of message in FMT, see log file. log file.

#define LOG_FORMAT_MSG 128

#define LOG_PARAMETER_MSG 129

#define LOG_GPS_MSG 130

#define LOG_IMU_MSG 131

#define LOG_MESSAGE_MSG 132

#define LOG_RCIN_MSG 133

#define LOG_RCOUT_MSG 134

#define LOG_IMU2_MSG 135

...

5th , the structure of Log_imu, occupies 3 + 4 + + + = bytes .

struct PACKED log_imu {

Log_packet_header; 3

uint32_t timestamp; 4

Float gyro_x, gyro_y, gyro_z; 4*3 = 12

Float accel_x, accel_y, accel_z; 4*3 = 12

};

6th : If you want to add a custom data structure, you can add as much code as the following.

#define LOG_TEST_MSG 1

struct PACKED log_test {

Log_packet_header;

uint16_t v1, v2, v3, v4;

int32_t L1, L2;

};

static const struct Logstructure log_structure[] Progmem = {

Log_common_structures,

{log_test_msg, sizeof (log_test),// Add custom Format data

"TEST", "hhhhii", "V1,V2,V3,V4,L1,L2"}// Add custom Format data

};

7th : Concrete Data structure operation

DataFlash. Init (Log_structure, sizeof (log_structure)/sizeof (log_structure[0]));

Log_num = DataFlash. Startnewlog ();

DataFlash. WriteBlock (&pkt, sizeof (PKT));

The DataFlash API hides the details of how the underlying log file is stored. In addition, for Posix IO-capable systems such as Pixhawk or Linux, log files are stored in the "LOGS" directory of the microSD card. The user can directly extract the SD card and copy it directly to the computer.

4. Posix IO

Some boards are with operating systems and support similar POSIX APIs such as Linux and Nuttx. The Ap_terrain library is a typical example. Terrain data is very large for EEPROM and is often stored randomly. DataFlash API is not flexible enough, and POSIX IO support, there is no need to use DataFlash anymore.

To view the ap_hal_boards.h file, confirm that the HAL_OS_POSIX_IO macro is defined as follows:

#define hal_os_posix_io 1//With file system, has posix-like filesystem IO

The log and TERRAIN file storage paths are given below:

#define Hal_board_log_directory "/fs/microsd/apm/logs"//log file address

#define Hal_board_terrain_directory "/fs/microsd/apm/terrain"//surface, Terrain file address

With the above information, the POSIX IO feature is supported, and it should also be noted that:

1, Posix io function, intelligent through the IO timer timer, or other low-priority thread calls. IO Thread Priority 59.

2, do not call through other APIs directly, even the simple stat () function, can not, unless you are too handsome.

3, as little storage, storage data length is small, as far as possible with seek (search) function.

Very simple, a principle, not too time consuming, affect the flight control code execution. A simple IO operation for an SD card can take a second, which is enough time for your aircraft to flip, drop vertically, and fry the chicken directly. Pixhawk SD card Read and write operation typically a few milliseconds, and occasionally take a long time. Now, you know how to do this?

For the relevant routines Libraries/ap_terrain/terrainio.cpp, we will find that the state machine that processes the IO is called through Ap_terrain::io_timer.

Reprint: Pixhawk Source note five: storage and EEPROM management