# pile-server

**Repository Path**: wangszab/pile-server

## Basic Information

- **Project Name**: pile-server
- **Description**: Pile Server 是一款基于 云快充平台协议开发的开源充电桩云端调试与通信平台，模拟云快充平台服务端，通过TCP二进制协议与充电桩直接通信，覆盖协议全部核心业务流程，是充电桩出厂测试、协议联调、功能验证、固件开发的高效工具，无需依赖官方云平台，本地即可完成全流程调试。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-04-23
- **Last Updated**: 2026-07-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Pile Server - 云快充协议充电桩调试平台

一款基于 [云快充平台协议 V1.5/6](docs/云快充平台协议V1.5.pdf) 的开源充电桩云端调试与通信平台。模拟云快充平台服务端，通过 TCP 二进制协议与充电桩直接通信，覆盖了协议中全部核心业务流程，是充电桩出厂测试、协议联调、功能验证的理想工具。

## 核心特性

- **全协议覆盖** -- 实现 20+ 个协议指令处理，涵盖登录认证、计费模型、充电控制、实时数据、BMS 交互、远程维护等完整业务链路
- **一键启动** -- 拉起即用，充电桩配置平台 IP 和端口后直连，无需额外对接云平台
- **RESTful API** -- 提供完整的 HTTP 接口，可通过 Postman / Swagger 快速下发充电控制指令
- **实时监控** -- 充电过程电压、电流、SOC、电量、金额等关键数据实时采集与存储
- **多桩并发** -- 基于 Netty 高性能异步框架，支持多台充电桩同时在线
- **CRC 兼容** -- 自动识别不同厂商充电桩 CRC 高低位差异，无需手动适配

## 技术栈

| 组件 | 技术 |
|------|------|
| Web 框架 | Spring Boot 2.3.7 |
| 通信框架 | Netty 4.1.111 |
| 数据库 | MySQL + MyBatis-Plus |
| 缓存 | Redis |
| API 文档 | Swagger 2 |
| 构建工具 | Maven |
| JDK | 17 |

## 快速开始

### 1. 环境准备

- JDK 17+
- MySQL 8.0+
- Redis

### 2. 数据库初始化

创建数据库并执行建表语句（项目运行后根据实体类生成，或参考 `model/db` 包下的实体定义）：

```sql
CREATE DATABASE engine_backend DEFAULT CHARACTER SET utf8mb4;
```

### 3. 修改配置

编辑 `src/main/resources/application.yml`：

```yaml
spring:
  datasource:
    url: jdbc:mysql://127.0.0.1:3306/engine_backend?useUnicode=true&characterEncoding=utf-8&useSSL=false&serverTimezone=GMT%2B8
    username: your_username
    password: your_password
  redis:
    host: 127.0.0.1
    port: 6379
    password: your_redis_password
```

### 4. 编译运行

```bash
mvn clean package -DskipTests
java -jar target/pile-server-0.0.1-SNAPSHOT.jar
```

### 5. 充电桩连接

将充电桩平台地址配置为本机 IP，TCP 端口配置为 **8888**，充电桩将自动发起登录。

## 协议指令一览

### 登录认证

| 指令 | 方向 | 说明 |
|------|------|------|
| 0x01 / 0x02 | 桩 -> 平台 / 平台 -> 桩 | 充电桩登录注册，解析桩编号(BCD)、类型、枪数、协议版本、软件版本 |
| 0x03 / 0x04 | 桩 -> 平台 / 平台 -> 桩 | 心跳保活，上报枪状态 |

### 计费模型

| 指令 | 方向 | 说明 |
|------|------|------|
| 0x05 / 0x06 | 桩 <-> 平台 | 计费模型验证 |
| 0x09 / 0x0A | 桩 <-> 平台 | 计费模型请求，返回尖峰平谷四段费率 + 48 个半小时时段 |
| 0x58 / 0x57 | 平台 -> 桩 / 桩 -> 平台 | 主动下发计费模型设置 |
| 0x3B / 0x40 | 桩 -> 平台 / 平台 -> 桩 | 交易账单上报，含四段分时电量、电表值、VIN、停止原因 |

### 充电控制

