# esp32-jk-bms

**Repository Path**: leeos/esp32-jk-bms

## Basic Information

- **Project Name**: esp32-jk-bms
- **Description**: esp32通过蓝牙来接jk保护板来显示实时BMS数据
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 3
- **Forks**: 1
- **Created**: 2026-05-28
- **Last Updated**: 2026-09-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ESP32-2432S028R — JK BMS & ANT BMS 蓝牙监控器

通过蓝牙低功耗（BLE）监控 **JK BMS** 和 **ANT BMS**，并在 **ESP32-2432S028R**（Cheap Yellow Display / CYD）开发板自带的2.8"触摸屏上显示数据。

## 功能特性

- **启动动画界面**：3秒倒计时后开始BLE扫描
- **自动BLE扫描**：扫描8秒后显示设备列表，同时检测 **JK BMS** 和 **ANT BMS**
- **自动重新扫描**：设备选择屏幕每12秒自动重新扫描
- **3个显示页面**，可通过触摸切换：
  - **页面1 - 主页**：总电压、电流、SOC、MOS/电池温度、容量、循环次数、充电/放电/均衡状态
  - **页面2 - 单体电压**：3列网格显示各单体电压，带颜色差异指示
  - **页面3 - 单体内阻**：3列网格显示各单体内阻（mΩ），仅支持JK旧协议（55AAEB90）
- **双JK BMS协议支持**：
  - 新TLV协议 `4E57`（标准BLE JK02）
  - 旧固定帧协议 `55AAEB90`（JK01 / 固件变体）
- **Legacy RS485桥接支持** (`EB90`)：兼容仅响应短ACK `FC xx 06` 的JK均衡器
- **ANT BMS支持**：通过 `7E A1` 协议（CRC-16/Modbus）——单体电压、电流、SOC、温度、容量、充放电/均衡状态
- **自动检测内阻偏移**：兼容不同固件版本
- **RGB LED状态指示**：显示BLE连接状态
- **看门狗与自动重连**：BLE断开时自动重新连接

## 硬件规格

| 组件 | 规格 |
|---|---|
| 开发板 | ESP32-2432S028R (CYD) |
| 主控 | ESP32 双核 240 MHz |
| 显示屏 | ILI9341 2.8" TFT 240×320, SPI (HSPI) |
| 触摸屏 | XPT2046, SPI (VSPI) |
| LED | RGB LED (低电平有效) |
| 无线 | BLE via NimBLE |

### 引脚定义

| 组件 | 引脚 |
|---|---|
| TFT MOSI | GPIO 13 |
| TFT MISO | GPIO 12 |
| TFT CLK  | GPIO 14 |
| TFT CS   | GPIO 15 |
| TFT DC   | GPIO 2  |
| TFT BL (背光) | GPIO 21 |
| LED 红色 | GPIO 4 |
| LED 绿色 | GPIO 16 |
| LED 蓝色 | GPIO 17 |
| Touch CS | GPIO 33 |
| Touch IRQ | GPIO 36 |

## 支持的BMS协议

### JK BMS — 新协议 `4E57` (JK02)
- BLE服务UUID: `0000ffe0-0000-1000-8000-00805f9b34fb`
- Notify: `FFE1` · Write: `FFE2`
- 帧头: `4E 57` (TLV tag-length-value)
- 数据: 单体电压、电流、SOC、温度、容量、告警、MOSFET状态

### JK BMS — 旧协议 `55AAEB90` (JK01 / 变体)
- 帧头: `55 AA EB 90`
- 帧类型 `0x02`: 单体数据（电压 + 单体内阻）
- 单体内阻: 自动检测偏移，单位mΩ（原始值直接为mΩ）
- 附加数据: 温度、电流、SOC、容量、告警

### JK Legacy RS485桥接 — `55AA ..` 请求 / `EB90 ..` 响应
- 主机请求: `55 AA <addr> FF 00 00 <checksum>`
- 从机响应: `EB 90 <addr> FF ...` 固定长度74字节
- Legacy短ACK `FC xx 06` 被识别为有效信号；固件会自动触发后续轮询
- ACK `FC xx 06` 在notify级别处理（包括桥接特性如 `FF12`），即使在数据包分段/混合时仍能检测到
- Legacy地址探测覆盖 `0x81`, `0x00`, `0x01`, `0x02`, `0x10` 以兼容BLE-RS485模块变体
- `EB90` 解析器提取总电压、单体数量、单体电压、均衡标志和告警

RS485请求校验和说明:
- 校验和计算为字节 `55 AA <addr> FF 00 00` 的和（模256）
- 例如地址 `0x81`: 有效请求为 `55 AA 81 FF 00 00 7F`

### ANT BMS — 协议 `7E A1`
- BLE服务UUID: `0000ffe0-0000-1000-8000-00805f9b34fb`
- Notify & Write: `FFE1`（双向共用一个特性）
- 帧头: `7E A1` · 响应类型: `0x11`
- CRC: CRC-16/Modbus 覆盖payload字节
- 请求: 10字节命令 `7E A1 01 00 00 BE 18 55 AA 55`
- 数据: 单体电压（LE uint16, mV）、传感器温度、MOS温度、总电压、电流、SOC、充放电/均衡状态、容量
- 设备检测: BLE名称包含 `"ANT"` 或 `"ant"`

## 系统要求

- [PlatformIO IDE](https://platformio.org/)（VS Code扩展）
- ESP32-2432S028R开发板通过USB连接
- JK BMS **或** ANT BMS（BLE已启用）

## 构建与上传

```bash
# 构建
pio run

# 构建并上传到开发板
pio run --target upload

# 打开串口监视器（115200波特率）
pio device monitor --baud 115200
```

或者使用VS Code PlatformIO工具栏中的 **Upload**（→）按钮。

## 项目结构

```
jk-bms-esp32-cyd/
├── src/
│   └── main.cpp          # 主固件代码
├── platformio.ini        # PlatformIO构建配置
├── README.md             # 项目文档
└── CHANGELOG.md          # 更新日志
```

## 串口监视器

打开115200波特率的串口监视器查看诊断日志，包括：
- BLE扫描和连接过程
- 每帧从BMS解析的数据
- 内阻偏移自动检测（`[OldProto] finalOffset=...`）
- 如果启用，C01异常值校正（`[OldProto] C01 outlier ...`）

## RGB LED状态指示

| LED颜色 | 状态 |
|---|---|
| 红色闪烁 | 启动中 / BLE扫描中 |
| 蓝色常亮 | 已连接到BMS |
| 绿色常亮 | 数据同步正常 |
| 黄色闪烁 | BLE连接失败，重试中 |

## 故障排除

### 无法连接到BMS
1. 确保BMS的BLE已启用
2. 确保开发板与BMS距离在10米以内
3. 检查串口日志查看扫描结果
4. 尝试重启开发板和BMS

### 电压/电流读数不准确
1. 调整 `platformio.ini` 中的校准常量
2. 设置 `DEBUG_PROTOCOL=1` 查看原始TLV数据
3. 参考BMS官方文档确认协议版本

### 触摸屏不响应
1. 检查触摸屏引脚连接
2. 确保触摸屏已正确校准
3. 尝试重新触摸（触摸屏有去抖延迟约600ms）

## 许可证

MIT License

## 贡献

欢迎提交Issue和Pull Request！

---

*基于ESP32-2432S028R开发板的JK BMS蓝牙监控器*