admin/charging-cabinet
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
charging-cabinet/docs/protocol/1TN协议标准_YG20240118-1_V1.0.md
12451 619c96c85f docs: 文档分类整理 —— AGENTS.md 只留判据与链接，详细篇按用途归入 docs/ 子目录 
## 为什么要做

`AGENTS.md` 曾达 **90,370 B**，而工作区指令预算是 **65,536 B** —— 系统按**保留头部**截断，
于是**尾部约 25 KB 永远不会被加载**：组织架构、数据模型、TCP 协议、数据单位规范、
微信小程序用户端**全部处于"写了但读不到"的状态**。手册实际上部分失效。

## 一、AGENTS.md 瘦身：90,370 → 60,227 B（余量 5,309 B，尾部不再被截断）

三个**纯参考型大段**整段搬迁到 `docs/tech/`（**内容逐字保留，未删改**），
原位置换成「判据 + 链接」：

| 原 AGENTS.md 章节 | 大小 | 现位置 |
|---|---|---|
| `## 部署与维护` | 17,611 B | `docs/tech/部署手册.md` |
| `## 数据模型` | 12,100 B | `docs/tech/数据模型.md` |
| `## 微信小程序用户端` | 10,262 B | `docs/tech/小程序用户端.md` |

替换后的章节**只留改动前必须先知道的硬约束**（例如：产物名与测试环境落地名不一致、
ETXTBSY 的 `.new`→`stop`→`mv`→`start` 流程、`stream{}` 不可重加、发布顺序 device 先 api 后、
建表顺序即依赖顺序且写错报 MySQL 1824、时间列必须 DATETIME、`cabinets.status` 是配置态不表示在线……），
其余指向详细篇。**判据留在常驻加载的 AGENTS.md，逐项参考移出**。

## 二、docs/ 分类（原 21 个文件平铺 → 五个用途目录）

```
docs/
├── README.md          新增：文档地图（分类/权威性/旧名→现名映射/维护约定）
├── protocol/          设备协议（冻结，对硬件交付）★唯一权威
│   ├── 柜控板固件对接文档.md
│   └── 1TN协议标准_*.md / *.pdf
├── tech/              平台技术文档（开发/运维必读）
│   ├── API.md · 数据模型.md · 部署手册.md · 小程序用户端.md
├── contract/          合同·规格·验收标准（商务依据，不描述实现）
├── compound-notes/    单点经验笔记（原有）
└── archive/           ⛔ 历史留痕（只读，不代表现状，不可作依据）
    ├── 开发文档.md（早于现行实现）
    └── 审查报告/深度分析报告-2026-07-06
```

- 19 个文件用 `git mv` 迁移（保留历史），3 个未跟踪文件用普通移动；
- **内容零改动**（唯一例外是引用替换），已核验 `docs/tech/API.md` 的 `git diff` 为空。

## 三、全仓引用同步：40 处 / 10 个文件

路径不只出现在文档里，还散落在**源码注释**（`db/migrate.rs`、`routes/cabinets.rs`、
`workers/report_worker.rs`、`tcp/connection.rs`、`h5-uniapp/utils/format.ts`）、
`test/tcp_e2e_smoke.py`、`tasks/001-*.md`、`README.md`、`AGENTS.md` 中，全部同步。

**并已实测校验命令能失败**：往 `docs/tech/API.md` 植入 `<!-- probe: docs/API.md -->`
→ 命中；删除 → 无输出。
> ⚠️ 过程中踩了一个坑并已修：这些 `.md` 多为 **CRLF**，我第一次用 `\n` 正则删除时
> **没匹配上 `\r\n`**，以为删干净了其实残留了一行 —— 靠 `git diff` 非空才发现。
> 已把「CRLF 必须按 `\r?\n` 处理」写进 `docs/README.md` 的维护约定。

## 四、顺带查实的失效引用（归档保留原文，不改写历史）

- `docs/tcp-protocol.md`：仅出现在 2026-07-06 的两份历史报告里（当时的事实）；
- `docs/柜控板-平台TCP接口文档.md`：仅出现在协议文档 **v1.1 变更记录**里
  （记录"已删除该内部重复文档"这件事），**不是活链接**，无需修复。

两者已在 `docs/README.md` 的「旧名 → 现名映射」表中给出对应关系。
2026-09-20 04:42:51 +08:00

