APM学习（10）：数据记录

ArduPilot提供了丰富的数据记录功能，通过AP_Logger来管理数据记录

1. AP_Logger::WriteBlock

程序的数据记录主要通过AP_Logger::WriteBlock()函数来进行，函数原型：

class AP_Logger {
...
	void WriteBlock(const void *pBuffer, uint16_t size);
...
};

表示写入一个大小为size的区块。这个区块为包含数据结构的区块，常用的用法如下

void Plane::Log_Write_AETR()
{
    struct log_AETR pkt = {
        LOG_PACKET_HEADER_INIT(LOG_AETR_MSG)
        ,time_us  : AP_HAL::micros64()
        ,aileron  : SRV_Channels::get_output_scaled(SRV_Channel::k_aileron)
        ,elevator : SRV_Channels::get_output_scaled(SRV_Channel::k_elevator)
        ,throttle : SRV_Channels::get_output_scaled(SRV_Channel::k_throttle)
        ,rudder   : SRV_Channels::get_output_scaled(SRV_Channel::k_rudder)
        ,flap     : SRV_Channels::get_slew_limited_output_scaled(SRV_Channel::k_flap_auto)
        ,steering : SRV_Channels::get_output_scaled(SRV_Channel::k_steering)
        ,speed_scaler : get_speed_scaler(),
        };

    logger.WriteBlock(&pkt, sizeof(pkt));
}

如上为写入一个log_AETR数据结构的例子，表示飞行器的控制信号，结构体log_AETR的数据定义如下

struct PACKED log_AETR {
    LOG_PACKET_HEADER;		//数据块的包头，
    uint64_t time_us;		//时间（微秒）
    float aileron;			//滚转控制
    float elevator;			//俯仰控制
    float throttle;			//油门
    float rudder;			//偏航控制
    float flap;				//襟翼输出
    float steering;			//转向控制
    float speed_scaler;		//速度缩放因子
};

其中，LOG_PACKET_HEADER为数据包头，定义为两个字符的起头和一个msgid，如下

#define LOG_PACKET_HEADER	       uint8_t head1, head2, msgid;

对于不同类型的数据记录，msgid不同，对于log_AETR结构，包头数据为

LOG_PACKET_HEADER_INIT(LOG_AETR_MSG)

其中

#define LOG_PACKET_HEADER_INIT(id) head1 : HEAD_BYTE1, head2 : HEAD_BYTE2, msgid : id

表示两个起头字符HEAD_BYTE1和HEAD_BYTE2，它们的定义如下

#define HEAD_BYTE1  0xA3    // Decimal 163
#define HEAD_BYTE2  0x95    // Decimal 149

msgid为LOG_AETR_MSG，定义在一个枚举类型（enum）中

enum log_messages {
	...
    LOG_AETR_MSG,
    ...
};

这样就完成了一个数据块的写入，数据块的含义由msgid确认，每一个msgid对应了数据块的内容。

2. LogStructure

所有数据块的内容在Plane::log_structure[]中定义，Plane::log_structure是一个数组，记录了所有数据记录类型的含义，通常定义如下

const struct LogStructure Plane::log_structure[] = {
	log_structure item1,
	log_structure item2,
	...
	{ LOG_AETR_MSG, sizeof(log_AETR), 
	"AETR", "Qfffffff",  "TimeUS,Ail,Elev,Thr,Rudd,Flap,Steer,SS", "s-------", "F-------" , true },
	...
}

每一行为一个数据记录类型的定义，分别对应不同类型的数据记录内容，LOG_AETR_MSG也为其中的一行，LogStructure的定义如下

struct LogStructure {
    uint8_t msg_type;			//数据记录类型
    uint8_t msg_len;			//数据记录长度
    const char *name;			//数据记录名称
    const char *format;			//数据记录格式
    const char *labels;			//数据项标签
    const char *units;			//数据项单位
    const char *multipliers;	//数据项比例因子
    bool streaming; 			//是否可限制写入速度
};

