CSoft.Protocol.HJ212
11.100.0
See the version list below for details.
dotnet add package CSoft.Protocol.HJ212 --version 11.100.0
NuGet\Install-Package CSoft.Protocol.HJ212 -Version 11.100.0
<PackageReference Include="CSoft.Protocol.HJ212" Version="11.100.0" />
<PackageVersion Include="CSoft.Protocol.HJ212" Version="11.100.0" />
<PackageReference Include="CSoft.Protocol.HJ212" />
paket add CSoft.Protocol.HJ212 --version 11.100.0
#r "nuget: CSoft.Protocol.HJ212, 11.100.0"
#:package CSoft.Protocol.HJ212@11.100.0
#addin nuget:?package=CSoft.Protocol.HJ212&version=11.100.0
#tool nuget:?package=CSoft.Protocol.HJ212&version=11.100.0
HJ212 协议库(v2 重构版)
支持 HJ/T 212-2005、HJ 212-2017 和 HJ 212-2025 的 C# 协议库。现场机(设备端)和上位机(服务端)使用同一个 NuGet 包,共用编解码与命令注册表。
设计文档见 DESIGN.md。
特点
- 命令注册表按协议版本、CN 和方向索引。双向 CN 通过 CP 字段识别,2005 专有命令与 2017、2025 的同号命令按版本独立匹配。
- 一套核心,两侧共用:
Hj212Client(现场机)与Hj212Server(上位机,多客户端)共用帧编解码、CP 编解码、模型与注册表,取代旧版两个 NuGet 包的重复实现;服务端补上 2025 支持。 - 一条命令一份定义,取代旧版约 6 个工件(UploadReq / SendReq / GetCmd / Rsp / 事件 / 处理方法),旧
IGB的 85 个成员收敛为Hj212Client的十余个。 - 应答/重发/分包统一在会话层:9011 → 数据 → 9012 查询流程、9013/9014 等待、超时重发(OverTime/ReCount)、PNUM/PNO 分包(各自独立 QN)全部内建。
- CP 段一次编解码:标量 + 数据组(
a1001-Rtd=…,a1001-Flag=N)通用读写,数据组字段不再散落在各命令的字符串插值里。 - 传输与分帧使用 CSoft 的
PigeonPort、PigeonPort_Server和HeadLengthParser,由IPhysicalPort接入串口、TCP 或命名管道。现场机的应答配对和等待由 Pigeon 管理,帧校验使用Utils.CRC.GBcrc16。 - CRC 与帧格式对照标准附录 A(poly 0xA001、init 0xFFFF、高位在前),以标准示例帧
2200/1C80为基准向量测试。
快速上手
using Communication.Bus.PhysicalPort;
using HJ212.Client;
using HJ212.Codec;
using HJ212.Commands;
using HJ212.Messages;
using HJ212.Session;
using HJ212.Typed;
// 物理口来自 CSoft.Communication(串口/TCP/命名管道均可)
await using var session = new Hj212Client(
new TcpClient("127.0.0.1", 2756),
new Hj212Options { Mn = "88888888", Version = Hj212Version.V2025 });
await session.OpenAsync();
// 上传实时数据(等待 9014 数据应答,超时自动重发)
await session.UploadRealtimeAsync(DateTime.Now,
[
new RealtimeItem("a1001") { Rtd = "20.5", Flag = "N" },
]);
// 处理上位机命令:会话自动回 9011 → 处理器 → 9012
session.On(CommandCatalog.GetSystemTime, req =>
new CommandReply.Data([new CpSection().Set("SystemTime", DateTime.Now)]));
session.On(CommandCatalog.SetSystemTime, req =>
{
ApplySystemTime(req.GetDateTime("SystemTime")!.Value);
return new CommandReply.Success();
});
上位机(服务端)
using Communication.Bus;
using HJ212.Commands;
using HJ212.Messages;
using HJ212.Server;
using HJ212.Session;
await using var server = new Hj212Server(
new TcpServer("0.0.0.0", 2756),
new Hj212Options { Version = Hj212Version.V2025 });
server.OnClientConnect += async clientId => { /* … */ await Task.CompletedTask; };
// 接收上传:自动回 9014/9013 后分发
server.On(CommandCatalog.UploadRealtimeData, (clientId, req) =>
{
var dataTime = req.GetDateTime("DataTime");
return Task.CompletedTask;
});
await server.StartAsync();
// 下发控制命令:自动组装 9011 → 9012 事务
await server.SetSystemTimeAsync(clientId, "w01018", DateTime.Now);
// 下发查询命令:自动组装 9011 → 数据包*N(逐包回 9014)→ 9012
var packets = await server.GetStatisticsDataAsync(clientId,
CommandCatalog.GetMinuteData, beginTime, endTime);
自定义命令(未写糖的)直接走通用 API:
var cp = new CpSection()
.Set("DataTime", dataTime)
.Add(new DataGroup("w01018").Add("SampleRd", "12.5").Add("StandardValue", "12").Add("ResultType", "1"));
await session.SendAsync(CommandCatalog.UploadAutoStandardCheckData, cp);
离线组帧(调试/回放):
string frame = session.BuildFrame(CommandCatalog.UploadMinuteData, cp);
从旧版迁移
现场机(旧 CSoft.Protocol.HJ212 / IGB):
| 旧 API(IGB / GB) | 新 API |
|---|---|
new GB(name, port, mn, version: HJT212_2025) |
new Hj212Client(port, new(){ Mn = mn, Version = V2025 }) |
gb.UploadRealTimeData(dt, data) |
session.UploadRealtimeAsync(dt, items) |
gb.SendRealTimeData(dt, data) |
session.SendAsync(CommandCatalog.UploadRealtimeData, cp, new(){ WaitAck = false }) |
gb.GetSendMinuteDataCmd(...) |
session.BuildFrame(CommandCatalog.UploadMinuteData, cp) |
gb.OnGetSystemTime += h |
session.On(CommandCatalog.GetSystemTime, req => …) |
gb.OnSetOverTimeAndReCount += h |
session.On(CommandCatalog.SetOverTimeAndReCount, req => …) |
List<StatisticsData> |
List<StatisticsItem>(字段同名:Cou/Min/Avg/Max/Zs*/Flag) |
上位机(旧 CSoft.Protocol.HJ212_Server / IGB_Server,现并入本库并支持 2025):
| 旧 API(IGB_Server / GB_Server) | 新 API |
|---|---|
new GB_Server(new TcpServer(...)) |
new Hj212Server(new TcpServer(...), new(){ Version = V2025 }) |
gb.SetSystemTimeAsync(clientId, mn, pw, st, …) |
server.SetSystemTimeAsync(clientId, polId, time)(MN/PW/ST 取自 Hj212Options) |
gb.GetMinuteDataAsync(clientId, …) |
server.GetStatisticsDataAsync(clientId, CommandCatalog.GetMinuteData, begin, end) |
gb.OnUploadRealTimeData += h |
server.On(CommandCatalog.UploadRealtimeData, (clientId, req) => …) |
gb.OnAskSetSystemTime += h |
server.On(CommandCatalog.AskSetSystemTime, (clientId, req) => …) |
| 逐命令方法(40 成员) | 通用 QueryAsync / ControlAsync + ServerExtensions 薄糖 |
行为差异(修复旧版问题):
- 分包消息各自独立 QN(标准要求,旧版全包同 QN)。
- 2025 新增
RF补传标志:SendOptions.Retransmit = true。 - 留样信息按标准走 CN 3015(2025 C63);旧版误用 2031。
- 按标准,2017 的 3014/3016/3017 在 2025 版本下不可用(注册表
Cn2025 = null),旧版不区分。
目录结构
src/HJ212/
Framing/ Crc16(Utils.CRC 包装), Hj212Frame(##dddd…CRC…CRLF)
Messages/ Hj212Message(QN/ST/CN/PW/MN/Flag/PNUM/PNO/RF/CP), MessageCodec
Codec/ CpSection, DataGroup, CpCodec
Commands/ CommandSpec, CommandCatalog(全量命令注册表)
Client/ Hj212Client(现场机), ClientExtensions
Server/ Hj212Server(上位机,多客户端), ServerExtensions
Session/ 共用线协议、会话选项与 Pigeon Req/Rsp 适配器
Typed/ 数据组模型(RealtimeItem/StatisticsItem), 便捷扩展
tests/HJ212.Tests/ 三版协议样例、编解码和现场机/上位机会话回归
构建与测试
构建使用 .NET 11 SDK。协议库提供 net8.0、net9.0、net10.0、net11.0 四个目标,测试默认在 net11.0 上运行。CSoft.Protocol 和 CSoft.TopPortLib 使用 11.0.3,Builder、CommTask、Communication 和 Parser 通过传递依赖还原到同一版本。CRC 使用 CSoft.Utils 11.0.1。
dotnet test HJ212.slnx -c Release
附录报文回归覆盖 2005 附录 C 的 25 个流程、2017 表 C.1–C.50 和 2025 表 C.1–C.63,共 436 条报文。测试逐条检查组帧、CRC、命令和 CP 字段,并通过 Pigeon 回放附录交互。报文中的省略号只取已给出的字段,2017 的报头排印差异保留原文并标注测试所用的修正。2025 附录 A 的两条 SM4 密文用于验证明文解析器会拒绝密文。
标准差异要点(详见 DESIGN.md)
- 三版共用帧结构与 CRC。2005 使用 ASCII,2017 和 2025 的中文日志使用 UTF-8。2025 新增 RF 补传标志和心跳 9015,SM4 加密尚未实现。
- Flag 的 bit 0 表示应答,bit 1 表示分包,版本位 2005 为 0、2017 为 4、2025 为 8。
- 2005 的应答可在 CP 内携带 QN。历史查询的 9014 回执按该版本携带 QN、CN 和适用的分包编号。
- 2005 持续上传命令(CN=2011/2021)收到 9011 即完成启动,随后通过同一连接调用
ControlAsync停止时沿用启动 QN。 - ST 51/52 两版同值异义(工况 → 温室气体/碳足迹),跨版本解析先按 Flag 判版。
- 需要分包时,由调用方将数据划分为多个
CpSection,再交给SendPacketsAsync编号和发送。2025 原始监测数据(CN=2013)也支持此流程。 - 2025 附录 C.39/C.40 的用电历史数据使用
CommandCatalog.GetRealtimeHistory。以BeginTime、EndTime构造 CP,并用 ST=44 调用QueryAsync。 - 查询收到现场机的结束应答时,会检查已声明分包总数的报文是否覆盖对应包号。缺少包号会抛出
InvalidOperationException。
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | net8.0 is compatible. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. net9.0 is compatible. net9.0-android was computed. net9.0-browser was computed. net9.0-ios was computed. net9.0-maccatalyst was computed. net9.0-macos was computed. net9.0-tvos was computed. net9.0-windows was computed. net10.0 is compatible. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed. net11.0 is compatible. |
-
net10.0
- CSoft.Protocol (>= 11.0.3)
- CSoft.TopPortLib (>= 11.0.3)
- CSoft.Utils (>= 11.0.1)
-
net11.0
- CSoft.Protocol (>= 11.0.3)
- CSoft.TopPortLib (>= 11.0.3)
- CSoft.Utils (>= 11.0.1)
-
net8.0
- CSoft.Protocol (>= 11.0.3)
- CSoft.TopPortLib (>= 11.0.3)
- CSoft.Utils (>= 11.0.1)
-
net9.0
- CSoft.Protocol (>= 11.0.3)
- CSoft.TopPortLib (>= 11.0.3)
- CSoft.Utils (>= 11.0.1)
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories
This package is not used by any popular GitHub repositories.
| Version | Downloads | Last Updated |
|---|---|---|
| 11.100.1 | 149 | 11/13/2026 |
| 11.100.0 | 103 | 11/13/2026 |
| 10.100.3 | 99 | 10/28/2026 |
| 10.100.2 | 102 | 10/28/2026 |
| 10.100.1 | 99 | 10/28/2026 |
| 10.100.0 | 103 | 10/28/2026 |
| 10.1.0 | 179 | 5/21/2026 |
| 10.0.8 | 163 | 1/28/2026 |
| 10.0.7 | 149 | 1/27/2026 |
| 10.0.6 | 146 | 1/14/2026 |
| 10.0.5 | 152 | 1/14/2026 |
| 10.0.4 | 159 | 1/13/2026 |
| 10.0.3 | 156 | 1/13/2026 |
| 10.0.2 | 156 | 1/13/2026 |
| 10.0.1 | 150 | 1/12/2026 |
| 10.0.0 | 358 | 11/12/2025 |
| 9.4.7 | 270 | 9/24/2025 |
| 9.4.6 | 267 | 8/15/2025 |
| 9.4.4 | 274 | 8/14/2025 |
| 9.4.3 | 329 | 8/5/2025 |
新增 .NET 11 目标,升级 CSoft 通信库至 11.0.3。优化 HJ212 2005、2017、2025 的命令查询、报文编解码及会话处理。