211 lines
6.3 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 换电柜用锂电池充电器 1TN 标准通信协议 RS485
- **标准号**：YG20240118-1
- **版本**：V1.0
- **制定方**：苏州翌工电源科技有限公司
- **适用范围**：换电柜 1TN 多路充电器 RS485 总线通信
---
## 版本记录
| 版本 | 修改内容 | 时间 | 修改人 |
|------|---------|------|--------|
| S1.0 | 初步建立1TN RS485协议内容 | 2024-01-18 | Eleven |
---
## 1. 概述
换电柜 1TN 多路充电器支持通过 RS485 总线进行通信，通信协议为客户自定义协议，采用 Modbus-RTU 传输模式，波特率 9600。
Modbus-RTU 传输模式在一根通讯线上采用主从应答方式的通讯连接方式。由主机发起，主机的信号寻址到一台唯一地址的终端设备（从机），然后终端设备发出的应答信号以相反的方向传输给主机，即半双工的工作模式。该协议只允许在主机和终端设备之间通讯，而不允许独立的终端设备之间的数据交换，这样各终端设备不会在它们初始化时占据通讯线路，而仅限于响应到达本机的查询信号。
### 1.1 通讯格式
信息传输为异步方式，并以字节为单位，在主机和从机之间传递的通讯信息是 11 位的字格式。包含 1 个起始位(0)，8 个数据位和 1 个停止位。
### 1.2 信息帧格式
| 字段 | 字节数 | 说明 |
|------|--------|------|
| ADDR | 1 | 地址码 |
| CHx | 1 | 通道码 |
| CMD | 1 | 功能码 |
| LEN | 1 | 数据区长度 |
| DATA | LEN | 数据区（BigEndian 网络字节序） |
| SUM | 1 | 校验码 = (ADDR + CHx + CMD + LEN + DATA) 按字节相加取低8位 |
### 1.3 通讯过程
信息发送至从机时，从机接收通讯命令，如果 SUM 校验无误则执行相应的操作，然后把执行结果（数据）返送给主机。返回的信息中包括 Header、CMD、ATS、执行后的数据以及 SUM 校验码和 END。如果校验出错就不返回任何信息，则分析返回相应的错误信息。
---
## 2. 地址码（ADDR）
对应电源拨码开关。
- **双拨码开关**：01→0x01, 10→0x02, 11→0x03
- **3位拨码开关**：001→0x01, 010→0x02, 011→0x03, 100→0x04, 101→0x05, 110→0x06, 111→0x07
---
## 3. 通道码（CHx）
对应各个通道识别码。
| 通道 | Bit1-7 | CHx值（Bit0=0主通道） | CHx值（Bit0=1副通道） |
|------|--------|----------------------|----------------------|
| CH1 | 0x00 | 0x00 | 0x01 |
| CH2 | 0x01 | 0x02 | 0x03 |
| CH3 | 0x02 | 0x04 | 0x05 |
| CH4 | 0x03 | 0x06 | 0x07 |
| CH5 | 0x04 | 0x08 | 0x09 |
| CH6 | 0x05 | 0x0A | 0x0B |
---
## 4. 功能码（CMD）
| 序号 | 命令 | CMD | LEN | 备注 |
|------|------|-----|-----|------|
| 1 | 设置通道输出电压/电流 | 0x02 | 0x04 | |
| 2 | 设置通道开关机 | 0x03 | 0x01 | |
| 3 | 通道组合指令（开关机/调压/调流） | 0x04 | 0x05 | |
| 4 | 电源通道信息查询 | 0x05 | 0x01 | |
| 5 | 供应商电源型号/版本号/序列号查询 | 0x12 | 0x01 | |
| 6 | 升级状态查询 | 0x18 | NC | 详见升级协议 |
| 7 | OTA 远程升级 | 0x19 | NC | 详见升级协议 |
---
## 5. 故障码
### 故障字节1
| Bit | 含义 | Bit | 含义 |
|-----|------|-----|------|
| Bit0 | 输入欠压 | Bit4 | 输出欠压 |
| Bit1 | 输入过压 | Bit5 | 输出短路 |
| Bit2 | NC | Bit6 | 输出过流 |
| Bit3 | 输出过压 | Bit7 | 过温 |
### 故障字节2
| Bit | 含义 | Bit | 含义 |
|-----|------|-----|------|
| Bit0 | 硬件故障 | Bit4 | NC |
| Bit1 | PFC故障 | Bit5 | NC |
| Bit2 | 风扇故障 | Bit6 | NC |
| Bit3 | 电池反接故障 | Bit7 | NC |
---
## 6. 指令示例
### 6.1 设置输出电压/电流（CMD=0x02）
**主控→电源：**
| ADDR | CHx | CMD | LEN | DATA | SUM |
|------|-----|-----|-----|------|-----|
| 0x01 | 0x00 | 0x02 | 0x04 | 0x02 0x58 0x00 0x64 | 0xC5 |
DATA：0x0258 = 60.0V, 0x0064 = 10.0A
**电源→主控：**
| ADDR | CHx | CMD | LEN | DATA | SUM |
|------|-----|-----|-----|------|-----|
| 0x01 | 0x00 | 0x02 | 0x01 | 0x01 | 0x05 |
回复：0x01 = 设置成功
### 6.2 设置开关机（CMD=0x03）
**主控→电源：**
| ADDR | CHx | CMD | LEN | DATA | SUM |
|------|-----|-----|-----|------|-----|
| 0x01 | 0x00 | 0x03 | 0x01 | 0x01 | 0x06 |
DATA：0x01 = 开机, 0x00 = 关机
**电源→主控：**
| ADDR | CHx | CMD | LEN | DATA | SUM |
|------|-----|-----|-----|------|-----|
| 0x01 | 0x00 | 0x03 | 0x01 | 0x01 | 0x06 |
回复：0x01 = 设置成功
### 6.3 组合控制命令（CMD=0x04）
**主控→电源：**
| ADDR | CHx | CMD | LEN | DATA | SUM |
|------|-----|-----|-----|------|-----|
| 0x01 | 0x00 | 0x04 | 0x05 | 0x01 0x02 0x58 0x00 0x64 | 0xC9 |
DATA: 0x01 = 开机, 0x0258 = 60.0V, 0x0064 = 10.0A
**电源→主控：**
| ADDR | CHx | CMD | LEN | DATA | SUM |
|------|-----|-----|-----|------|-----|
| 0x01 | 0x00 | 0x04 | 0x07 | 0x02 0x58 0x00 0x64 0x01 0x01 0x1A | 0xE6 |
回复DATA: 0x0258 = 当前电压60.0V, 0x0064 = 当前电流10.0A, 0x01 0x01 = 故障码, 0x1A = 环温26℃
### 6.4 读取通道运行信息（CMD=0x05）
**主控→电源：**
| ADDR | CHx | CMD | LEN | DATA | SUM |
|------|-----|-----|-----|------|-----|
| 0x01 | 0x00 | 0x05 | 0x01 | 0x00 | 0x07 |
**电源→主控：**
| ADDR | CHx | CMD | LEN | DATA | SUM |
|------|-----|-----|-----|------|-----|
| 0x01 | 0x00 | 0x05 | 0x0D | 0x02 0x58 0x00 0x64 0x01 0x01 0x1A 0x55 0xF0 0x03 0xE8 0x08 0x98 | 0xBD |
回复DATA解析：
| 偏移 | 数据 | 含义 |
|------|------|------|
| 0-1 | 0x0258 | 设置电压 60.0V |
| 2-3 | 0x0064 | 设置电流 10.0A |
| 4-5 | 0x0101 | 故障码 |
| 6 | 0x1A | 环温 26℃ |
| 7-8 | 0x55F0 | 输入电压 220.00V |
| 9-10 | 0x03E8 | 输入电流 10.00A |
| 11-12 | 0x0898 | 输入功率 2200W |
### 6.5 查询供应商信息（CMD=0x12）
**主控→电源：**
| ADDR | CHx | CMD | LEN | DATA | SUM |
|------|-----|-----|-----|------|-----|
| 0x01 | 0x00 | 0x12 | 0x01 | 0x00 | 0x14 |
**电源→主控：**
| ADDR | CHx | CMD | LEN | DATA |
|------|-----|-----|-----|------|
| 0x01 | 0x00 | 0x12 | 0x0F | 'YGCP1TN-A' + 硬件版本 + 软件版本 + 日期(年/月/日) + 序列号 |
回复DATA解析：
| 偏移 | 含义 |
|------|------|
| 0-1 | 厂商 ('YG') |
| 2-9 | 电源型号 ('CP1TN-A') |
| 10 | 硬件版本 (S1.0) |
| 11 | 软件版本 (V1.0) |
| 12-14 | 生产日期 (年/月/日) |
| 15-16 | 序列号 |
Reference in New Issue View Git Blame Copy Permalink