From e89d809497a370f00c576df00263fce3bfb6c4ea Mon Sep 17 00:00:00 2001
From: acetaffy <acetaffy@users.noreply.git.acetaffy.ltd>
Date: Wed, 16 Sep 2026 16:13:06 +0800
Subject: [PATCH] docs: add project introduction and technical approach

---
 README.md | 162 +++++++++++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 147 insertions(+), 15 deletions(-)

diff --git a/README.md b/README.md
index b95d706..465685a 100644
--- a/README.md
+++ b/README.md
@@ -1,31 +1,163 @@
 # BMS Monitor
 
-Windows 只读型 BMS CAN 监控工具，面向兼容周立功 `ControlCAN.dll` 的 USBCAN-II 设备。
+BMS Monitor 是一款面向 Windows 平台的电池管理系统 CAN 实时监控软件，配合兼容周立功 `ControlCAN.dll` 的 USBCAN-II 设备使用。
 
-## 当前协议
+软件以只听模式接入 CAN 总线，不主动发送报文，适用于 BMS 调试、实车数据观察和电芯状态检查。
 
-- CAN 波特率：250 / 500 kbit/s（界面可选）
-- `0x140`：总电压、总电流、故障及状态（标准帧）
-- SOC 按 `当前总电压 ÷ 68V × 100%` 实时计算
-- `0x150` / `0x151` / `0x153` / `0x154`：16 路单体电压，以大端 16 位数值的 0.1mV 为单位
-- `0x156`：温度数据
-- 最高/最低单体电压和温度均从实际有效通道实时计算
-- 仍保留对文档扩展帧 `0x186040F3` / `0x186140F3` 的兼容解析
-- 应用没有声明 `VCI_Transmit`，不会发送 CAN 报文
+## 主要功能
+
+- 250 / 500 kbit/s 波特率切换
+- CAN1 / CAN2 通道选择
+- 实时显示总电压、总电流和 SOC
+- 显示 16 路单体电压及最高/最低值
+- 显示 10 路温度及最高/最低实际温度
+- 显示 BMS 工作状态和故障信息
+- 实时查看原始 CAN 报文
+- 最多保留最近 1000 帧，限制长期运行的内存占用
+
+## 技术路径
+
+### 1. CAN 硬件接入
+
+程序通过 P/Invoke 调用原生 `ControlCAN.dll` 接口：
+
+```text
+VCI_OpenDevice
+    ↓
+VCI_InitCAN
+    ↓
+VCI_StartCAN
+    ↓
+VCI_Receive
+    ↓
+VCI_ResetCAN
+    ↓
+VCI_CloseDevice
+```
+
+CAN 初始化采用硬件只听模式 `Mode = 1`。应用没有声明 `VCI_Transmit`，不会主动向 CAN 总线发送数据。
+
+### 2. 波特率配置
+
+| 波特率 | Timing0 | Timing1 |
+|---|---:|---:|
+| 250 kbit/s | `0x01` | `0x1C` |
+| 500 kbit/s | `0x00` | `0x1C` |
+
+连接时根据界面选择生成对应的 CAN 初始化参数。
+
+### 3. 异步报文接收
+
+连接成功后，后台任务循环调用 `VCI_Receive`，将原生数据转换为 `CanFrame`，再通过事件切换回 WPF UI 线程更新界面。
+
+每次最多读取 100 帧，接收等待时间为 50ms，兼顾实时性和 CPU 占用。
+
+### 4. 实际 CAN 协议
+
+| CAN ID | 数据内容 |
+|---|---|
+| `0x140` | 总电压、总电流、故障和工作状态 |
+| `0x150` | 电芯 1–4 |
+| `0x151` | 电芯 5–8 |
+| `0x153` | 电芯 9–12 |
+| `0x154` | 电芯 13–16 |
+| `0x156` | 温度数据 |
+
+同时保留对文档扩展帧 `0x186040F3` 和 `0x186140F3` 的兼容解析。
+
+### 5. 单体电压解析
+
+每个单体电压占用两个字节，采用大端格式，数值单位为 0.1mV：
+
+```text
+原始值 = Byte[n] × 256 + Byte[n+1]
+单体电压 = 原始值 ÷ 10000
+```
+
+例如：
+
+```text
+98 F3 → 0x98F3 → 39155 → 3.9155V
+```
+
+`0xFFFE` 和 `0xFFFF` 视为未接或无效通道，不参与最大值和最小值计算。
+
+### 6. 温度处理
+
+`0x156` 的前 8 个字节对应 8 路实际温度：
+
+```text
+温度 = 原始字节 - 40
+```
+
+`0xFF` 表示无效温度。界面显示 10 路温采，最高、最低温度只根据前 8 路实际温采计算。
+
+### 7. SOC 计算
+
+当前版本根据总电压进行线性估算：
+
+```text
+SOC = 当前总电压 ÷ 68V × 100%
+```
+
+结果四舍五入为整数，并限制在 0–100% 之间。
+
+### 8. 软件架构
+
+```text
+WPF 界面层
+├── 实时监控
+├── 电流 I
+├── 电芯与温度
+└── CAN 原始报文
+
+协议解析层
+├── BmsProtocolParser
+└── BmsSnapshot
+
+CAN 通信层
+├── ICanReceiver
+├── ControlCanReceiver
+├── ControlCanNative
+└── CanFrame
+```
+
+- `ControlCanNative`：声明原生 CAN 接口和数据结构
+- `ControlCanReceiver`：管理设备连接和后台接收
+- `BmsProtocolParser`：识别 CAN ID 并解析数据
+- `BmsSnapshot`：保存当前 BMS 状态
+- `MainWindow`：展示数据并响应用户操作
+
+## 技术栈
+
+- C# / .NET 8
+- WPF
+- P/Invoke
+- ControlCAN SDK
+- xUnit
+- Windows x86
+
+采用 x86 构建是为了匹配当前使用的 32 位 `ControlCAN.dll`。
 
 ## 使用
 
 1. 安装 CAN 盒厂商驱动。
-2. 项目已包含 `C:\Program Files (x86)\CANTest` 中的致远电子 x86 `ControlCAN.dll`，以及它运行所需的 `kerneldlls\kerneldll.ini` 和 `kerneldlls\usbcan.dll`，构建时会自动保留目录结构并复制到程序目录。
-3. CANH/CANL 接入 BMS 外部 CAN，并确认终端电阻。
-4. 选择 CAN1 或 CAN2，点击“连接”。
+2. 连接 CANH/CANL，并确认总线终端电阻。
+3. 启动程序，选择通道和波特率。
+4. 点击“连接”开始监听。
 
-项目默认使用 x86 构建，以匹配当前 CANTest 配套的 `ControlCAN.dll`：
+项目已包含 x86 `ControlCAN.dll` 以及运行所需的 `kerneldlls` 文件。
+
+## 构建与测试
 
 ```powershell
 dotnet build BmsMonitor.App/BmsMonitor.App.csproj -c Release -p:Platform=x86
 ```
 
+```powershell
+dotnet test BmsMonitor.Tests/BmsMonitor.Tests.csproj -c Release -p:Platform=x86
+```
+
 ## 安全边界
 
-本项目只包含打开、初始化、启动、接收、复位和关闭 API，不包含任何发送或参数配置功能。
+本项目只包含打开、初始化、启动、接收、复位和关闭 API，不包含任何 CAN 报文发送或参数配置功能。