mirror of https://gitee.com/san-bing/JChargePointProtocol synced 2026-07-18 12:48:26 +08:00

Files

三丙 fa9524d302 wiki生成

2025-10-28 14:39:06 +08:00

21 KiB

Raw Blame History

绿能协议实现

**本文档中引用的文件** - [LvnengV340ProtocolBootstrap.java](file://jcpp-protocol-lvneng/src/main/java/sanbing/jcpp/protocol/lvneng/v340/LvnengV340ProtocolBootstrap.java) - [LvnengProtocolMessageProcessor.java](file://jcpp-protocol-lvneng/src/main/java/sanbing/jcpp/protocol/lvneng/LvnengProtocolMessageProcessor.java) - [LvnengUplinkCmdExe.java](file://jcpp-protocol-lvneng/src/main/java/sanbing/jcpp/protocol/lvneng/LvnengUplinkCmdExe.java) - [LvnengDownlinkCmdExe.java](file://jcpp-protocol-lvneng/src/main/java/sanbing/jcpp/protocol/lvneng/LvnengDownlinkCmdExe.java) - [LvnengDownlinkCmdConverter.java](file://jcpp-protocol-lvneng/src/main/java/sanbing/jcpp/protocol/lvneng/mapping/LvnengDownlinkCmdConverter.java) - [LvnengV340RealTimeDataULCmd.java](file://jcpp-protocol-lvneng/src/main/java/sanbing/jcpp/protocol/lvneng/v340/cmd/LvnengV340RealTimeDataULCmd.java) - [LvnengUplinkMessage.java](file://jcpp-protocol-lvneng/src/main/java/sanbing/jcpp/protocol/lvneng/LvnengUplinkMessage.java) - [LvnengDwonlinkMessage.java](file://jcpp-protocol-lvneng/src/main/java/sanbing/jcpp/protocol/lvneng/LvnengDwonlinkMessage.java) - [LvnengProtocolConstants.java](file://jcpp-protocol-lvneng/src/main/java/sanbing/jcpp/protocol/lvneng/LvnengProtocolConstants.java) - [ProtocolCommandRouter.java](file://jcpp-protocol-api/src/main/java/sanbing/jcpp/protocol/routing/ProtocolCommandRouter.java) - [AbstractLvnengCmdExe.java](file://jcpp-protocol-lvneng/src/main/java/sanbing/jcpp/protocol/lvneng/AbstractLvnengCmdExe.java) - [LvnengV340SetPricingModelDLCmd.java](file://jcpp-protocol-lvneng/src/main/java/sanbing/jcpp/protocol/lvneng/v340/cmd/LvnengV340SetPricingModelDLCmd.java) - [LvnengV340RemoteStopDLCmd.java](file://jcpp-protocol-lvneng/src/main/java/sanbing/jcpp/protocol/lvneng/v340/cmd/LvnengV340RemoteStopDLCmd.java)

简介

绿能协议（v3.40）是一个专为电动汽车充电站设计的通信协议，实现了充电桩与服务器之间的可靠数据交换。该协议采用TCP传输层，具有严格的消息帧结构、校验和验证机制和完善的命令处理体系。

本文档深入分析了绿能协议v3.40的实现细节，重点关注LvnengV340ProtocolBootstrap的配置机制、消息帧结构的设计、以及LvnengProtocolMessageProcessor的处理逻辑。同时详细阐述了上行命令处理器和下行指令生成机制，展示了从gRPC调用到协议报文构建的完整流程。

项目结构

绿能协议模块采用分层架构设计，主要包含以下核心包结构：

graph TB
subgraph "协议核心模块"
A[jcpp-protocol-lvneng]
A --> B[v340 - 协议版本实现]
A --> C[mapping - 命令映射]
A --> D[enums - 枚举定义]
A --> E[cmd - 命令处理器]
end
subgraph "基础框架"
F[jcpp-protocol-api]
G[jcpp-protocol-bootstrap]
H[jcpp-protocol-yunkuaichong]
end
subgraph "基础设施"
I[jcpp-infrastructure-util]
J[jcpp-infrastructure-cache]
K[jcpp-infrastructure-queue]
end
A --> F
F --> I
F --> J
F --> K

图表来源

章节来源

核心组件

绿能协议的核心组件包括协议引导器、消息处理器、命令执行器和命令转换器等关键模块。这些组件协同工作，实现了完整的协议栈功能。

协议引导器（LvnengV340ProtocolBootstrap）

协议引导器负责初始化和配置整个协议栈，它继承自基础的ProtocolBootstrap类，提供了协议特定的初始化逻辑。

消息处理器（LvnengProtocolMessageProcessor）

消息处理器是协议的核心，负责解析和处理所有上行和下行消息。它实现了严格的帧结构解析、校验和验证和命令路由功能。

命令执行器基类

系统提供了两个抽象基类：LvnengUplinkCmdExe用于处理上行命令，LvnengDownlinkCmdExe用于处理下行命令。它们都继承自AbstractLvnengCmdExe，提供了统一的编码和发送机制。

章节来源

架构概览

绿能协议采用事件驱动的异步处理架构，通过Netty框架实现高效的网络通信。整个架构分为消息接收层、协议处理层、命令执行层和业务逻辑层。

graph TB
subgraph "网络层"
A[TCP连接] --> B[消息解码器]
B --> C[帧解析器]
end
subgraph "协议处理层"
C --> D[LvnengProtocolMessageProcessor]
D --> E[上行命令路由]
D --> F[下行命令路由]
end
subgraph "命令执行层"
E --> G[LvnengUplinkCmdExe]
F --> H[LvnengDownlinkCmdExe]
G --> I[业务逻辑处理]
H --> J[协议报文生成]
end
subgraph "数据转换层"
K[LvnengDownlinkCmdConverter] --> H
L[消息对象封装] --> G
L --> H
end
subgraph "输出层"
I --> M[UplinkQueueMessage]
J --> N[编码后的字节数组]
end

图表来源

详细组件分析

LvnengV340ProtocolBootstrap配置机制

LvnengV340ProtocolBootstrap作为协议的入口点，负责建立TCP监听器和初始化协议上下文。它通过注解@ProtocolComponent标记协议名称，并重写父类方法提供具体的初始化逻辑。

classDiagram
class LvnengV340ProtocolBootstrap {
+String PROTOCOL_NAME
+getProtocolName() String
+_init() void
+_destroy() void
+messageProcessor() ProtocolMessageProcessor
}
class ProtocolBootstrap {
<<abstract>>
+forwarder Forwarder
+protocolContext ProtocolContext
+messageProcessor() ProtocolMessageProcessor
}
class LvnengProtocolMessageProcessor {
+uplinkRouter ProtocolCommandRouter
+downlinkRouter ProtocolCommandRouter
+downlinkCmdConverter DownlinkCmdConverter
+uplinkHandle(ListenerToHandlerMsg) void
+doDownlinkHandle(SessionToHandlerMsg) void
}
LvnengV340ProtocolBootstrap --|> ProtocolBootstrap
LvnengV340ProtocolBootstrap --> LvnengProtocolMessageProcessor : creates

图表来源

LvnengV340ProtocolBootstrap.java

消息帧结构设计

绿能协议采用严格的帧结构设计，确保消息的可靠传输和完整性验证。帧结构包括起始标志、长度字段、加密标识、序列号、命令字和校验和等关键字段。

字段名称	长度（字节）	描述
起始标志	2	固定值0xAAF5，标识帧开始
数据长度	2	包含头部和校验和在内的总长度
加密标识	1	0x10表示加密，0x00表示明文
序列号	1	用于消息顺序控制
命令字	2	标识具体命令类型
数据域	可变	实际消息内容
校验和	1	对命令字和数据域的校验

LvnengProtocolMessageProcessor消息处理

消息处理器实现了复杂的消息解析逻辑，包括帧头解析、长度验证、校验和计算和命令路由等功能。

sequenceDiagram
participant Client as 客户端
participant Processor as LvnengProtocolMessageProcessor
participant Router as 命令路由器
participant Executor as 命令执行器
participant Forwarder as 消息转发器
Client->>Processor : 接收原始消息
Processor->>Processor : 解析帧头信息
Processor->>Processor : 验证消息长度
Processor->>Processor : 读取消息体
Processor->>Processor : 计算并验证校验和
Processor->>Router : 查找命令执行器
Router->>Executor : 返回匹配的执行器
Executor->>Executor : 执行业务逻辑
Executor->>Forwarder : 转发处理结果
Forwarder->>Client : 发送响应消息

图表来源

LvnengProtocolMessageProcessor.java

章节来源

LvnengProtocolMessageProcessor.java

协议消息处理流程

上行消息处理流程

上行消息处理涉及复杂的帧解析和命令执行过程。处理器首先验证消息格式，然后提取各个字段，最后通过命令路由机制找到对应的执行器。

flowchart TD
Start([接收上行消息]) --> ParseHeader["解析帧头信息<br/>起始标志 + 长度 + 加密标识 + 序列号 + 命令字"]
ParseHeader --> ValidateLength{"验证消息长度<br/>dataLength >= 9?"}
ValidateLength --> |否| LogWarning["记录警告日志"]
ValidateLength --> |是| ReadBody["读取消息体<br/>msgBodyLength = dataLength - 9"]
ReadBody --> CalcChecksum["计算校验和<br/>sumData = 命令字 + 数据域"]
CalcChecksum --> VerifyChecksum{"校验和验证"}
VerifyChecksum --> |失败| LogError["记录错误日志"]
VerifyChecksum --> |成功| BuildMessage["构建LvnengUplinkMessage对象"]
BuildMessage --> RouteCommand["命令路由查找"]
RouteCommand --> ExecuteCmd["执行命令处理器"]
ExecuteCmd --> SendResponse["发送响应消息"]
LogWarning --> End([处理结束])
LogError --> End
SendResponse --> End

图表来源

LvnengProtocolMessageProcessor.java

下行消息处理流程

下行消息处理从gRPC调用开始，经过命令转换、消息构建和协议编码等步骤，最终生成符合绿能协议规范的报文。

flowchart TD
Start([接收gRPC调用]) --> ConvertCmd["命令转换<br/>DownlinkCmdEnum -> 协议命令字"]
ConvertCmd --> ValidateSupport{"验证命令支持"}
ValidateSupport --> |不支持| LogUnsupported["记录不支持命令"]
ValidateSupport --> |支持| BuildMessage["构建LvnengDwonlinkMessage"]
BuildMessage --> ExtractData["提取请求数据"]
ExtractData --> RouteCommand["命令路由查找"]
RouteCommand --> ExecuteCmd["执行命令处理器"]
ExecuteCmd --> EncodeMsg["编码协议消息<br/>帧头 + 长度 + 加密 + 序列号 + 命令字 + 数据域 + 校验和"]
EncodeMsg --> SendMsg["发送到TCP会话"]
LogUnsupported --> End([处理结束])
SendMsg --> End

图表来源

LvnengProtocolMessageProcessor.java

章节来源

LvnengProtocolMessageProcessor.java

命令路由机制

ProtocolCommandRouter实现

ProtocolCommandRouter提供了基于协议名和命令字的智能路由功能，支持自动扫描和注册命令执行器，实现了松耦合的命令处理架构。

classDiagram
class ProtocolCommandRouter~T~ {
-Map~String,T~ executorMap
+ProtocolCommandRouter(Class, Predicate)
+getExecutor(String, int) T
-initializeRoutes(Class, Predicate) void
-registerExecutor(Class) void
-buildKey(String, int) String
}
class LvnengUplinkCmdExe {
<<abstract>>
+execute(TcpSession, LvnengUplinkMessage, ProtocolContext) void
#uplinkMessageBuilder(String, TcpSession, LvnengUplinkMessage) UplinkQueueMessage.Builder
}
class LvnengDownlinkCmdExe {
<<abstract>>
+execute(TcpSession, LvnengDwonlinkMessage, ProtocolContext) void
}
class LvnengV340RealTimeDataULCmd {
+execute(TcpSession, LvnengUplinkMessage, ProtocolContext) void
}
class LvnengV340SetPricingModelDLCmd {
+execute(TcpSession, LvnengDwonlinkMessage, ProtocolContext) void
}
ProtocolCommandRouter --> LvnengUplinkCmdExe : routes
ProtocolCommandRouter --> LvnengDownlinkCmdExe : routes
LvnengUplinkCmdExe <|-- LvnengV340RealTimeDataULCmd
LvnengDownlinkCmdExe <|-- LvnengV340SetPricingModelDLCmd

图表来源

命令注册机制

系统通过@ProtocolCmd注解自动发现和注册命令执行器，每个执行器可以支持多个协议版本。这种设计使得协议升级更加灵活。

章节来源

数据包格式与处理

上行命令处理示例：实时数据上报

LvnengV340RealTimeDataULCmd展示了典型的上行命令处理流程，包括数据解析、状态更新和消息转发。

sequenceDiagram
participant Pile as 充电桩
participant Cmd as LvnengV340RealTimeDataULCmd
participant Session as TCP会话
participant Context as 协议上下文
participant Forwarder as 消息转发器
Pile->>Cmd : 接收实时数据上报
Cmd->>Cmd : 解析消息体<br/>充电桩编码 + 枪口数量 + 枪口号
Cmd->>Cmd : 提取状态信息<br/>工作状态 + SOC + 告警码
Cmd->>Cmd : 解析电气参数<br/>电压、电流、电量
Cmd->>Session : 更新会话信息
Cmd->>Context : 注册会话
Cmd->>Cmd : 构建状态消息<br/>GunRunStatusProto
Cmd->>Forwarder : 转发状态信息
Cmd->>Cmd : 构建充电进度消息<br/>ChargingProgressProto
Cmd->>Forwarder : 转发充电进度
Cmd->>Cmd : 发送应答消息<br/>REAL_TIME_DATA_ACK

图表来源

LvnengV340RealTimeDataULCmd.java

下行命令处理示例：设置定价模型

LvnengV340SetPricingModelDLCmd演示了下行命令的处理流程，包括参数解析、数据转换和响应生成。

sequenceDiagram
participant Server as 服务器
participant Cmd as LvnengV340SetPricingModelDLCmd
participant Session as TCP会话
participant Cache as 请求缓存
Server->>Cmd : 接收定价模型设置
Cmd->>Cmd : 验证消息格式<br/>SetPricingRequest
Cmd->>Cmd : 解析计费规则<br/>时段计价或阶梯计价
Cmd->>Cmd : 构建响应数据<br/>48个时间段 * 12字节
Cmd->>Cache : 存储请求ID
Cmd->>Session : 发送应答消息<br/>SET_PRICING_ACK

图表来源

LvnengV340SetPricingModelDLCmd.java

章节来源

实际应用示例

协议命令转换机制

LvnengDownlinkCmdConverter作为命令转换器，建立了通用命令与协议特定命令字之间的映射关系。这种设计确保了协议的可扩展性和向后兼容性。

通用命令	绿能协议命令字	描述
LOGIN_ACK	105	登录应答
SYNC_TIME_REQUEST	3	时间同步请求
TRANSACTION_RECORD_ACK	201	交易记录应答
HEARTBEAT_ACK	101	心跳应答
REAL_TIME_DATA_ACK	103	实时数据应答
SET_PRICING	1103	设置定价模型
REMOTE_STOP_CHARGING	5	远程停止充电
SET_QRCODE	3	设置二维码

消息对象结构

系统定义了专门的消息对象来封装协议数据，提供了类型安全的数据访问接口。

classDiagram
class LvnengUplinkMessage {
-UUID id
-int head
-int dataLength
-int sequenceNumber
-int encryptionFlag
-int cmd
-byte[] msgBody
-int checkSum
-byte[] rawFrame
+getId() UUID
+getCmd() int
+getMsgBody() byte[]
+getRawFrame() byte[]
}
class LvnengDwonlinkMessage {
-UUID id
-UUID requestId
-int cmd
-DownlinkRequestMessage msg
-LvnengUplinkMessage requestData
+getId() UUID
+getCmd() int
+getRequestId() UUID
+getMsg() DownlinkRequestMessage
}
class AbstractLvnengCmdExe {
#encode(int, int, int, ByteBuf) byte[]
#encodeAndWriteFlush(int, ByteBuf, TcpSession) void
#encodeAndWriteFlush(DownlinkCmdEnum, ByteBuf, TcpSession) void
}
LvnengDwonlinkMessage --> LvnengUplinkMessage : requestData
AbstractLvnengCmdExe --> LvnengUplinkMessage : processes
AbstractLvnengCmdExe --> LvnengDwonlinkMessage : processes

图表来源

章节来源

性能考虑

绿能协议在设计时充分考虑了性能优化，采用了多种技术手段来提高系统的响应速度和吞吐量。

异步处理机制

系统采用Netty框架实现异步I/O操作，避免了线程阻塞，提高了并发处理能力。消息处理完全基于事件驱动，能够高效处理大量并发连接。

内存管理优化

使用ByteBuf进行零拷贝操作，减少内存分配和垃圾回收压力
采用对象池技术复用消息对象，降低GC频率
合理设计消息结构，减少不必要的数据复制

缓存策略

命令路由表采用ConcurrentHashMap实现，提供O(1)的查找性能
请求ID缓存机制避免重复处理相同请求
会话状态信息本地化存储，减少数据库访问

故障排除指南

常见问题诊断

消息解析失败

检查帧头是否为0xAAF5
验证消息长度是否正确
确认校验和计算是否准确

命令路由失败

确认命令执行器是否正确注册
检查@ProtocolCmd注解配置
验证协议名称匹配

连接异常

检查TCP连接状态
验证网络防火墙设置
确认端口监听状态

日志分析

系统提供了详细的日志记录，帮助快速定位问题：

WARN级别：消息格式异常、校验和失败
ERROR级别：命令执行异常、系统内部错误
DEBUG级别：消息处理流程跟踪

章节来源

LvnengProtocolMessageProcessor.java

总结

绿能协议v3.40实现了一个功能完整、性能优异的电动汽车充电站通信协议。通过模块化的架构设计、严格的帧结构规范和智能的命令路由机制，系统实现了高可靠性的消息传输和处理。

主要特性

严格的协议规范：采用标准的帧结构和校验机制，确保消息传输的可靠性
灵活的命令处理：支持多种命令类型，具备良好的扩展性
高性能架构：基于Netty的异步处理，支持高并发场景
完善的错误处理：提供详细的日志记录和异常处理机制
类型安全设计：使用强类型的消息对象，减少运行时错误

技术优势

模块化设计：各组件职责明确，便于维护和扩展
自动化注册：通过注解机制自动发现和注册命令执行器
性能优化：采用多种优化技术，确保系统高效运行
向后兼容：支持协议版本升级，保证系统稳定性

该协议实现为电动汽车充电站提供了稳定可靠的通信基础，支撑了大规模充电网络的运营需求。通过持续的优化和改进，系统能够适应不断发展的行业需求和技术进步。

21 KiB Raw Blame History Unescape Escape

绿能协议实现

目录

简介

项目结构

核心组件

协议引导器（LvnengV340ProtocolBootstrap）

消息处理器（LvnengProtocolMessageProcessor）

命令执行器基类

架构概览

详细组件分析

LvnengV340ProtocolBootstrap配置机制

消息帧结构设计

LvnengProtocolMessageProcessor消息处理

协议消息处理流程

上行消息处理流程

下行消息处理流程

命令路由机制

ProtocolCommandRouter实现

命令注册机制

数据包格式与处理

上行命令处理示例：实时数据上报

下行命令处理示例：设置定价模型

实际应用示例

协议命令转换机制

消息对象结构

性能考虑

异步处理机制

内存管理优化

缓存策略

故障排除指南

常见问题诊断

消息解析失败

命令路由失败

连接异常

日志分析

总结

主要特性

技术优势

21 KiB

Raw Blame History