Rust嵌入式日志解码库defmt-decoder使用指南

简介

defmt-decoder是一个用于解析和转换defmt格式二进制日志数据的Rust库。defmt（"deferred formatting"的缩写）是专为嵌入式系统设计的高效日志框架，而defmt-decoder则用于在主机端解码这些日志数据。

主要特性

• 高效解析defmt格式的二进制日志
• 支持从ELF文件中提取类型信息
• 提供多种输出格式选项
• 与defmt日志框架无缝集成

安装方法

在Cargo.toml中添加依赖：

[dependencies]
defmt-decoder = "0.3"

基本使用方法

1. 从ELF文件创建表

use defmt_decoder::Table;

// 读取ELF文件并解析为表
let elf = std::fs::read("path/to/your/firmware.elf")?;
let table = Table::parse(&elf)?;

2. 解码日志数据

use defmt_decoder::{log::LevelFilter, DefmtStream, StreamDecoder};

let bytes = /* 从串口或文件读取的defmt二进制数据 */;
let mut stream = DefmtStream::new(bytes, &table);
let mut decoder = StreamDecoder::new(&mut stream);

// 解码并打印每一帧日志
while let Some(frame) = decoder.decode()? {
    println!("{}", frame.display(false));
}

3. 过滤日志级别

use defmt_decoder::log::LevelFilter;

// 只解码Info及以上级别的日志
let mut decoder = StreamDecoder::new(&mut stream)
    .with_max_level(LevelFilter::Info);

高级用法

从串口实时解码

use serialport::SerialPort;

// 打开串口
let port = serialport::new("/dev/ttyUSB0", 115_200)
    .open()
    .expect("Failed to open port");

// 创建流和解码器
let mut stream = DefmtStream::new(port, &table);
let mut decoder = StreamDecoder::new(&mut stream);

// 实时解码循环
loop {
    if let Some(frame) = decoder.decode().expect("Decoding failed") {
        println!("{}", frame.display(false));
    }
}

保存解码日志到文件

use std::fs::File;
use std::io::Write;

// 创建输出文件
let mut output = File::create("decoded.log")?;

// 解码并写入文件
while let Some(frame) = decoder.decode()? {
    writeln!(output, "{}", frame.display(false))?;
}

命令行工具

defmt-decoder也可以作为命令行工具使用：

1. 安装：

cargo install defmt-decoder

1. 基本使用：

defmt-decoder firmware.elf < input.bin > output.txt

1. 从串口读取：

defmt-decoder firmware.elf --serial /dev/ttyUSB0 --baud 115200

注意事项

1. 确保使用的ELF文件与生成日志的固件完全匹配
2. 对于实时解码，建议使用适当的缓冲策略
3. 如果日志格式不匹配，可能需要检查defmt版本兼容性

示例项目结构

典型的嵌入式项目使用defmt和defmt-decoder的结构：

my-embedded-project/
├── firmware/
│   ├── src/
│   │   └── main.rs  # 使用defmt日志宏
│   └── Cargo.toml   # 依赖defmt
└── host-tools/
    ├── src/
    │   └── main.rs  # 使用defmt-decoder
    └── Cargo.toml   # 依赖defmt-decoder

完整示例demo

以下是使用defmt-decoder的完整示例代码：

use defmt_decoder::{log::LevelFilter, DefmtStream, StreamDecoder, Table};
use serialport::SerialPort;
use std::{fs::File, io::Write, error::Error};

fn main() -> Result<(), Box<dyn Error>> {
    // 1. 从ELF文件创建表
    let elf = std::fs::read("target/thumbv7m-none-eabi/debug/firmware")?;
    let table = Table::parse(&elf)?;
    
    // 2. 打开串口
    let port = serialport::new("/dev/ttyACM0", 115_200)
        .timeout(std::time::Duration::from_millis(1000))
        .open()?;
    
    // 3. 创建日志文件
    let mut log_file = File::create("device_logs.txt")?;
    
    // 4. 创建流和解码器
    let mut stream = DefmtStream::new(port, &table);
    let mut decoder = StreamDecoder::new(&mut stream)
        .with_max_level(LevelFilter::Debug);
    
    // 5. 主解码循环
    loop {
        match decoder.decode() {
            Ok(Some(frame)) => {
                let log_entry = frame.display(false);
                println!("{}", log_entry);  // 打印到控制台
                writeln!(log_file, "{}", log_entry)?;  // 写入文件
            }
            Ok(None) => continue,
            Err(e) => eprintln!("解码错误: {}", e),
        }
    }
}

这个完整示例展示了如何：

1. 从ELF文件加载类型信息
2. 配置串口连接
3. 创建日志文件
4. 设置日志级别过滤
5. 实现实时解码循环，同时输出到控制台和日志文件

要使用此示例，您需要：

1. 在Cargo.toml中添加依赖：

[dependencies]
defmt-decoder = "0.3"
serialport = "4.2"

1. 确保有正确的ELF文件和串口设备路径