kashmira-b/embedded-debuggin-toolkit

# 嵌入式调试工具包 ## 概述 一个模块化、可复用的 C 调试库，适用于 STM32L476RG，遵循 STM32 HAL 约定。 | 模块 | 文件 | 描述 | |---|---|---| | 调试日志 | `debug_log.h/.c` | 具有运行时级别控制的分层 UART 日志输出 | | 错误处理 | `error_handler.h/.c` | 错误码、字符串描述符、LED 指示 | | I2C 扫描器 | `i2c_scanner.h/.c` | 带重试、注解和汇总表的总线扫描 | | 计时宏 | `timing.h/.c` | 通过 `HAL_GetTick()` 进行执行时间分析 | | 模拟 HAL | `mock_hal.h/.c` | STM32 HAL 桩代码 — 模拟 UART、I2C、滴答计时器 | ## 项目结构 ``` embedded-debugging-toolkit/ ├── Inc/ │ ├── mock_hal.h # Simulated STM32 HAL types and functions │ ├── debug_log.h # Logging API, level macros, runtime filter │ ├── error_handler.h # Error codes and reporting API │ ├── i2c_scanner.h # I2C bus scan API │ └── timing.h # Timing macros and functions ├── Src/ │ ├── mock_hal.c # HAL stubs (stdout = UART, I2C whitelist, bus-busy injection) │ ├── debug_log.c # Formatted log engine with timestamp + file:line prefix │ ├── error_handler.c # Error table + simulated LED indication │ ├── i2c_scanner.c # Per-address probe, bus-busy retry, summary table │ ├── timing.c # Elapsed time logger │ └── main.c # Integration demo ├── logs/ │ └── scan_output.log # Captured run output (generated at runtime) └── README.md ``` ## 模拟规则 | 方面 | 模拟行为 | |---|---| | UART 输出 | `fwrite` 写入标准输出（通过 `tee` 捕获到日志文件中） | | `HAL_GetTick()` | 模拟计数器，每次调用时递增 | | I2C 设备存在情况 | 仅 `0x3C` (SSD1306) 和 `0x68` (MPU-6050) 返回 ACK | | 总线忙注入 | 约每第 15 次探测返回 `HAL_BUSY` → 扫描器重试并记录 `WARN` | | LED 指示 | 记录为描述闪烁模式的 `WARN` 消息 | | `HAL_Delay()` | 仅推进内部滴答计数器 | ## 快速入门 ### STM32CubeIDE 集成 1. 将 `Inc/` 和 `Src/` 复制到您的 CubeIDE 项目中（排除 `mock_hal.h/.c`）。 2. 将 `#include "mock_hal.h"` 替换为 `#include "stm32l4xx_hal.h"`。 3. 通过 `MX_USART2_UART_Init()` 和 `MX_I2C1_Init()` 初始化 `huart2` 和 `hi2c1`。 ## 功能：调试日志级别控制 在运行时控制发出哪些严重级别 — 无需重新编译： ``` DEBUG_SetMinLevel(LOG_LEVEL_INFO); // All messages (default) DEBUG_SetMinLevel(LOG_LEVEL_WARN); // Suppress INFO — keep WARN + ERROR only DEBUG_SetMinLevel(LOG_LEVEL_ERROR); // Suppress INFO + WARN — errors only ``` 查询活动级别： ``` LogLevel_t lvl = DEBUG_GetMinLevel(); ``` ## 功能：I2C 总线扫描器 探测从 `0x08` 到 `0x77` 的每一个地址，记录每个结果，通过重试机制处理总线忙状态，并在最后打印汇总表。 **示例输出（节选）：** ``` ============================================ I2C Bus Scanner | STM32L476RG [SIM] Probing addresses 0x08 to 0x77 ... ============================================ Probing 0x08 ... NACK ... 0x24: I2C bus busy, retrying... (arbitration lost) Probing 0x24 ... NACK ... Probing 0x3C ... ACK <- SSD1306 OLED Display [FOUND] ... Probing 0x68 ... ACK <- MPU-6050 IMU (AD0=GND) [FOUND] ... ============================================ I2C SCAN SUMMARY Addr Device ------ ------------------------------ 0x3C SSD1306 OLED Display 0x68 MPU-6050 IMU (AD0=GND) ------ ------------------------------ Total found : 2 device(s) Bus retries : 7 event(s) ============================================ ``` ## API 参考 ### `debug_log.h` ``` void DEBUG_LogInit(UART_HandleTypeDef *huart); void DEBUG_SetMinLevel(LogLevel_t level); // Runtime level filter LogLevel_t DEBUG_GetMinLevel(void); LOG_INFO("msg %d", val); LOG_WARN("msg %s", str); LOG_ERROR("msg 0x%02X", code); ``` ### `error_handler.h` ``` void ERROR_Initialize(void); void ERROR_Report(ErrorCode_t code, const char *details); const char *ERROR_CodeToString(ErrorCode_t code); ErrorCode_t ERROR_GetLastCode(void); ``` ### `i2c_scanner.h` ``` // Full bus sweep (0x08–0x77) with retry, annotation, summary table HAL_StatusTypeDef I2C_Scanner_ScanBus(I2C_HandleTypeDef *hi2c, uint8_t *found_count); // Single address check HAL_StatusTypeDef I2C_Scanner_PingDevice(I2C_HandleTypeDef *hi2c, uint8_t address); ``` ### `timing.h` ``` TIMING_MEASURE_START(tag); // Capture start tick TIMING_MEASURE_STOP(tag); // Log elapsed time uint32_t TIMING_GetTimestamp(void); void TIMING_LogElapsed(const char *label, uint32_t start_tick); ``` ## 设计原则 - **HAL 风格 API**：镜像 STM32 HAL 命名，以实现无缝的真实硬件移植。 - **防御性编程**：对所有公共 API 进行空指针检查。 - **模块化**：每个模块均可独立使用，依赖项极少。 - **模拟优先**：无需硬件即可运行，适用于 CI 和作品集演示。 - **总线忙恢复能力**：I2C 扫描器在遇到 `HAL_BUSY` 时会自动重试，并生成 `WARN` 日志。

标签：HAL库, I2C总线, IoT, Mock测试, MPU-6050, SSD1306, STM32, STM32L476RG, UART串口, 代码复用, 单片机, 固件开发, 外设驱动, 客户端加密, 嵌入式系统, 微控制器, 性能分析, 时序分析, 模块化设计, 硬件仿真, 硬件抽象层, 结构化日志, 自动化修复, 设备扫描, 调试框架, 错误处理