a

A Rust library that implements the protocol layer of China MEE HJ 212 (ASCII messages).

This crate focuses on reusable building blocks:

Receiving: extract frames from a TCP/serial byte stream (sticky packets) → parse a frame → get a structured Hj212Packet
Sending: build CP=&&...&& and payload via builders → wrap into an HJ212 frame (##{LEN}{PAYLOAD}{CRC})

Scope

Included:

Framing: ##{LEN}{PAYLOAD}{CRC16_HEX} (HJ 212—2025 ANSI CRC16)
Parse/build: parse_frame / build_frame
Streaming framer: Framer
Builders: CpBuilder / PayloadBuilder
Helpers: CRC functions, DataTime parsing
Standard-alignment helpers:
- build_frame_standard (uppercase CRC + trailing \r\n)
- parse_frame_strict (requires 4-digit length + CRC + \r\n)
Appendix C helpers: PNUM/PNO support and common ACK payload builders (build_qn_rtn, build_exe_rtn, build_data_ack, build_notify_ack)
Appendix A/H helpers (optional): encryption helpers under crypto (see below)

Intentionally NOT included:

Network I/O (Tokio/Actix/TCP server), serial port reading/writing
Database/storage, platform-specific mapping, UI
HTTPS upload logic (Appendix H multimedia upload)

Quick start

1) Parse a single complete frame

use a::{build_frame, parse_frame};

let payload = "QN=1;ST=22;CN=2011;PW=123456;MN=ABC;Flag=7;CP=&&DataTime=20250101010101;a21026-Rtd=12.3&&";
let frame = build_frame(payload);
assert!(frame.ends_with("\r\n"));

let pkt = parse_frame(&frame).unwrap();
assert_eq!(pkt.mn.as_deref(), Some("ABC"));
assert_eq!(pkt.cp.get("a21026-Rtd").map(String::as_str), Some("12.3"));

2) Extract frames from a byte stream

use a::{Framer, parse_frame};

let mut framer = Framer::new();
framer.push(b"##0025QN=1;ST=22;CN=2011;CP=&&&&");

while let Some(frame_bytes) = framer.next_frame() {
    let frame_str = String::from_utf8(frame_bytes).expect("HJ212 is ASCII");
    let _pkt = parse_frame(&frame_str)?;
}

# Ok::<(), a::Hj212Error>(())

3) Send-side: builders

use a::{CpBuilder, PayloadBuilder, parse_frame};

let mut cp = CpBuilder::new();
cp.data_time("20250101010101")
  .rtd_flag("a21026", "12.3", "N")
  .kv("a21026-Zs", "0.0");

let frame = PayloadBuilder::new(
    "20251225123000001", // QN
    "123456",            // PW
    "ABC",               // MN
    cp.build(),
)
.st("22")
.cn("2011")
.flag("7")
.frame();

let pkt = parse_frame(&frame).unwrap();
assert_eq!(pkt.mn.as_deref(), Some("ABC"));

Optional: SM4 auth encryption (Appendix H)

The standard’s multimedia upload appendix specifies:

Authorization plaintext is username:password
SM4-ECB + PKCS7Padding
then Base64

Enable feature sm4:

a = { version = "0.1", features = ["sm4"] }

And use a::crypto::sm4_auth.

Notes on standard vs compat frames

build_frame(...) emits standard frames: 4-digit LEN + uppercase CRC + trailing \r\n.
If you must interop with a legacy variant without CRLF, use build_frame_compat(...).

CRC16 and LEN (important)

LEN is the ASCII byte length of the payload (the bytes between {LEN} and {CRC}), i.e. payload.as_bytes().len(). It does not include the ## prefix, the LEN digits, the 4-byte CRC text, or the trailing \r\n.
CRC is computed over the payload bytes only using the HJ 212—2025 “ANSI CRC16” algorithm (poly 0xA001, init 0xFFFF, and the update step crc = (crc >> 8) ^ byte).
For historical interop, this crate also exposes the CRC16/Modbus variant via crc16_modbus_hex_upper/lower.

Standard example from the text (CRC = 2200):

##0087QN=20240601085857223;ST=32;CN=1011;PW=123456;MN=010000A8900016F000169DC0;Flag=9;CP=
&&&&2200\r\n

Notes on CP parsing

parse_frame* parses CP=&&...&& into pkt.cp by splitting only on ; into k=v pairs.
Some platform payloads group fields with commas (e.g. a34006-Avg=... ,a34006-Flag=N). Those commas are intentionally left for the business layer to interpret.

a 0.1.1

a