| 指令 | 方向 | 说明 |
|------|------|------|
| 0x34 / 0x33 | 平台 -> 桩 / 桩 -> 平台 | 远程启动充电（流水号、桩号、枪号、卡号、余额） |
| 0x36 / 0x35 | 平台 -> 桩 / 桩 -> 平台 | 远程停止充电 |

### 实时数据与 BMS

| 指令 | 方向 | 说明 |
|------|------|------|
| 0x12 / 0x13 | 平台 -> 桩 / 桩 -> 平台 | 实时数据采集（电压、电流、SOC、电量、金额、故障位），支持变位上送 |
| 0x15 | 桩 -> 平台 | 充电握手（BMS 版本、电池类型、容量、VIN 码） |
| 0x17 | 桩 -> 平台 | BMS 参数配置（单体电压/电流/标称能量/SOC） |
| 0x19 | 桩 -> 平台 | 充电结束（SOC、单体电压、温度、时长、能量） |
| 0x1B | 桩 -> 平台 | 错误报文（64 位错误位图） |
| 0x1D | 桩 -> 平台 | BMS 中止充电（含中止原因枚举） |
| 0x21 | 桩 -> 平台 | 充电机中止充电 |
| 0x25 | 桩 -> 平台 | BMS 充电过程信息（温度 + 7 种状态位图） |

### 远程维护

| 指令 | 方向 | 说明 |
|------|------|------|
| 0x92 / 0x91 | 平台 -> 桩 / 桩 -> 平台 | 远程重启 |
| 0x94 / 0x93 | 平台 -> 桩 / 桩 -> 平台 | 远程升级（FTP 服务器地址、固件路径） |
| 0x56 / 0x55 | 平台 -> 桩 / 桩 -> 平台 | 对时同步（CP56Time2a 编码） |
| 0x52 / 0x57 | 平台 -> 桩 / 桩 -> 平台 | 设置工作参数（启用/锁桩/功率百分比） |
| 0xF0 / 0xF1 | 平台 -> 桩 / 桩 -> 平台 | 二维码前缀下发 |

## REST API

启动后访问 `http://localhost:8080/swagger-ui.html` 查看完整 API 文档，**直接操作最简单**。

### 充电控制

```bash
# 启动充电
curl -X POST http://localhost:8080/v1/charge/startCharge \
  -H "Content-Type: application/json" \
  -d '{"pileCode":"桩编号","gunNo":1,"amount":10000}'

# 停止充电
curl -X POST http://localhost:8080/v1/charge/stopCharge \
  -H "Content-Type: application/json" \
  -d '{"pileCode":"桩编号","gunNo":1}'

# 下发计费模型
curl -X POST http://localhost:8080/v1/charge/setfee \
  -H "Content-Type: application/json" \
  -d '{"pileCode":"桩编号"}'
```

### 计费模型管理

```bash
# 查询所有计费模型
curl http://localhost:8080/v1/feemodel/all

# 新增计费模型
curl -X POST http://localhost:8080/v1/feemodel \
  -H "Content-Type: application/json" \
  -d '{"strategyCode":"MODEL_001","name":"标准费率","feeDetailList":[...]}'
```

### 远程维护

```bash
# 远程重启
curl -X POST http://localhost:8080/v1/maintenance/restart \
  -H "Content-Type: application/json" \
  -d '{"pileCode":"桩编号","value":1}'

# 远程升级
curl -X POST http://localhost:8080/v1/maintenance/upgrade \
  -H "Content-Type: application/json" \
  -d '{"pileCode":"桩编号","serverIp":"192.168.1.100","serverPort":21,"username":"ftp","password":"123","filePath":"/firmware/update.bin"}'

# 设置工作参数
curl -X POST http://localhost:8080/v1/maintenance/setparam \
  -H "Content-Type: application/json" \
  -d '{"pileCode":"桩编号","enable":1,"maxPower":100}'
```

## 项目结构

