列出系统可用串口。识别 CH340/CP2102/FT232 等常见 USB 转串口芯片并给驱动建议。 毕设学生"串口列表里找不到板子"时先调这个。

打开串口，返回句柄 handle。port 形如 "COM3" 或 "/dev/ttyUSB0"。 波特率不确定就先用 115200（STM32 HAL 默认）或 9600（老例程/模块默认）。

关闭串口句柄。调试结束记得关，释放端口。

从串口读取数据（非阻塞，三条件提前退出）。 expect：正则，命中立即返回（如 expect="OK|ERROR" 等响应）； idle_ms：静默超时（板子说完就走）； seconds：总时长上限。返回文本视图 + HEX 视图 + 是否命中。 读到的内容同时累积进会话日志。

向串口发送数据并等响应。newline=True 自动追加 \r\n（AT 指令必须！）。 expect：正则，如 "OK"——发 AT 后等到 OK/ERROR 立即返回，不傻等； wait_s：等待响应上限秒数（默认 0.5，AT 慢响应建议 3~5）。 hex_mode=True 时 data 按 HEX 解析（RS485/Modbus 用）。

自动探测波特率：逐档打开串口采样，按"最像正常日志"评分排序并给推荐。 log_text 提供现成日志样本时走离线评分（不占串口）。设备静默时会提示先复位再扫。

★USB CDC 口（ESP32-S3 原生 USB、RP2040 等）上波特率不参与数据路径，本工具会 直接短路说明，不给排序——在那种口上"各档评分"只是同一批字节被反复读。 确需强行扫（例如怀疑枚举成 CDC 但实际是 UART 桥）时显式传 candidates， 如 candidates=[115200, 9600]。

批量执行 AT 指令序列并逐条断言（半自动回归测试）。 steps 形如 [{"cmd": "AT", "expect": "OK", "timeout_s": 2}, {"cmd": "AT+CWJAP?", "expect": "WIFI|ERROR"}]（expect 是正则）。 输出每步 PASS/FAIL/TIMEOUT + 回显尾，中途失败不中断，方便一次看全。

同时监听两个串口，输出时间线交错的录制日志（RS485 主从对话/两设备联调）。 每行前缀 [A]/[B] 标明来源口，附 HEX 视图防波特率猜错时完全看不懂。最长 120s。

取该句柄自打开以来的全部累积日志（喂给 analyze_log 做整体分析用）。

列出已落盘的串口会话日志（serial_open 时自动创建，新→旧）。 会话被关闭甚至对话轮次已隔很久之后，仍可用它找回之前的串口现场。

读取指定会话日志的内容（文件名来自 sessions_list）。 默认显示尾部 200 行（日志开头常是复位前旧数据）。整段内容可直接喂 analyze_log。

会话日志的保留策略与清理入口（日志只增不减时用）。

★ 默认 dry_run=True：只列出会删哪些文件、能回收多少空间，什么都不删。 要真删：dry_run=False + confirm=True，且隔离档位需为 write （删除不可逆——那些日志往往是几天前那次偶发故障的唯一现场）。

keep_days / keep_count 传 0（默认）时用内置策略：保留最近 30 天 / 最新 200 个。 ⓘ 日志会原样记录串口收发内容，可能含 WiFi 密码 / token 等凭据，分享前请检查。

把一次串口会话导出成 Markdown 交付报告（故障分析 + 原始日志附后）。

调完一次问题，把「现象/证据/结论/下一步」直接变成可交付文件——毕设报告、 工单、给同事看都行。原始日志原样附在末尾，避免「只有结论没有证据」。

数据来源：给 handle（活动会话）或 fname（已落盘日志，来自 sessions_list）； 都不给时若恰好只有一份日志会自动用它。 默认落点 <数据根>/reports/；已存在不覆盖（要覆盖传 overwrite=True + confirm=True）。

