基于炬芯ATS308X的离线日志存储导出功能实现

没有u盘就检测cdc 串口导出有U盘就U盘方式导出# ATS3089P 离线日志存储与 Windows USB 导出设备默认开启日志采集不需要连接电脑。运行中的串口文本先进入 RAM再由后台线程写入 NAND日志区满后循环覆盖最旧记录。插 USB 后可使用随附 Windows 工具一键导出 TXT反馈给研发。本版固件为 outdir/ats3089p_dev_watch/_firmware/ats3089p_dev_watch_261014_offline_log_v3.fw调试包文件名后缀为 _offline_log_v3_debug.fw。烧录后用普通 UART 输入 app log status应看到 version261014-v3 ready1 enabled1 usb_auto1 auto_boot1各字段之间还会打印容量等信息。首次升级默认开启自动 USB 检测插线后提供 CDC 模拟串口电脑直接请求最新日志。## 1. Python / PowerShell 命令导出1. 将新固件烧入开发板正常使用设备复现问题。2. 设备开机后用 USB **数据线**连接 Windows。3. 打开 PowerShell进入 SDK 根目录 运行下面一条命令。4. 成功后命令会显示电脑保存路径把该 TXT 文件发给研发。powershellpowershell -NoProfile -ExecutionPolicy Bypass -File .\application\bt_watch\tools\offline_log\export_logs.ps1 -OutputDir D:\logs脚本优先调用已打包的 OfflineLogCLI.exe这种方式无需安装 Python找不到 EXE 时调用 Python 源码。不传 -OutputDir 时保存到当前工作目录的 logs 子目录。文件名包含导出时间不覆盖已有文件无需接普通 UART 串口板。默认 auto 模式先扫描已经枚举且包含有效 OFFLOG.TXT/OFFLOG.CRC 的 U 盘这样不需要 CDC也不需要先发送 app udisk on。只有找不到有效 U 盘时才等待 CDC 并请求本次实时导出。v3 固件还支持无盘时自动发送 app log usb 编号设备生成带编号快照并切换为 U 盘。旧版固件使用新工具时仍需先用普通 UART 执行旧的 USB 控制命令。也可以直接使用 Python推荐显式指定电脑保存目录powershellpython .\application\bt_watch\tools\offline_log\offline_log_cli.py --mode auto --output-dir D:\logsPython 方式要求 Python 3.8 或以上。USB 盘导出只需标准库使用 USB CDC 时先安装串口依赖python -m pip install pyserial。python 命令不可用时可尝试 Windows 已安装的 py -3或者使用上面的独立 EXE / PowerShell 方式。手动指定盘符或者 COM 口的完整例子powershellpowershell -NoProfile -ExecutionPolicy Bypass -File .\application\bt_watch\tools\offline_log\export_logs.ps1 -Mode usb -Drive E:\ -OutputDir D:\logspowershell -NoProfile -ExecutionPolicy Bypass -File .\application\bt_watch\tools\offline_log\export_logs.ps1 -Mode cdc -Port COM8 -OutputDir D:\logspython .\application\bt_watch\tools\offline_log\offline_log_cli.py --mode usb --drive E:\ --output-dir D:\logspython .\application\bt_watch\tools\offline_log\offline_log_cli.py --mode cdc --port COM8 --output-dir D:\logs路径带空格或中文时用双引号包住参数例如 -OutputDir D:\客户反馈\设备 A 或 --output-dir D:\客户反馈\设备 A。退出码 0 表示成功失败返回非 0。执行中按 CtrlC 取消临时文件不会作为成功日志保存。CDC 和 USB 盘两条路径均验证长度与 CRC32通过后才发布正式 TXT。校验失败、取消、USB 断开时不会把半截内容显示为导出成功。导出结果为快照生成时已采集到的日志传输过程中继续产生的日志留待下次导出。usb 模式是保留的 U 盘快照读取方式需要设备已处于 U 盘模式。设备进入 U 盘模式前自动生成根目录 OFFLOG.TXT 和 OFFLOG.CRC也可以手动复制这两个文件一起反馈。快照只反映**进入此次 U 盘模式时**的日志。设备保持 U 盘连接期间后台日志仍可保存在独立日志分区需要更新快照时退出并重新进入 U 盘模式。不要在 PC 已接管 U 盘时从板端写快照。如果 USB 盘被 Windows 识别为固定磁盘用 -Mode usb -Drive E:\ / --mode usb --drive E:\ 指定目标盘根目录。默认自动模式仅请求当前 CDC 日志找不到 CDC 时会报错不会把磁盘旧快照当成最新日志。明确指定 Drive 表示读取该盘快照明确指定 Port 表示连接该 COM不要同时指定两个目标。多块开发板同时连接时请指定 -Port COM8。已附带的 outdir/offline_log_tool/dist/OfflineLogExport.exe 窗口为可选入口使用命令行即可完成本版导出。## 2. 普通 UART 控制命令沿用现有普通串口参数在看到 uart:~$ 的串口助手中发送命令末尾加回车。app log 与录音、查找等原指令共存。| 命令 | 作用 || --- | --- || app log status | 显示固件版本、保存开关、已保存容量、队列和错误计数 || app log on | 开启采集并保存开关断电后仍保持 || app log off | 提交已有队列后关闭普通采集历史日志保留 || app log flush | 立即提交当前 RAM 队列正常最长等待 3 秒 || app log save | 在板端持有 FAT 时生成 OFFLOG.TXT / OFFLOG.CRC || app log usb [编号] | 无盘时生成带请求编号的 U 盘快照然后自动切换 MSC供 PC 读取 OFFLOG.TXT/OFFLOG.CRC || app log export [编号] | 将稳定快照经已开启的 USB CDC 发到 PC || app log cancel [编号] | 取消当前 CDC 导出指定编号时只取消匹配的请求 || app log clear | 删除本功能的持久日志和命令前已排队内容不删除录音文件 || app usbserial auto on | 开启自动 USB 检测并保存设置供下次开机使用 || app usbserial auto off | 关闭自动检测当前自动 CDC 会话一并停止保存设置 || app usbserial status | 查看实际 CDC 枚举状态、自动监听和开机设置 |clear 用于研发主动清理会丢失旧问题记录客户反馈前请勿执行。它不删除此前导出到电脑或 U 盘的 TXT 快照后续进入 U 盘会生成新快照。关闭普通采集后独立异常尾部仍会尽力保留便于故障诊断。状态例子中的字段含义textoffline-log: version261014-v3 ret0 ready1 enabled1 bytes... pages...queued... dropped... errors... last_error0 next_seq... boot_id...offset0x4d80000 export0 id... export_error0 usb_auto1 auto_boot1- ready1启动扫描完成。刚开机短时间 ready0 可以稍后重试。- bytes/pages已验证有效的日志文本字节数 / 记录数记录最多 256 个。- queued尚在 RAM 中等待提交的字节数。- dropped本次启动因队列满丢弃的新日志字节数不是旧记录正常循环覆盖次数。- errors/last_error本次启动存储或配置错误次数 / 最近错误码。成功提交后 last_error 恢复 0。- boot_id从历史日志恢复后递增的启动标识不是日期。- export/id/export_errorCDC 导出状态、请求编号和最后结果0 表示成功。- usb_auto1后台自动检测已开启不代表此时已连接电脑auto_boot1 表示下次开机仍自动检测。导出文本末尾还包含 [offline-log snapshot] 元信息记录导出时启动编号、运行毫秒数、丢日志及存储错误计数便于研发判断完整性。## 3. USB CDC 直接导出### 3.1 自动连接及 USB 模式切换v2 默认后台检测插线即使本板外置充电电路导致 PMU_DC5V0也通过 USB DP/DM 检测主机。未连接电脑时不建立 CDC会约每秒进行一次短探测插线并发现主机后启动 CDC。Windows 工具等待 COM 出现再发送导出命令。物理拔线后自动关闭本次会话并继续等待下次插线。电脑休眠造成的 USB SUSPEND 保留会话不当作物理拔线。一个物理 USB 控制器同时只能使用一种设备类别。用户显式开启 U 盘或 USB 声卡时原有模式选择优先自动检测不会抢占它们。需要从这些模式返回自动日志导出时在普通 UART 执行textapp udisk offapp usbaudio offapp usbserial auto on只需关闭实际正在使用的模式。拔插 USB 后重新运行 PC 导出命令即可。设备关机、仅充电线、串口被其他程序占用或仍处于 U 盘/声卡模式时电脑不能通过不存在的 CDC 通道发命令工具会给出对应提示。### 3.2 手动控制兼容已有 CDC 录音导出的手动方式继续适用。普通 UART 可执行textapp usbserial onapp usbserial statusapp usbserial on/off 用于手动启停当前 CDC显式手动启停会撤销当前自动等待。自动开机偏好独立保存在 NVRAM 的 USB_SERIAL_AUTO 项旧 app usbserial boot on/off 控制原 USB_SERIAL_BOOT 项。自动偏好开启时优先启动后台监听关闭自动偏好后按旧开机设置处理。需要恢复原来的无 CDC 开机行为时执行 app usbserial auto off 和 app usbserial boot off再重启。在 Windows 执行 --mode cdc --port COM8 的上述 Python 命令或 -Mode cdc -Port COM8 的 PowerShell 命令。不指定 COM 时会自动发现 VID 10D6 / PID B00A 的设备多块板同时连接时指定目标 COM。先关闭占用该 COM 的串口助手。工具自动发送带请求编号的命令、校验并保存文本。研发可运行独立命令行程序textOfflineLogCLI.exe --mode auto --output-dir D:\logsOfflineLogCLI.exe --mode usb --drive E:\ --output-dir D:\logsOfflineLogCLI.exe --mode cdc --port COM8 --output-dir D:\logs这两种导出均使用开发板 USB 接口。普通 UART 只用于方便研发控制CDC 导出正文不会从普通 UART 传输。### 3.3 自动检测与待机功耗目前板级深睡入口没有可用的 USB 或普通定时器唤醒源且外置充电电路的 DC5V 状态不能可靠表示插线。为保证客户设备插 USB 后可被发现自动监听持有 PARTIAL_WAKE_LOCK允许显示休眠但会阻止进入最深睡眠。监听开启期间存在待机功耗代价需要实板测量本版没有修改显示或 NTC 的休眠策略。不需要随时插 USB 导出时可执行 app usbserial auto off 关闭监听并释放其锁若当前是手动 CDC 会话再执行 app usbserial off。正常日志循环保存继续工作。以后执行 app usbserial auto on 恢复自动导出。手动 app usbserial on 沿用原 FULL 锁行为不作为低功耗自动监听方式。## 4. 存储原理和异常恢复原 NAND 分区表已有 1 MB runtimelog本次将该分区内部划分为两个互不重叠区域**不调整分区表或录音 FAT 容量**| 区域 | 地址 | 大小 | 用途 || --- | --- | --- | --- || SDK ACTLOG | 0x4D00000 | 512 KB | 保留原压缩运行日志机制 || 离线文本日志 | 0x4D80000 | 512 KB | 新增文本循环存储 || 录音 U 盘 | 0x4E00000 起 | 原配置 | 录音文件及导出快照 |离线区有 256 个 2048 字节记录每条有 32 字节头和最多 2016 字节正文因此纯日志最大约 **504 KB**导出还追加少量状态信息总长度不超过 512 KB。能保留多久取决于日志输出量不按固定天数保存。流程如下textprintk / printf / 控制台输出↓ 短临界区复制不等待存储16KB RAM 队列↓ 后台线程满记录或等待约5秒2048B记录 → NAND写入 → flush → 读回校验↓ 成功后才移除队列原文512KB循环日志区↓ 请求导出刷盘并复制有序稳定快照PSRAM 快照├─ USB CDC长度正文 CRC32结束帧 → PC└─ 进入MSC前OFFLOG.TXT OFFLOG.CRC → PC日志页头包含格式版本、序号、启动编号、运行时间、长度和 CRC32。重启扫描只接收完整有效记录跳过损坏页不因单页错误清空全部历史。记录序号支持 32 位回绕。写入失败保留队列原文并限速重试状态可查询队列满时丢弃新增日志并计数。日志采集覆盖原 DMA printk 输出以及切到 CPU 输出后的 printk 路径经这些路径输出的系统、应用和 Shell 文本均能收集。没有实际输出到这些路径的内部事件不会自动补日志ROM 深睡输出也不在采集范围内。文本保留原始字节可能包含 ANSI 颜色控制符。启动分隔行记录固件版本和 BOOT 标识文件名时间来自 PC设备没有据此获得实时时钟。异常回调只切换到独立 **4KB 内部 SRAM** 尾部缓冲不在故障现场等待 NAND 或文件锁原 ACTLOG / coredump / ramdump 流程继续执行。再次启动时若 SRAM 数据仍保留且元信息有效会分块恢复到日志队列确认刷盘成功后才清除异常 bank失败保留重试。恢复中再次复位时可能重复已经保存的前缀优先保留异常内容。正常关机 / 重启在撤销供电保持前限时等待最多 2 秒提交已有队列。**突然断电仍可能丢失尚未提交的 RAM 日志**异常 SRAM 尾部也不保证跨彻底断电或清 RAM 的启动过程保存。本功能提供运行文本和尽力恢复的异常尾部导出 TXT 不包含完整二进制内存转储。## 5. 开发入口和扩展方法重要新增或修改位置按约定添加 //zk / //zk- 和中文注解Python、CMake、配置使用 #zk / #zk-。| 位置 | 作用 || --- | --- || src/main/offline_log.c/.h | 队列、分区扫描、循环记录、开关、刷盘、清理、快照 || src/main/offline_log_panic.c/.h | 异常 SRAM bank、打印分流、复位恢复 || src/main/offline_log_export.c/.h | CDC 后台导出、取消、U 盘快照与状态尾部 || src/main/system_app_shell.c | app log 注册和参数检查 || src/main/system_app_main.c | 正常开机启动自动 CDC 监听尊重明确选择的 U 盘启动模式 || src/main/usb_serial_runtime.c | USB 类别所有权、自动探测、插拔处理、可靠流传输和唤醒锁 || ../../framework/system/hotplug/hotplug_usb.c | 自动探测结束的 PHY 清理成功后才释放热插拔保留 || src/card_reader/card_reader_main.c | FAT 交给 MSC 前自动生成快照 || ../../zephyr/subsys/trace/printk_dma.c、../../zephyr/lib/os/printk.c | 打印采集入口 || ../../framework/system/act_log/act_log_flash_buffer.c | 限制 SDK ACTLOG 只写前半区 || ../../framework/system/sys_power_off.c | 正常关机和重启的有界同步 || tools/offline_log/ | 中文 GUI、CLI、协议、EXE 构建和测试 |CONFIG_APP_OFFLINE_LOGy 默认随本板开启。调整 RAM 容量、提交周期见 offline_log.h调整 Flash 区域时必须同步原 ACTLOG 的边界并确认 NAND 分区和记录对齐。添加诊断日志仍按现有 printk / 系统日志方法输出采集层不要打印自己的日志或在中断中执行 Flash/USB 操作。### 5.1 上位机代码文件及职责上位机源码统一位于 **application/bt_watch/tools/offline_log/**。下面链接相对于本说明文件EXE 在 outdir/offline_log_tool/dist/它们由 Python 源码打包生成。| 文件 | 代码职责及修改入口 || --- | --- || [offline_log_protocol.py](tools/offline_log/offline_log_protocol.py) | 公共导出实现CLI 和 GUI 都调用它。包括 USB 设备发现、CDC 枚举等待、目标选择、命令发送、帧解析、长度/CRC32 校验、取消和最终文件发布 || [offline_log_cli.py](tools/offline_log/offline_log_cli.py) | 命令行 main()解析 --mode/--drive/--port/--output-dir调用公共导出函数中文打印过程及结果返回退出码 || [export_logs.ps1](tools/offline_log/export_logs.ps1) | PowerShell 入口将 -Mode/-Drive/-Port/-OutputDir 转换成 CLI 参数优先运行 EXE找不到 EXE 时运行 Python保留退出码和含空格路径 || [offline_log_gui.py](tools/offline_log/offline_log_gui.py) | 可选 Tkinter 窗口。ExportWindow 管理设备选择、输出目录、后台线程、进度和取消AdaptiveMessage 负责提示自动换行、增高和超长内容滚动 || [启动日志导出.bat](tools/offline_log/启动日志导出.bat) | 双击入口启动 GUI EXE开发环境可使用源码入口 || [build_windows.ps1](tools/offline_log/build_windows.ps1) | 在独立 venv 中运行 PyInstaller生成 OfflineLogCLI.exe 和 OfflineLogExport.exe并复制中文使用说明、PowerShell 和 BAT || [requirements-build.txt](tools/offline_log/requirements-build.txt) | EXE 构建依赖pyserial、PyInstaller。只运行 Python CDC 导出时安装 pyserial 即可 || [test_offline_log_protocol.py](tools/offline_log/test_offline_log_protocol.py) | 协议与导出单元测试真实导出代码搭配模拟串口/磁盘、拆包、错误 CRC、断流、超时、取消、旧快照和多设备目标选择 || [test_offline_log_gui.py](tools/offline_log/test_offline_log_gui.py) | 窗口提示布局测试长中文错误完整可读、窗口缩放、滚动及手选目标保留 || [test_windows_package.py](tools/offline_log/test_windows_package.py) | 实际 EXE / PowerShell 包验证帮助、中文及带空格目录、成功导出、坏 CRC 拒绝、Python 回退及可选 GUI 启动 || [README.md](tools/offline_log/README.md) | 可随上位机工具发给客户的中文使用说明打包时复制为 使用说明.md |### 5.2 公共协议模块的主要函数维护通信和文件保存时重点阅读 offline_log_protocol.py| 函数 / 类 | 处理内容 || --- | --- || export_auto(...) | 两个界面的统一入口。默认等待 CDC显式 USB 模式/盘目录读取快照。拒绝冲突目标不在实时失败后回退旧快照 || cdc_ports() / all_serial_ports() | 通过 pyserial 枚举端口自动发现匹配本板 VID 10D6 / PID B00A手选 COM 可使用完整串口列表 || wait_cdc_port(...) | 最长 10 秒等待指定目标出现支持取消多块板拒绝猜测不改变明确选定的 COM || export_cdc(...) | 创建非零 32 位随机请求编号发送 app log export接收本次快照失败/取消时尽力发送对应 app log cancel || CDCReader.begin/copy_payload/end | 跳过普通控制台输出匹配请求编号按声明长度读取原始正文验证结束帧编号、长度及 CRC32 || removable_directories() | 通过 Windows API 获取可移动卷固定磁盘形式的设备由用户显式指定目录 || inspect_snapshot() / newest_snapshot() | 读取 OFFLOG.CRC验证 OFFLOG.TXT 的长度和 CRC仅供明确的磁盘快照导出 || export_msc(...) | 将指定快照复制到电脑复制前后检查快照一致性并再次验证实际复制内容 || _target() / _finish() / publish_complete() | 生成带 PC 时间的文件名写同目录 .part刷盘后发布正式 TXT拒绝覆盖已有文件失败清理临时文件 || Snapshot / ExportResult | 保存快照信息以及成功结果的电脑路径、字节数、CRC 和传输方式 |GUI 的后台线程使用取消事件界面通过事件队列更新避免文件传输阻塞窗口。CLI 的 CtrlC 返回 130普通导出失败返回 1成功返回 0。PowerShell 返回下层工具的实际退出码方便工厂脚本和客服批处理判断结果。### 5.3 从 PC 指令到板端日志的完整流程textexport_logs.ps1 / OfflineLogCLI.exe / GUI 点击导出→ offline_log_cli.main / ExportWindow 后台线程→ offline_log_protocol.export_auto→ 等待 CDC COM打开目标串口→ export_cdc发送 app log export 请求编号→ 板端 system_app_shell.c校验参数并提交导出任务→ offline_log_export.c刷盘生成本次 PSRAM 稳定快照→ usb_serial_runtime.c独占可靠流经 CDC 发送帧和正文→ CDCReader校验编号、正文长度、CRC32→ .part 刷盘并发布电脑 TXT显示保存路径CDC 串口在 PC 端按 115200 打开这是虚拟串口的配置参数正文经 USB 传输不经板上普通 UART。设备帧格式如下正文不做文本解码或换行转换textPC 请求app log export 123\r\n设备头LOG,BEGIN,123,offline_log.txt,字节数\r\n设备正文精确 字节数 个原始字节设备尾\r\nLOG,END,123,字节数,8位大写十六进制CRC32\r\n开始前失败LOG,ERROR,123,负错误码\r\nPC 取消app log cancel 123\r\n123 是示例请求编号实际每次导出生成新编号范围 14294967295。CRC32 使用标准 IEEE 算法与 Python zlib.crc32 一致。按长度读取可以允许正文出现 LOG,END 字样不会误判为结束。板端快照复制完成后从 PSRAM 发送等待 USB 时继续保存新日志。U 盘的清单格式为 OFFLOG,1,字节数,8位大写CRC32\r\n。修改帧或清单格式时需同时修改板端 offline_log_export.c、PC 正则/解析函数及两侧测试。调整 VID/PID 时同步 USB_VID/USB_PID调整最大快照容量时同步 PC 的 MAX_LOG_BYTES 和板端容量并检查实际存储布局。### 5.4 源码运行、重新打包和测试以下命令从 SDK 根目录 运行powershell# 仅运行 Python 上位机python -m pip install pyserialpython .\application\bt_watch\tools\offline_log\offline_log_cli.py --output-dir D:\logs# 运行可选窗口源码python .\application\bt_watch\tools\offline_log\offline_log_gui.py# 修改源码后重建两个 Windows EXEpowershell -NoProfile -ExecutionPolicy Bypass -File .\application\bt_watch\tools\offline_log\build_windows.ps1# 协议和窗口源码测试python -m unittest discover -s application/bt_watch/tools/offline_log -v# 验证实际打包文件--gui 同时检查窗口 EXE 启动python application/bt_watch/tools/offline_log/test_windows_package.py --gui源码修改不会自动改变已有 EXE需重新运行打包脚本。构建环境在 outdir/offline_log_tool/build_env成品在 outdir/offline_log_tool/dist。客户可以拿整个 dist 目录使用其中 PowerShell、CLI EXE 或窗口无需 SDK 和 Python。修改 PowerShell 参数或中文说明后也应同步发新的脚本及 使用说明.md。只调整 PC 窗口、输出目录或提示文本可修改相应上位机文件新增板端指令需修改 system_app_shell.c并通过公共协议模块调用。自动进入 CDC 的逻辑在固件 usb_serial_runtime.c 和开机入口电脑工具负责等待接口及发送请求两侧缺一不可。## 6. 验证和板端复测从 SDK 根目录 可运行日志核心、异常和导出软件测试以及 PC 协议测试textpython application/bt_watch/tests/offline_log/run_tests.pypython application/bt_watch/tests/offline_log/run_panic_tests.pypython application/bt_watch/tests/offline_log/run_export_tests.pypython application/bt_watch/tests/usb_serial/run_auto_tests.pypython application/bt_watch/tests/usb_serial/run_core_tests.pypython application/bt_watch/tests/usb_serial/run_factory_tests.pypython -m unittest discover -s application/bt_watch/tools/offline_log -v软件测试使用真实 C 模块或协议代码模拟存储失败、断流、复位、错误校验和取消无法代替实板 NAND 掉电测试、USB 枚举和实际使用功耗测试。本版已完成生产编译及普通 / 调试固件打包。日志核心 930 项 ARM 断言、异常模块 4741 项 ARM 断言、导出模块 337 项 ARM 断言、自动 CDC 模块 192 项 ARM 断言及上位机 53 项协议/窗口测试通过独立 CLI、GUI 和 PowerShell 入口已验证中文及带空格路径导出、校验失败拒绝、窗口启动和 Python 回退。生产 ELF 的原 CDC/PCM、USB Chapter 9 配置及工厂命令回归通过第一版日志集成时的双 MIC、蓝牙通话、MP3、Find My 回归也已通过。板端真实 USB、掉电、功耗和客户使用场景仍需烧录复测。建议烧录后依次检查1. app log status 显示 261014-v3采集、自动监听及自动开机设置开启。2. 不发模式切换指令直接插 USB 数据线运行默认 PC 命令检查 TXT 中刚产生的唯一日志内容。再产生一条新日志第二次导出应包含新内容。3. 产生录音、通话、Find My 等原功能日志执行 app log flush 后正常重启确认旧日志仍可导出。4. 中途拔线或取消后工具不生成不完整 TXT重新插线可再次导出。电脑睡眠恢复后也应能继续导出。5. 手动 U 盘/声卡工作时自动监听不抢占关闭该模式、重新 app usbserial auto on 后恢复实时导出。U 盘已接管时 app log save 应返回忙不应写 FAT。6. 分别测试自动监听开/关时的屏幕休眠、待机电流及原音频业务确认实际使用效果。