```
src/main/java/com/anbei/pile/
├── PileServerApplication.java          # 启动入口
├── config/
│   ├── NettyConfig.java                # Netty TCP 服务配置
│   └── RedisConfig.java                # Redis 配置
├── codec/
│   ├── FrameCodec.java                 # 帧编解码 + CRC 校验
│   ├── DataConverter.java              # BCD/BIN/ASCII/CP56Time2a 转换
│   └── FeeUtil.java                    # 计费模型编解码
├── handler/                            # 协议帧处理器
│   ├── FrameHandler.java               # 处理器接口
│   ├── FrameHandlerRegistry.java       # 处理器注册中心
│   ├── ChannelManager.java             # 桩连接管理
│   ├── MasterHandler.java              # Netty 主处理器
│   └── impl/
│       ├── LoginFrameHandler.java      # 登录认证
│       ├── HeartbeatFrameHandler.java  # 心跳
│       ├── charge/                     # 充电控制
│       ├── fee/                        # 计费模型
│       ├── realtime/                   # 实时数据与 BMS
│       └── mantenance/                 # 远程维护
├── controller/                         # REST API
│   ├── ChargeController.java           # 充电控制
│   ├── FeeStrategyController.java      # 计费模型管理
│   ├── MaintenanceController.java      # 维护指令
│   └── RealController.java             # 实时数据
├── service/                            # 业务服务层
├── model/                              # 数据模型
│   ├── db/                             # 数据库实体
│   ├── realtime/                       # 实时数据模型
│   ├── fee/                            # 计费模型
│   └── maintenance/                    # 维护指令模型
├── mapper/                             # MyBatis 数据访问
└── job/                                # 定时任务
    └── TimeSyncTask.java               # 每日全网对时
```

## 通信架构

```
                         充电桩 (TCP Client)
                               │
                               │ TCP :8888
                               ▼
              ┌─────────────────────────────────┐
              │         Netty Pipeline           │
              │                                  │
              │  FrameStartValidator             │  帧分界 (扫描 0x68)
              │         │                        │
              │  MasterHandler                   │
              │    ├── FrameCodec.decode()       │  CRC 校验 + 解码
              │    ├── HandlerRegistry.get()     │  路由到对应 Handler
              │    └── Handler.handle()          │  业务处理
              │         │                        │
              │    FrameCodec.encode()           │  编码 + CRC 生成
              └────────┬────────────────────────┘
                       │
                       ▼
              ┌─────────────────────────────────┐
              │    Spring Boot 业务层 :8080      │
              │    REST API + Swagger + Web UI   │
              └─────────────────────────────────┘
```

## 协议数据编码

| 类型 | 用途 | 示例 |
|------|------|------|
| BCD | 桩编号(7B)、交易流水号(16B)、枪号(1B) | `0x01 0x23 0x45 0x67 0x89 0x01 0x23` |
| BIN | 电压(2B x0.1V)、电流(2B x0.1A)、电量(4B x0.0001kWh) | `0x03E8` = 220.0V |
| CP56Time2a | 7 字节时间编码（毫秒+分+时+日+月+年+星期） | IEC 60870-5-4 标准 |
| ASCII | 软件版本(8B)、VIN 码(17B)、电池厂商(4B) | `"V3.5.0\0\0\0"` |

## 计费模型

支持四段分时电价，每段含电费和服务费，通过 48 个半小时时段（00:00 ~ 23:30）映射：

| 段 | 标识 | 说明 |
|----|------|------|
| 尖 | 0x00 | 尖峰电价 |
| 峰 | 0x01 | 高峰电价 |
| 平 | 0x02 | 平段电价 |
| 谷 | 0x03 | 低谷电价 |

## 适用场景

- **充电桩厂商** -- 出厂前协议一致性测试，验证云快充协议对接是否正确
- **充电运营商** -- 充电桩接入云快充前的本地调试，排查通信问题
- **嵌入式开发** -- 充电桩固件开发阶段的协议调试，无需等待云平台部署
- **第三方集成** -- 接入云快充生态前的技术验证和可行性评估

## 端口说明

| 端口 | 协议 | 用途 |
|------|------|------|
| 8080 | HTTP | REST API、Swagger 文档、Web 管理界面 |
| 8888 | TCP | 充电桩二进制协议通信 |

## 参考文档

- [云快充平台协议 V1.5](docs/云快充平台协议V1.5.pdf)
- [云快充1.5协议 - 二维码远程下发指令补充](docs/云快充1.5协议-二维码远程下发指令补充-2021-11-18.pdf)

## License

MIT