分析日志，识别 30 类常见故障模式（乱码/AT报错/反复重启/HardFault/传感器全0/全FF/ DS18B20恒85/DHT超时/I2C NACK/网络断链/ESP崩溃/掉电/看门狗/固件损坏/CWJAP错误码/ CME错误码/RTOS断言/栈溢出/链接错误/编译错误/I2C扫描空/UART帧错/HAL断言/ADC饱和/ MQTT失败/HTTP错误/SD卡失败等），每条给出人话诊断和排查步骤。 输入可以是 serial_read 的输出、用户粘贴的串口日志、编译器/链接器报错。

计算或校验 Modbus RTU 的 CRC16（RS485 毕设必备）。 check=False：对数据部分计算 CRC；check=True：校验完整帧（数据+CRC）。

解析 Modbus RTU 帧：正常响应拆出寄存器值/线圈状态，异常响应（功能码|0x80） 直译异常码 01-06（非法功能/非法地址/非法值/设备故障/忙...）并给排查建议。 从站"该响应但不响应/回了一帧看不懂"时用它。

查错误码释义表（外置知识库 knowledge/error_codes/*.json，每条带出处）。

table 留空列出所有可查的表；只给 table 列出该表全部码； table+code 给出该码的释义、排查方向与依据（出处）。 已收录：esp_idf（esp_err_t）/ at_common（AT 通用响应）/ cwjap / cme / modbus_exception / mqtt_rc。 查不到时明说未收录、不给释义——不要拿别的码去猜。

检查 MCU 引脚分配是否冲突（内置数据手册级复用映射）。 mcu 如 "stm32f103c8t6"；pins 如 {"PA9": "USART1_TX", "PB6": "I2C1_SCL", "PA0": "GPIO"}。 board 可选开发板名（如 "bluepill"）：板载外设占用的引脚再挪用会警告。 能抓：该脚没有此功能（AI 幻觉接线）、同一功能双占、SWD 脚挪用、 remap 档不匹配、非 5V 容忍脚；ESP32 类查硬约束（flash 保留脚/仅输入/strapping）。 写代码分配引脚之前必须先过一遍。

列出引脚知识库已收录的 MCU 型号。pin_check 前可用它确认型号是否支持。

输出指定 MCU 的 pinmap JSON 原文（全引脚复用映射 + caveats + 常见冲突提示）。 pin_check 报错后想看完整数据、或需要给用户展示映射依据时用。

列出板级知识库已收录的开发板。选板子前先看有没有现成板级坑清单。

输出指定开发板的板级知识：板载外设及占用引脚、板级坑清单（按翻车率排序）、 供电说明、数据来源。如 "bluepill"（蓝药丸）、"blackpill_f411"（黑药丸）。 给用户做硬件选型/排板级坑之前先查这个。

列出已收录的嵌入式生态/框架（Zephyr / RT-Thread / PlatformIO / Keil / IAR / Rust defmt）。 拿到不认识的工作目录、或一段陌生的报错时，先判断「这是哪个生态的工程」—— 识别错了，后面每一步排查都会拐到沟里。

输出指定生态的识别特征：工程产物 / 构建配置 / 日志特征 / 常见坑。 name 用 ecosystem_list 给的 key（如 zephyr / keil / rust_defmt）。

识别一个工程目录属于哪个生态（扫标志文件：platformio.ini / *.uvprojx / prj.conf / SConstruct / *.ewp / Cargo.toml），并给出该生态的构建方式与常见坑。 拿到别人的工程压缩包、或不知道从哪下手时先跑这个。只探一层，不递归。

探测本机嵌入式工具链：编译器（ARM GCC / armclang / RISC-V / Xtensa）、 调试器、构建系统（CMake/Ninja/west/SCons/PlatformIO/Cargo）各给版本。 换机器、或「我这能编过、换台电脑就编不过」时先看这个。烧录器用 flash_tool_detect。

探测已连接的调试器（DAPLink/ST-Link/J-Link...）和目标芯片。 "烧录失败/找不到目标芯片"时先调这个。需要可选依赖 pyocd。

通过 pyocd 的 RTT 通道读目标板调试日志（⚠ 实验性）。 固件需集成 SEGGER RTT 控制块；比 UART 快且不占串口外设。 cbuffer：控制块编号（多通道时指定，默认读全部）；probe_serial：多调试器时指定。 失败自动给排查指引，建议先 probe_list 确认调试器。

检测本机已安装的烧录工具（esptool/st-flash/pyocd/openocd）。 烧录前先调这个看有什么可用。

烧录固件到开发板（不可逆操作，双闸门）。

第一道：dry_run 默认 True，只返回将要执行的完整命令供逐字核对，不写 flash。 第二道：真正执行必须 dry_run=False 且 confirm=True —— 两道都齐才会写。 另受隔离档位管辖：MCU_DEBUG_MCP_MODE 为 readonly（默认）时直接拒绝。 STM32+ST-Link（默认首选，实测最稳）： flash_firmware("app.bin", chip="stm32h563") → STM32_Programmer_CLI -c port=SWD mode=normal -w app.bin 0x08000000 -v -rst 接多台同型号调试器时用 sn 指定探针序列号。 ESP 系：flash_firmware("app.bin", chip="esp32", port="COM5") 通用 Cortex-M：flash_firmware("app.elf", tool="pyocd", chip="stm32f103c8") 烧完自动 -rst 复位；不复位的话 SWD 会把内核 halt 住，板子不会跑。

列出可用的预验证驱动模板（带出厂验证记录）。 用户要做毕设传感器部分时，先看这里有没有现成的，而不是自己写。

输出指定驱动的接线表+完整代码+验证记录。name 来自 driver_list。 这些代码是预验证过的，直接交付用户；需要适配的只有 *_port.h。

查指定驱动的接线知识库：接线表、头号坑清单（按翻车率排序）、 输出日志解读、答辩加分点。回答"XX传感器怎么接/为什么不工作"前先查这个。

器件选型清单：按接口（i2c / uart / timer_pwm / gpio_timing）列出可用的 传感器与模块，带地址、微秒时序要求。回答"我要做温湿度采集/测距/姿态， 用哪个现成器件"时先查这里，别凭记忆报型号。bus 可按接口过滤（如 "i2c"）。

单个器件的选型详情：接口 / 地址 / 移植要求 / 头号坑 / 出厂验证记录 / 接线避坑全文。name 来自 component_list。

外设 API 用法知识层：每个驱动要占哪些外设（I2C1/TIM1/UART2…）、 初始化顺序有什么硬要求。移植驱动或排查"外设配了但读不到数"时先查这里。

单个驱动的外设初始化要求全文（取自其 *_port.h 适配层原注释）。 name 来自 peripheral_api_list。

把寄存器原始值按位域拆开解释。 fields 形如 [{"name":"HSION","bit":0}, {"name":"PLLSRC","lsb":16,"width":2}]。 手头有寄存器值不知道每个位什么意思时用。

用 CMSIS-SVD 文件解码寄存器位域（含枚举值提示与描述）。 svd_path 指向厂商 SVD 文件（CubeMX/固件包里有），如： decode_register_svd("STM32F103.svd", "RCC", "CR", 0x00040002)

解码 Cortex-M 故障寄存器，给出人话诊断 + 排查方向。

设备跑飞/进 HardFault 时用。传你从 fault handler 读到的原始值（任意组合）： decode_fault(cfsr=0x8200, hfsr=0x40000000, bfar=0x40021000)

★ 会自动处理三类陷阱，别跳过它的结论： · BFARVALID/MMARVALID=0 时地址是垃圾值——工具会拒绝解读，不给假地址 · IMPRECISERR 时即使 valid，BFAR 也不可信（总线写延迟）——工具会标注 · FORCED=1 说明真因在 CFSR——工具会提示去读 CFSR 拿到可信地址后，用 symbol_lookup 反查是哪个函数。

解析 .map 文件：段占用（Flash/RAM）、符号表、可疑大符号（查大数组/大缓冲）。

支持 GNU ld / Keil / IAR 三种格式，自动识别；认不出会明说，不猜。 parse_map("build/app.map") 查"RAM 怎么爆了""哪个大数组吃栈"时用。结果里的符号大小若是「推断」值， 表示该 map 不记 size，大小由相邻符号地址差推出（可能偏大）。

把地址反查成「函数名+偏移」。fault 地址定位代码的关键一步。

symbol_lookup("build/app.elf", ["0x08004a2c"]) ★优先给 .elf 而不是 .map：.elf 的 .symtab 带真实 st_size，能判断 「地址还在不在这个函数内」；.map 只能靠「下一个符号 − 本符号」推断。 ★GNU ld（GCC/STM32CubeIDE/ESP-IDF）默认不往 .map 里写符号表， 同一份固件的 .map 可能只有个位数条目（实测 3 个，而 .elf 有 31 个）。 此时反查会命中段符号给出假函数名——所以本工具遇到这种稀疏 map 会 明确提示，并把同目录的 .elf 摆出来让你换源。 找不到符号时明确报"未找到"，不给猜测的函数名——猜出来的名字比没名字更害人。

栈回溯：把 fault 时压栈的 8 个字还原成调用链，定位出错函数。

frame 按硬件压栈顺序：[R0, R1, R2, R3, R12, LR, PC, xPSR] stack_unwind("build/app.elf", frame=[r0,r1,r2,r3,r12,lr,pc,xpsr]) ★同 symbol_lookup：优先给 .elf。.map 的符号表稀疏时 PC/LR 可能反查出 假函数名，工具会就此提示。 exc_return 传 handler 入口时的 LR——它决定栈帧是标准还是 FPU 扩展、 以及异常前用的是 MSP 还是 PSP（RTOS 任务）。传了会给出更准的判断。 ★ PC 反查不到符号时，说明是典型「跑飞」，工具会给排查方向。

环境自检：依赖 / 串口 / 烧录器 / 知识库根 / 版本，一次问清。

拿到陌生机器、或工具突然不好使时先跑这个：它把「这里能干什么、缺什么、 缺了会导致哪些工具不可用」一次列清，省掉一个个试错。 ★ 只报实测——探不到的会明说为什么探不到。

解析 NMEA 0183 语句（GPS/北斗模块最常见的串口输出），给人话解读。

支持 GGA/RMC/GSA/GSV/VTG/GLL，逐句输出 UTC 时间、经纬度（度分 + 十进制度）、 定位质量、卫星数、HDOP、速度、日期。把模块吐出来的整段原始数据直接贴进来： nmea_parse("$GNGGA,012345.00,3112.3456,N,12122.3456,E,1,08,0.9,12.3,M,,M,,*47") ★ 每句都验 XOR 校验和，不过的会明说「这句数据不可信」，不会把错帧当对的解。 ★ 非 NMEA 的行会单独指出并跳过，不当成数据。

通用二进制帧解析：按「帧头 + 长度字段」切帧，可选逐帧校验。

单片机自定义协议（上位机抓到的 hex 流）对不上时用。参数都能少填就少填： frame_parse("AA 55 04 01 02 03 04 AA 55 02 05 06") frame_parse("AA 55 04 01 02 03 04", header="AA55", checksum="sum8") frame_parse("01 03 04 00 0A 00 0B 9B F6", checksum="crc16_modbus") header 不给则须给 length_offset（长度字段相对帧首的偏移）。 checksum 可选 "none"/"sum8"/"crc16_modbus"。 ★ 切不出来（找不到帧头 / 长度越界 / 帧被截断）会逐条报出并附剩余字节， 绝不静默丢数据——静默丢帧是这类工具最危险的错。

读目标芯片的身份与存储信息（型号 / Device ID / 修订 / Flash 容量 / UID / 读保护）。

mode="read"（默认）走 hotplug：不复位、不停内核，板子照跑。 能拿到 型号 / Device ID / Revision / Device CPU / Board / 电压 / 调试器信息， 以及 DBGMCU_IDCODE 里更精确的 DEV_ID 与 REV_ID（会和连接 banner 交叉核对）。 mode="full" 走 normal：多拿 真实 Flash 容量 / 96 位 UID / 选项字节（读保护等）。 代价是连接本身会复位一次目标并 halt 内核 —— 受隔离层管辖（需要写权限）。 ★ 如果你正在查复位原因，别先调它：这次复位会把 PINRSTF 打进 RCC_RSR，污染现场。

实测依据：system memory（UID @0x08FFF800 / FlashSize @0x08FFF80C）在 hotplug 下 读不到（CLI 报 "failed to read the requested memory content"），必须 normal 档； 而 normal 档连上就复位。所以拆成两档，把选择权交给你，不悄悄替你做主。

读复位原因（RCC_RSR 标志）与内核运行状态，走 hotplug：不复位、不停内核。

回答「板子为什么自己重启了」「是不是看门狗喂狗没喂上」这类问题。 RCC_RSR 会给出 PINRSTF（复位引脚）/ BORRSTF（欠压）/ SFTRSTF（软件）/ IWDGRSTF（独立看门狗）/ WWDGRSTF（窗口看门狗）/ LPWRRSTF（低功耗退出）。

★ 关键理解：这些标志是【累积】的，只有写 RMVF 或整片掉电才清。 所以「好几个位同时为 1」= 「自上次清零以来发生过这几类复位」， 不等于「最后一次是它们一起发生」。 要定位「这一次」：先 clear_flags=True + confirm=True 清零 → 复现 → 再读。 clear_flags 不可逆（销毁现场），受隔离层管辖且需 confirm=True。 then_reset 只在 clear_flags=True 时有意义：清零并读回验证后再复位一次， 让内核继续跑（默认 True）。

★ 哪些动作会自己置标志（实测，用来区分「真复位」与「读操作自带的噪声」）： hotplug 连接（仅连接）→ 不置任何标志； normal 连接（仅连接）→ PINRSTF|SFTRSTF； hotplug + -rst → PINRSTF|SFTRSTF； hotplug + -hardRst → 仅 PINRSTF。 所以清零后读回还看到 PINRSTF/SFTRSTF 几乎总是命令自己造成的，不是 RMVF 没生效。

★ 为什么必须 hotplug：STM32CubeProgrammer 以 normal 档连接动作本身就会复位目标 并 halt 内核。用 normal 读复位原因，读到的第一个标志就是这次读操作自己造成的 —— 结论必然错。

烧录后校验：把固件文件与芯片上实际内容逐字节比对（只读，走 hotplug）。

比 -v 有用：-v 只能紧跟烧录命令，等于重烧一遍；这个读回来直接比， 还会报出第一个不一致的偏移和前后 8 字节上下文 —— 能直接看出来是「整段没写进去」 还是「某几个字节错了」。

file_path 支持 .bin（配 address，默认 0x08000000）/ .hex / .elf。 烧完提示 "verified" 但设备不工作时，先调它排除「根本没烧进去」。 ★ 不要拿 CLI 的 -checksum 和 -fchecksum 互相验：两者口径不同，实测同一份固件 给出不同值。字节比对才是唯一真凭据。

时序 / 数据率分析：找丢帧（序号跳号）、卡顿（间隔离群）、节拍漂移。

输入二选一：text（现成日志内容）或 path（日志/采集文件）。 最顺的用法：先 stream_capture 采一段，再把它的文件路径喂进来。

时间戳自动识别两种：[+0.0123] 采集前缀、HH:MM:SS.mmm；其他格式用 pattern （第 1 个捕获组是秒）。 seq_pattern 给序号（第 1 个捕获组），例如 TICK 42 这种要写 seq_pattern="TICK\s+(\d+)"； 不给则只认行首那个整数。

★ 定位说明：时间戳来自 PC 侧（OS 调度 + USB 缓冲），自带毫秒级抖动。上面的数适合 【相对比较】——哪几次明显变慢、有没有跳号、是否整体漂移；不适合当示波器判 「周期是不是精确 1.000 ms」。

长时录测：持续采集串口一段时间，逐行打上到达时间戳落盘。

产出的文件**直接可以喂给 timing_analysis(path=...) ** —— 两件工具是同一条链路。

seconds 最长采集秒数；max_lines 收够多少行提前结束（0=不限）； idle_stop_s 连续多少秒没数据提前结束（0=不用）；out_path 默认落在会话日志目录 （已存在同名文件会自动改名，不覆盖旧现场）。

★ 为什么时间戳必须在采集端打：事后才拿到的日志如果没时间戳，时序信息就永久丢了。 采集时按到达时刻记一行，成本几乎为零，却让后面所有分析成立。 排查「偶发丢数据」「隔一会儿卡一下」时用：让它自己采几分钟，再看 timing_analysis。

桥自检：问那块跑桥固件的板「你是谁、支持哪些总线」——不碰任何总线，纯握手。

排查「总线工具不工作」的第一步：先确认桥活着、认协议，再去怀疑接线。 省得在「固件问题」和「接线问题」之间来回猜。

port 不填则读环境变量 MCU_DEBUG_BRIDGE_PORT。桥固件源码见 tools/bridge_fw/。

扫描 I2C 总线上的 7 位地址，标出每个应答地址上可能是什么器件。

这是「板子上到底挂了什么」的第一手答案。low/high 可缩小范围 （默认 0x08–0x77，即 I2C 规范里可自由分配的段；保留段会被跳过）。

★ 三条边界（别把结论放大）： · 「有应答」只说明该地址有人 ACK，不代表这颗器件功能正常； · 同一地址常被多颗器件共用（0x68 上可能是 MPU-6050 也可能是 DS1307）， 要定种必须读它的 WHO_AM_I / ID 寄存器（i2c_read_reg）； · 挂在 TCA9548A 这类 I2C 多路复用器后面的器件默认是断开的， 直接扫主总线只能看到复用器自己（0x70–0x77）。

读 I2C 从设备的寄存器（最常见的「这颗 IMU 是不是活的」动作）。

addr 是7 位地址（MPU-6050 写 0x68，别写 8 位的 0xD0/0xD1，工具会拦下来）； reg 是寄存器地址；count 是要读的字节数（1–256）。

★ 读回全 0 或全 0xFF 时不要直接判「器件坏了」：工具会分别给出这两种情况 完全不同的成因清单（全 0xFF 往往是器件没接/没上电，而不是寄存器的值是 0xFF）。

写 I2C 从设备的寄存器。data 支持 "0x01" / "1,2" / [1,2]。

verify=True 会在写完后回读比对。★ 默认关：有些寄存器是只写的 （命令寄存器、软复位寄存器），回读必然拿到别的东西，默认开着会造成大量假 FAIL。

写操作受隔离层写权限门禁：只读档会被拒绝，并给出放开方式。

逐条 CS 读 JEDEC ID（0x9F），找出板上挂的 SPI flash，并解出厂商与容量。

★ SPI 没有地址概念，所以「扫描」只能是「对每条 CS 发 0x9F」。因此本工具 只对遵守 0x9F 的 SPI NOR/NAND flash 有效；对 SPI 传感器 / ADC / 显示驱动 （各有自己的命令字）扫不出来是正常的，不是故障 —— 那种器件请用 spi_read_reg 给具体命令字。

发一个 SPI 命令字并读回 N 字节（对读了命令字的从设备通用）。

例：读 JEDEC ID → spi_read_reg(cmd_byte=0x9F, count=3)。

1-Wire 搜索 ROM，列出总线上每颗器件的 64 位 ROM 码，并解出家族码对应的器件。

搜不到时的第一条怀疑对象是数据线缺 4.7k 上拉（1-Wire 靠上拉给器件充电， 缺了必然一颗都搜不到）——输出里会给完整清单。

经桥的 RS485 收发器发送字节（桥负责 DE 方向脚的时序）。

★ 能力边界：它只能确认桥把字节推出去了，对端有没有收到它证明不了。 要验证整条链路得让对端回话（再用 serial_read 读），或示波器看 A/B 差分波形。 这句限制会直接打印在输出里，不代用户下结论。