# CSI-Tools

**Repository Path**: LitzJ/csi-tools

## Basic Information

- **Project Name**: CSI-Tools
- **Description**: ESP-CSI-Array 上位机
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-28
- **Last Updated**: 2026-06-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# CSI Python Tools

本仓库保存 CSI 系统配套的 Python 上位机工具。

主要工具：

1. `csi_tool`
   离线 CSV 校验、统计、绘图，以及 S3 串口 GUI 上位机。
2. `c5_send_tool`
   C5-Send 独立临时串口控制面 GUI，用于发送端参数联调。

## 1. 运行环境

- Python `3.10` 或更高版本
- 运行依赖以 [pyproject.toml](pyproject.toml) 为准
- Windows 便捷启动脚本统一放在 [scripts](scripts) 目录，建议直接使用脚本准备和启动工具。
- [setup_csi_tool_env.bat](scripts/setup_csi_tool_env.bat) 会复用或创建 `tools/.venv` 虚拟环境，并在缺少依赖时执行 `pip install -e .`。
- 默认使用虚拟环境运行工具，不直接依赖本机全局 Python 包；本机 Python 只用于创建 `tools/.venv`。

准备环境：

```powershell
.\scripts\setup_csi_tool_env.bat
```

## 2. 当前能力

当前可用命令：

1. `validate`：CSV 格式校验（文件或目录）
2. `inspect`：输出统计摘要（支持 `--json-out`）
3. `loss`：按 `session_id + source_mac + tx_seq` 做跨槽位包完整性和丢包率统计
4. `plot`：生成图表 PNG（`rssi_trend/noise_floor_trend/csi_len_hist`）
5. `gui`：启动串口 GUI，上位机方式连接 `S3-BaseBoard`

GUI 的 `采集设置` 和 `系统配置` 页由 [device_config.toml](csi_tool/config/device_config.toml)
动态生成配置表单，用户无需直接手写 `SET_CONFIG` JSON。
当前串口控制面协议为 `PROTOCOL_VERSION = 3`，`SET_CONFIG` 只接受带
`scope/config` 的配置 envelope。

Windows 启动脚本会在虚拟环境缺少运行依赖时自动执行 `pip install -e .`，用于安装
`pyserial`、GUI 所需的 `PySide6`、实时/离线绘图所需的 `matplotlib`，
以及 Python 3.10 下解析 TOML 所需的 `tomli`。

当前工具默认面向新 CSV 表头：

```text
slot_id,board_uid,session_id,frame_id,tx_seq,local_timestamp_us,collector_uptime_ms,rssi,noise_floor,channel,csi_data_len,is_fake,source_mac,csi_hex
```

示例：

```bash
python -m csi_tool validate --input ./logs
python -m csi_tool inspect --input ./logs/collector_0001.csv --slot-id 0 --json-out ./out/inspect.json
python -m csi_tool loss --input ./logs/collector_0001.csv --slots 0-3 --json-out ./out/loss.json
python -m csi_tool plot --input ./logs/collector_0001.csv --output ./out/fig --slot-id 0
python -m csi_tool gui --mock
```

GUI 内的 `系统概览` 页可连接 `mock://demo` 或真实串口后周期刷新 `GET_RUNTIME_STATUS`，
并按槽位绘制保留窗口、帧编号、轮询/读帧速率和异常累计趋势，同时显示逐槽位运行状态。
`采集状态` 页使用独立的 `GET_CAPTURE_STATUS` 命令刷新 RSSI、噪声底和读帧速率等采集链路指标。

Windows 便捷启动脚本：

1. [setup_csi_tool_env.bat](scripts/setup_csi_tool_env.bat)：创建/修复 `tools/.venv` 并安装运行依赖
2. [launch_csi_tool_gui_serial.bat](scripts/launch_csi_tool_gui_serial.bat)：
   直接打开真实串口 GUI，默认填入 `COM8 / 3000000`，也可在 GUI 内修改
3. [launch_c5_send_tool_gui.bat](scripts/launch_c5_send_tool_gui.bat)：
   打开 `C5-Send` 临时 GUI，上位机默认使用 `115200` 波特率，可在 GUI 内修改

规划说明见：

- [CSI数据工具规划.md](./docs/technical/CSI数据工具规划.md)
- [csi_tool/README.md](csi_tool/README.md)

## 3. 文档导航

- [CSI 数据工具规划](docs/technical/CSI数据工具规划.md)
- [csi_tool 使用说明](csi_tool/README.md)
- [c5_send_tool 使用说明](c5_send_tool/README.md)
- [S3 串口交互协议](csi_tool/docs/串口交互协议.md)
- [系统项目总览](../docs/technical/项目总览.md)