diff --git a/tools/bt/ble_log_console/docs/User-Guide-CN.md b/tools/bt/ble_log_console/docs/User-Guide-CN.md index c4d6574612..3c26d1067e 100644 --- a/tools/bt/ble_log_console/docs/User-Guide-CN.md +++ b/tools/bt/ble_log_console/docs/User-Guide-CN.md @@ -2,7 +2,7 @@ ## 简介 -BLE Log Console 是一个基于终端的实时 BLE 日志捕获与解析工具。它通过 UART DMA 接收 ESP32 固件发出的 BLE Log 帧，实时解析并展示在终端界面中，同时将原始二进制数据保存到文件供离线分析。 +BLE Log Console 是一个基于终端的实时 BLE 日志捕获与解析工具。它通过 UART DMA 接收 ESP 芯片固件发出的 BLE Log 帧，实时解析并展示在终端界面中，同时将原始二进制数据保存到文件供离线分析。 ## 准备工作 @@ -21,19 +21,10 @@ Component config → Bluetooth → BT Logs → Enable critical-log-only mode [y **手动配置：** ``` -Component config → Bluetooth → BT Logs → Enable BLE Log Module (Experimental) [y] -Component config → Bluetooth → BT Logs → BLE Log Module - → Peripheral Selection → UART DMA - → UART DMA Configuration - → UART Port Number (默认: 0) - → Baud Rate (默认: 3000000) - → TX GPIO Number (根据硬件设置) +Component config → Bluetooth → BT Logs → Enable BT Log Async Output (Dev Only) [y] ``` -| 配置项 | 推荐值 | 说明 | -|--------|--------|------| -| `CONFIG_BT_LOG_CRITICAL_ONLY` | `y` | 一键启用，包含 BLE Log + UART DMA | -| `CONFIG_BLE_LOG_PRPH_UART_DMA_BAUD_RATE` | `3000000` | 3 Mbps，兼顾吞吐量和稳定性 | +UART DMA 传输、3 Mbps 波特率、PORT 0 均为默认值，大多数情况下无需额外配置。 > **关于 UART PORT 0**：当配置为 PORT 0 时，固件会自动将 `ESP_LOG` 输出包装为 BLE Log 帧（`REDIR` source），Console 会自动解码并显示为普通日志行。 @@ -50,47 +41,56 @@ ESP32 GND ──────── USB 串口适配器 GND 确保 USB 串口适配器支持所配置的波特率（默认 3 Mbps）。推荐使用 CP2102N、CH343 或 FT232H 芯片的适配器。 -### 3. ESP-IDF 环境 - -使用前必须先 source ESP-IDF 环境： - -```bash -cd -. ./export.sh -``` - -无需额外安装依赖，`textual` 已包含在 ESP-IDF 核心依赖中。 - ## 启动 +### 快速启动（推荐） + +使用自带的启动脚本 -- 自动激活 ESP-IDF 环境并安装依赖，可在任意目录下运行： + +```bash +# Linux / macOS +/tools/bt/ble_log_console/run.sh + +# Windows +\tools\bt\ble_log_console\run.bat +``` + +不带参数启动时，工具会打开 **启动界面（Launch Screen）** -- 一个交互式配置界面，可以： + +- 从下拉列表中 **选择串口**（自动检测可用设备，支持 **Refresh** 按钮重新扫描） +- 从预设选项中 **选择波特率**（115200 至 3000000，默认 3000000） +- 通过文本输入或 **Browse** 文件选择器 **设置日志保存目录** +- 点击 **Connect** 开始捕获 + +传入 `--port` 可跳过启动界面，直接开始捕获： + +```bash +# Linux / macOS +./run.sh -p /dev/ttyUSB0 +./run.sh -p /dev/ttyUSB0 -b 3000000 -d /tmp/my_captures + +# Windows +run.bat -p COM3 +``` + +所有 CLI 选项均会转发给 `console.py`。 + +### 手动启动 + +如果你希望自行管理 ESP-IDF 环境： + ```bash cd . ./export.sh +python -m pip install textual textual-fspicker # 安装额外依赖 cd tools/bt/ble_log_console +python console.py # 启动界面 +python console.py -p /dev/ttyUSB0 # 直连捕获 +python console.py -p /dev/ttyUSB0 -b 3000000 # 指定波特率 +python console.py -p /dev/ttyUSB0 -d /tmp/captures # 指定日志目录 ``` -### 交互模式（启动界面） - -不带参数运行即可打开启动界面（Launch Screen），在 TUI 中选择串口、波特率和日志保存目录： - -```bash -python console.py -``` - -### 直连模式（CLI） - -传入 `--port` 跳过启动界面，直接开始捕获： - -```bash -# 基本用法 -python console.py -p /dev/ttyUSB0 - -# 指定波特率（须与固件配置一致） -python console.py -p /dev/ttyUSB0 -b 3000000 - -# 指定日志保存目录 -python console.py -p /dev/ttyUSB0 -d /tmp/my_captures -``` +### CLI 选项 | 参数 | 缩写 | 默认值 | 说明 | |------|------|--------|------| @@ -122,17 +122,16 @@ ble_log_YYYYMMDD_HHMMSS.bin 固定显示在底部，实时更新： ``` -Sync: SYNCED Checksum: XOR | Header+Payload -RX: 1.2 MB Speed: 2.8 Mbps Max: 2.9 Mbps Rate: 3421 fps -Frame Loss: 12 frames, 480 bytes +Sync: SYNCED | Checksum: XOR / Header+Payload | Press h for help +RX: 1.2 MB Speed: 293.0 KB/s Max: 300.0 KB/s Rate: 3421 fps Lost: 12 frames, 480 B ``` -- **Sync**: 同步状态（SEARCHING → CONFIRMING → SYNCED → CONFIRMING_LOSS） -- **Checksum**: 自动检测到的校验模式 +- **Sync**: 同步状态（SEARCHING -> CONFIRMING -> SYNCED -> CONFIRMING_LOSS） +- **Checksum**: 自动检测到的校验模式（算法 / 范围） - **RX**: 累计接收字节数 -- **Speed / Max**: 当前/峰值传输速度 +- **Speed / Max**: 当前/峰值传输速度（单位 KB/s 或 MB/s） - **Rate**: 当前帧率 -- **Frame Loss**: 自 Console 启动以来的累计丢帧数和丢失字节数 +- **Lost**: 自 Console 启动以来的累计丢帧数和丢失字节数 ## 快捷键 @@ -143,41 +142,70 @@ Frame Loss: 12 frames, 480 bytes | `c` | 清屏（清除日志区域） | | `s` | 切换自动滚动（默认开启） | | `d` | 打开每个 Source 的帧统计详情（按 `Escape` 或 `d` 关闭） | +| `m` | 查看缓冲区利用率（按 `Escape` 或 `m` 关闭） | | `h` | 显示快捷键帮助（按 `Escape` 关闭） | | `r` | 通过 DTR/RTS 复位芯片 | ### 帧统计详情（`d` 键） -按 `d` 键会弹出一个覆盖层，以表格形式展示每个 BLE Log Source 自 Console 启动以来的写入和丢失统计： +按 `d` 键会弹出一个覆盖层，包含两个表格，每秒自动刷新： -``` -┌─────────── Per-Source Frame Statistics (since console start) ───────────┐ -│ Source │ Written Frames │ Written Bytes │ Lost Frames │ Lost Bytes │ -│ LL_TASK │ 12345 │ 56.7 KB │ 5 │ 200 B │ -│ LL_HCI │ 890 │ 34.2 KB │ 0 │ 0 B │ -│ HOST │ 456 │ 12.1 KB │ 0 │ 0 B │ -│ HCI │ 234 │ 8.5 KB │ 2 │ 80 B │ -└─────────────────────────────────────────────────────────────────────────┘ -``` +**固件计数器（自芯片启动以来）** -- 固件上报的每个 Source 的写入和缓冲区丢帧统计： -有丢帧的行会以红色高亮显示。 +| Source | Written Frames | Written Bytes | Buffer Loss Frames | Buffer Loss Bytes | +|--------|---------------|---------------|-------------------|-------------------| +| LL_TASK | 12345 | 56.7 KB | 5 | 200 B | +| LL_HCI | 890 | 34.2 KB | - | - | +| HOST | 456 | 12.1 KB | - | - | +| HCI | 234 | 8.5 KB | 2 | 80 B | -## 查看历史捕获文件 +**Console 测量（自 Console 启动以来）** -- Console 端测量的每个 Source 的接收速率和峰值突发： + +| Source | Received Frames | Received Bytes | Avg Frames/s | Avg Bytes/s | Peak Frames/10ms | Peak Bytes/s | +|--------|----------------|---------------|-------------|------------|-----------------|-------------| +| LL_TASK | 12340 | 56.5 KB | 412 | 18.8 KB/s | 8 | 24.0 KB/s | +| LL_HCI | 890 | 34.2 KB | 30 | 1.1 KB/s | 3 | 3.6 KB/s | + +有缓冲区丢帧的 Source 会在固件计数器表格中以红色高亮显示。 + +### 缓冲区利用率（`m` 键） + +按 `m` 键会弹出一个覆盖层，展示固件上报的每个 LBM（Log Buffer Manager）缓冲区利用率： + +| Pool | Idx | Name | Peak | Total | Util% | +|------|-----|------|------|-------|-------| +| COMMON_TASK | 0 | spin | 3 | 4 | 75% | +| COMMON_TASK | 1 | atomic[0] | 4 | 4 | 100% | +| COMMON_ISR | 0 | spin | 2 | 4 | 50% | +| LL | 0 | ll_task | 4 | 4 | 100% | +| LL | 1 | ll_hci | 2 | 4 | 50% | + +- **Pool**: 缓冲池类别（COMMON_TASK、COMMON_ISR、LL、REDIR） +- **Idx**: 池内 LBM 索引 +- **Name**: LBM 可读名称（spin、atomic[N]、ll_task、ll_hci、redir） +- **Peak**: 同时在途的传输缓冲区峰值数量 +- **Total**: 该 LBM 可用的传输缓冲区总数 +- **Util%**: Peak / Total 的百分比；100%（红色高亮）表示所有缓冲区曾同时被占用，可能导致丢帧 + +此功能有助于诊断丢帧时哪个缓冲池资源不足。 + +## 打包为独立可执行文件 + +使用自带的构建脚本可将 BLE Log Console 打包为单文件可执行程序，目标机器无需安装 Python 或 ESP-IDF 环境： ```bash -python console.py ls +# Linux / macOS +/tools/bt/ble_log_console/build.sh + +# Windows +\tools\bt\ble_log_console\build.bat ``` -输出示例： +脚本会自动激活 ESP-IDF 环境、安装 PyInstaller、构建可执行文件、将其放置在当前工作目录下，并清理中间产物。 -``` -Captures in /tmp/ble_log_console: +输出：`./ble_log_console`（Linux/macOS）或 `.\ble_log_console.exe`（Windows）。 - 2026-03-17 14:30:25 2.3 MB ble_log_20260317_143025.bin - 2026-03-17 10:15:03 512.0 KB ble_log_20260317_101503.bin -``` - -这些 `.bin` 文件包含 UART 接收到的原始二进制数据，可使用 BLE Log Analyzer 的 `ble_log_parser_v2` 模块进行离线解析（HCI 日志提取、btsnoop 转换等）。 +> **注意**：请在与目标机器相同的操作系统和架构上构建。PyInstaller 不支持交叉编译。 ## 常见问题 @@ -200,7 +228,8 @@ Captures in /tmp/ble_log_console: ### 丢帧严重 - 按 `d` 查看各 Source 的丢帧详情 -- 增大固件 buffer：`CONFIG_BLE_LOG_LBM_TRANS_SIZE`、`CONFIG_BLE_LOG_LBM_LL_TRANS_SIZE` +- 按 `m` 查看缓冲区利用率 -- 100% 的池需要增加缓冲区 +- 增大固件 buffer：`CONFIG_BLE_LOG_LBM_TRANS_BUF_SIZE`、`CONFIG_BLE_LOG_LBM_LL_TRANS_BUF_SIZE` - 增加 LBM 数量：`CONFIG_BLE_LOG_LBM_ATOMIC_LOCK_TASK_CNT` - 提高波特率（需适配器支持） @@ -210,12 +239,4 @@ Captures in /tmp/ble_log_console: - Console 会自动解码 REDIR 帧，无需额外配置 - 日志由 1 秒周期定时器刷新，可能有短暂延迟 -### 提示 `ModuleNotFoundError: No module named 'textual'` -重新运行 ESP-IDF 安装脚本： - -```bash -cd -./install.sh -. ./export.sh -``` diff --git a/tools/bt/ble_log_console/docs/User-Guide-EN.md b/tools/bt/ble_log_console/docs/User-Guide-EN.md index 4a26334700..4e9caf6577 100644 --- a/tools/bt/ble_log_console/docs/User-Guide-EN.md +++ b/tools/bt/ble_log_console/docs/User-Guide-EN.md @@ -2,7 +2,7 @@ ## Introduction -BLE Log Console is a terminal-based tool for real-time capture and parsing of BLE Log frames from ESP32 firmware via UART DMA. It displays parsed frames in an interactive TUI and saves the raw binary data to a file for offline analysis. +BLE Log Console is a terminal-based tool for real-time capture and parsing of BLE Log frames from ESP chip firmware via UART DMA. It displays parsed frames in an interactive TUI and saves the raw binary data to a file for offline analysis. ## Prerequisites @@ -21,19 +21,10 @@ This enables the BLE Log module, selects UART DMA as the transport, and restrict **Manual configuration:** ``` -Component config → Bluetooth → BT Logs → Enable BLE Log Module (Experimental) [y] -Component config → Bluetooth → BT Logs → BLE Log Module - → Peripheral Selection → UART DMA - → UART DMA Configuration - → UART Port Number (default: 0) - → Baud Rate (default: 3000000) - → TX GPIO Number (set to match your hardware) +Component config → Bluetooth → BT Logs → Enable BT Log Async Output (Dev Only) [y] ``` -| Config Option | Recommended | Description | -|---------------|-------------|-------------| -| `CONFIG_BT_LOG_CRITICAL_ONLY` | `y` | One-click setup — enables BLE Log + UART DMA | -| `CONFIG_BLE_LOG_PRPH_UART_DMA_BAUD_RATE` | `3000000` | 3 Mbps — balances throughput and reliability | +UART DMA transport, 3 Mbps baud rate, and PORT 0 are all enabled by default -- no further configuration needed in most cases. > **About UART PORT 0**: When configured for PORT 0, the firmware automatically wraps `ESP_LOG` output in BLE Log frames (`REDIR` source). The console decodes and displays these as regular log lines. @@ -50,52 +41,61 @@ ESP32 GND ──────── USB-Serial GND Ensure your USB-serial adapter supports the configured baud rate (3 Mbps by default). Adapters based on CP2102N, CH343, or FT232H are recommended. -### 3. ESP-IDF Environment - -Source the ESP-IDF environment before use: - -```bash -cd -. ./export.sh -``` - -No additional installation is needed — `textual` is included in ESP-IDF's core dependencies. - ## Getting Started +### Quick Start (Recommended) + +Use the provided launcher script -- it automatically activates the ESP-IDF environment and installs dependencies. Can be run from any directory: + +```bash +# Linux / macOS +/tools/bt/ble_log_console/run.sh + +# Windows +\tools\bt\ble_log_console\run.bat +``` + +When launched without arguments, the tool opens a **Launch Screen** -- an interactive configuration interface where you can: + +- **Select a serial port** from a dropdown of auto-detected devices (with a **Refresh** button to re-scan) +- **Choose a baud rate** from preset options (115200 to 3000000, default: 3000000) +- **Set the log directory** via text input or a **Browse** file picker +- Press **Connect** to start capture + +To skip the Launch Screen and start capture directly, pass `--port`: + +```bash +# Linux / macOS +./run.sh -p /dev/ttyUSB0 +./run.sh -p /dev/ttyUSB0 -b 3000000 -d /tmp/my_captures + +# Windows +run.bat -p COM3 +``` + +All CLI options are forwarded to `console.py`. + +### Manual Launch + +If you prefer to manage the ESP-IDF environment yourself: + ```bash cd . ./export.sh +python -m pip install textual textual-fspicker # Install extra dependencies cd tools/bt/ble_log_console +python console.py # Launch Screen +python console.py -p /dev/ttyUSB0 # Direct capture +python console.py -p /dev/ttyUSB0 -b 3000000 # Custom baud rate +python console.py -p /dev/ttyUSB0 -d /tmp/captures # Custom log directory ``` -### Interactive Mode (Launch Screen) - -Run with no arguments to open the Launch Screen — a TUI where you can select the serial port, baud rate, and log directory before starting capture: - -```bash -python console.py -``` - -### Capture Mode (CLI) - -Pass `--port` to skip the Launch Screen and start capture immediately: - -```bash -# Basic usage -python console.py -p /dev/ttyUSB0 - -# With custom baud rate (must match firmware config) -python console.py -p /dev/ttyUSB0 -b 3000000 - -# With custom log directory -python console.py -p /dev/ttyUSB0 -d /tmp/my_captures -``` +### CLI Options | Option | Short | Default | Description | |--------|-------|---------|-------------| | `--port` | `-p` | (optional) | Serial port path, e.g., `/dev/ttyUSB0`, `COM3`. Omit to use Launch Screen. | -| `--baudrate` | `-b` | `3000000` | Baud rate — must match `CONFIG_BLE_LOG_PRPH_UART_DMA_BAUD_RATE` | +| `--baudrate` | `-b` | `3000000` | Baud rate -- must match `CONFIG_BLE_LOG_PRPH_UART_DMA_BAUD_RATE` | | `--log-dir` | `-d` | current working directory | Directory where capture `.bin` files are saved | Capture files are saved to the current working directory (or `--log-dir` if specified) with a timestamp-based filename: @@ -122,17 +122,16 @@ A scrollable area displaying real-time logs: Fixed at the bottom, updated in real time: ``` -Sync: SYNCED Checksum: XOR | Header+Payload -RX: 1.2 MB Speed: 2.8 Mbps Max: 2.9 Mbps Rate: 3421 fps -Frame Loss: 12 frames, 480 bytes +Sync: SYNCED | Checksum: XOR / Header+Payload | Press h for help +RX: 1.2 MB Speed: 293.0 KB/s Max: 300.0 KB/s Rate: 3421 fps Lost: 12 frames, 480 B ``` -- **Sync**: Sync state (SEARCHING → CONFIRMING → SYNCED → CONFIRMING_LOSS) -- **Checksum**: Auto-detected checksum mode +- **Sync**: Sync state (SEARCHING -> CONFIRMING -> SYNCED -> CONFIRMING_LOSS) +- **Checksum**: Auto-detected checksum mode (algorithm / scope) - **RX**: Total received bytes -- **Speed / Max**: Current / peak transport speed +- **Speed / Max**: Current / peak transport speed (in KB/s or MB/s) - **Rate**: Current frame rate -- **Frame Loss**: Cumulative lost frames and bytes since console start +- **Lost**: Cumulative lost frames and bytes since console start ## Keyboard Shortcuts @@ -143,41 +142,70 @@ Frame Loss: 12 frames, 480 bytes | `c` | Clear the log view | | `s` | Toggle auto-scroll (on by default) | | `d` | Open per-source frame statistics (press `Escape` or `d` to close) | +| `m` | Show buffer utilization (press `Escape` or `m` to close) | | `h` | Show keyboard shortcuts (press `Escape` to close) | | `r` | Reset chip via DTR/RTS toggle | ### Frame Statistics Detail (`d` key) -Pressing `d` opens a modal overlay showing per-source write and loss statistics since the console started: +Pressing `d` opens a modal overlay with two tables, refreshed every second: -``` -┌─────────── Per-Source Frame Statistics (since console start) ───────────┐ -│ Source │ Written Frames │ Written Bytes │ Lost Frames │ Lost Bytes │ -│ LL_TASK │ 12345 │ 56.7 KB │ 5 │ 200 B │ -│ LL_HCI │ 890 │ 34.2 KB │ 0 │ 0 B │ -│ HOST │ 456 │ 12.1 KB │ 0 │ 0 B │ -│ HCI │ 234 │ 8.5 KB │ 2 │ 80 B │ -└─────────────────────────────────────────────────────────────────────────┘ -``` +**Firmware Counters (since chip init)** -- per-source write and buffer loss counts as reported by the firmware: -Rows with frame loss are highlighted in red. +| Source | Written Frames | Written Bytes | Buffer Loss Frames | Buffer Loss Bytes | +|--------|---------------|---------------|-------------------|-------------------| +| LL_TASK | 12345 | 56.7 KB | 5 | 200 B | +| LL_HCI | 890 | 34.2 KB | - | - | +| HOST | 456 | 12.1 KB | - | - | +| HCI | 234 | 8.5 KB | 2 | 80 B | -## Viewing Saved Captures +**Console Measurements (since console start)** -- per-source receive rates and peak bursts measured by the console: + +| Source | Received Frames | Received Bytes | Avg Frames/s | Avg Bytes/s | Peak Frames/10ms | Peak Bytes/s | +|--------|----------------|---------------|-------------|------------|-----------------|-------------| +| LL_TASK | 12340 | 56.5 KB | 412 | 18.8 KB/s | 8 | 24.0 KB/s | +| LL_HCI | 890 | 34.2 KB | 30 | 1.1 KB/s | 3 | 3.6 KB/s | + +Sources with buffer loss are highlighted in red in the firmware table. + +### Buffer Utilization (`m` key) + +Pressing `m` opens a modal overlay showing per-LBM (Log Buffer Manager) buffer utilization as reported by the firmware: + +| Pool | Idx | Name | Peak | Total | Util% | +|------|-----|------|------|-------|-------| +| COMMON_TASK | 0 | spin | 3 | 4 | 75% | +| COMMON_TASK | 1 | atomic[0] | 4 | 4 | 100% | +| COMMON_ISR | 0 | spin | 2 | 4 | 50% | +| LL | 0 | ll_task | 4 | 4 | 100% | +| LL | 1 | ll_hci | 2 | 4 | 50% | + +- **Pool**: Buffer pool category (COMMON_TASK, COMMON_ISR, LL, REDIR) +- **Idx**: LBM index within the pool +- **Name**: Human-readable LBM name (spin, atomic[N], ll_task, ll_hci, redir) +- **Peak**: Maximum number of transport buffers in flight simultaneously +- **Total**: Total transport buffers available for this LBM +- **Util%**: Peak / Total as percentage; 100% (highlighted in red) means all buffers were in use simultaneously, indicating potential frame loss + +This helps diagnose which buffer pool is under-provisioned when experiencing frame loss. + +## Building Standalone Executable + +Use the provided build script to package BLE Log Console as a single-file executable that requires no Python or ESP-IDF environment on the target machine: ```bash -python console.py ls +# Linux / macOS +/tools/bt/ble_log_console/build.sh + +# Windows +\tools\bt\ble_log_console\build.bat ``` -Example output: +The script automatically activates the ESP-IDF environment, installs PyInstaller, builds the executable, places it in the current working directory, and cleans up intermediate artifacts. -``` -Captures in /tmp/ble_log_console: +Output: `./ble_log_console` (Linux/macOS) or `.\ble_log_console.exe` (Windows). - 2026-03-17 14:30:25 2.3 MB ble_log_20260317_143025.bin - 2026-03-17 10:15:03 512.0 KB ble_log_20260317_101503.bin -``` - -These `.bin` files contain raw binary data as received from UART. They can be parsed offline using the BLE Log Analyzer's `ble_log_parser_v2` module for HCI log extraction, btsnoop conversion, and more. +> **Note**: Build on the same OS/architecture as the target machine. PyInstaller does not cross-compile. ## Troubleshooting @@ -200,7 +228,8 @@ If it only appears once at startup, this is normal. If persistent, check the bau ### High frame loss - Press `d` to view per-source loss details -- Increase firmware buffers: `CONFIG_BLE_LOG_LBM_TRANS_SIZE`, `CONFIG_BLE_LOG_LBM_LL_TRANS_SIZE` +- Press `m` to check buffer utilization -- pools at 100% need more buffers +- Increase firmware buffers: `CONFIG_BLE_LOG_LBM_TRANS_BUF_SIZE`, `CONFIG_BLE_LOG_LBM_LL_TRANS_BUF_SIZE` - Add more LBMs: `CONFIG_BLE_LOG_LBM_ATOMIC_LOCK_TASK_CNT` - Increase baud rate (if your adapter supports it) @@ -210,12 +239,4 @@ If it only appears once at startup, this is normal. If persistent, check the bau - The console decodes REDIR frames automatically — no extra configuration needed - Logs are flushed by a 1-second periodic timer, so there may be a short delay -### `ModuleNotFoundError: No module named 'textual'` -Re-run the ESP-IDF installer: - -```bash -cd -./install.sh -. ./export.sh -```