CSoft.Protocol.HJ212 11.100.0

There is a newer version of this package available.
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
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="CSoft.Protocol.HJ212" Version="11.100.0" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="CSoft.Protocol.HJ212" Version="11.100.0" />
                    
Directory.Packages.props
<PackageReference Include="CSoft.Protocol.HJ212" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add CSoft.Protocol.HJ212 --version 11.100.0
                    
#r "nuget: CSoft.Protocol.HJ212, 11.100.0"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package CSoft.Protocol.HJ212@11.100.0
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=CSoft.Protocol.HJ212&version=11.100.0
                    
Install as a Cake Addin
#tool nuget:?package=CSoft.Protocol.HJ212&version=11.100.0
                    
Install as a Cake Tool

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 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. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

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
Loading failed

新增 .NET 11 目标,升级 CSoft 通信库至 11.0.3。优化 HJ212 2005、2017、2025 的命令查询、报文编解码及会话处理。