对应LOG_AETR_MSG数据，含义如下

msg_type:		LOG_AETR_MSG			//数据记录id
msg_len:		sizeof(log_AETR)		//数据块大小
name:			"AETR"					//数据类型名称
format:			"Qfffffff"				//数据项类型，Q表示uint64_t,f表示float
labels:			"TimeUS,Ail,Elev,Thr,Rudd,Flap,Steer,SS"		//数据项标签
units:			"s-------"				//数据项单位
multipliers:	"F-------"				//数据项乘数因子
streaming:		true					//是否可以限制写入速度（允许WriteStreaming）

其中数据项格式类型定义如下

数据项单位定义如下

乘数因子的字符定义如下

3. 数据记录的查看

ArduPilot的数据记录功能会在飞机飞行结束后产生.bin数据日志文件，通常通过MissionPlanner地面站程序来查看数据日志文件
如上，在MissionPlanner窗口的左侧选项卡中选择DataFlash Logs，然后选择Review a Log，就可以选择对应的数据日志文件（.bin）打开，出现数据日志窗口如下

如图，右侧包含所有的数据记录，其中就包括AETR数据记录，展开AETR，会列出AETR包含的所有数据项，勾选对应的数据项，就会在左侧数据窗口显示数据曲线。其中横坐标为时间，纵坐标为对应数据变量的数值。

4. 新增数据记录

在ArduPilot中新增一项数据记录，可以按照如下

1）新增数据结构定义
新增需要记录的数据结构定义，比如新增一个debug类型的数据结构记录，在LogStructure.h中增加如下数据结构定义

struct PACKED log_debug {
    LOG_PACKET_HEADER;
    uint64_t time_us;
    float data1;
    float data2;
    float data3;
    float data4;
    float data5;
    float data6;
};

表示新增的数据记录结构，其中包含时间（微秒）和6个数据记录项

2）新增数据结构描述
新增对应的数据结构描述

#define LOG_STRUCTURE_DEBUG \
    { LOG_DEBUG_MSG, sizeof(log_debug), \
      "DBG", "Qffffff",  "TimeUS, Data1, Data2, Data3, Data4, Data5, Data6", "s------", "F------" , true },

其中LOG_DEBUG_MSG为数据记录的ID，可以把它放到enum LogMessages中，如下

enum LogMessages: uint8_t {
	...
	LOG_DEBUG_MSG,
	...
	_LOG_LAST_MSG_
};

其中_LOG_LAST_MSG_表示最后一个消息项。数据结构描述可以放在LOG_COMMON_STRUCTURES的末尾，表示为常用的数据记录结构，如下

#define LOG_COMMON_STRUCTURES \
...
LOG_STRUCTURE_DEBUG

LOG_COMMON_STRUCTURES是定义在Plane::log_structure列表中的，如下

const struct LogStructure Plane::log_structure[] = {
    LOG_COMMON_STRUCTURES,
    ...

这样就可以进行数据记录了。

3）数据记录
在进行上述数据记录定义后，可在程序中进行数据记录的操作了，大致如下

	float data1, data2, data3, data4, data5, data6;
	...		//fill content of data1-data6
	
	log_debug pkt {
	    LOG_PACKET_HEADER_INIT(LOG_DEBUG_MSG),
	    time_us : AP_HAL::micros64(),
	    data1   : data1,
	    data2   : data2,
	    data3   : data3,
	    data4   : data4,
	    data5   : data5,
	    data6   : data6
	};
	
	AP::logger().WriteBlock(&pkt, sizeof(log_debug));

申明一个log_debug的数据变量pkg，把需要记录数据内容填进去，再调用AP_Logger::WriteBlock()函数就可以记录对应数据了。新增的数据记录可以在产生的飞行日志文件（.bin）中通过MissionPlanner等工具来查看。