kkprotocol 0.1.0__py3-none-any.whl

kkprotocol/compiler.py

@@ -0,0 +1,182 @@
+# -*- coding: utf-8 -*-
+"""规则编译：把 ``Field``/字典规则校验并编译成解析期使用的结构。
+
+所有配置错误都在**编译期**暴露（可在启动时调用 ``codec.compile()``），
+而不是等到运行期解析到某帧才炸。
+"""
+
+from __future__ import annotations
+
+import struct
+from collections.abc import Mapping as MappingABC
+from dataclasses import dataclass
+from typing import Any, Callable, Dict, List, Optional, Sequence, Tuple, Union
+
+from .errors import FrameRuleError
+from .fields import Field
+from .length import _GROUP_REF_RE, _LEN_ATTRS, LengthExpr
+
+__all__ = ["CompiledField", "compile_rules", "normalize_rule"]
+
+_LENGTH_KINDS = (int, LengthExpr)
+
+
+def normalize_rule(item: Any) -> Field:
+    """把 dict 规则或 Field 统一成 Field。"""
+    if isinstance(item, Field):
+        return item
+    if isinstance(item, MappingABC):
+        return Field.from_dict(dict(item))
+    raise FrameRuleError(
+        "规则项必须是 Field 或 dict，实际 {}".format(type(item).__name__)
+    )
+
+
+@dataclass
+class CompiledField:
+    """编译后的字段描述，解析热路径只读它。"""
+
+    key: str
+    length: Optional[Union[int, LengthExpr, Callable[[Dict[str, Any]], int]]]
+    fmt: str
+    fixed: Any
+    group_refs: Optional[Tuple[str, ...]]
+    is_crc: bool
+    is_device: bool
+    desc: str = ""
+    struct: Optional[struct.Struct] = None
+    fmt_size: Optional[int] = None
+    byteorder: str = "big"
+
+
+def _compile_length(key: str, spec: Any) -> Optional[Union[int, LengthExpr, Callable]]:
+    if spec is None:  # 取到帧尾为止，只有分隔符定界能确定边界
+        return None
+    if callable(spec):
+        return spec
+    if isinstance(spec, bool):
+        raise FrameRuleError("字段 {!r} 的长度不能是 bool".format(key))
+    if isinstance(spec, int):
+        return spec
+    if isinstance(spec, str):
+        text = spec.strip()
+        if not text:
+            raise FrameRuleError("字段 {!r} 的长度为空字符串".format(key))
+        try:
+            return int(text)
+        except ValueError:
+            return LengthExpr(text)
+    raise FrameRuleError(
+        "字段 {!r} 的长度必须是 int / str / callable，实际 {}".format(key, type(spec).__name__)
+    )
+
+
+def compile_rules(
+    raw_rules: Sequence[Union[Field, Dict[str, Any]]],
+    device_field: Optional[str] = None,
+) -> List[CompiledField]:
+    """校验并编译规则列表；任何不一致都抛 :class:`FrameRuleError`。"""
+    if not raw_rules:
+        raise FrameRuleError("rules() 返回空规则，至少需要一个字段")
+
+    compiled: List[CompiledField] = []
+    seen: List[str] = []
+
+    for item in raw_rules:
+        field = normalize_rule(item)
+        key = field.key
+        if not isinstance(key, str) or not key:
+            raise FrameRuleError("规则缺少合法的 key: {!r}".format(key))
+        if key in seen:
+            raise FrameRuleError("字段 key 重复: {!r}".format(key))
+        fmt = field.fmt
+        if not isinstance(fmt, str):
+            raise FrameRuleError("字段 {!r} 的 fmt 必须是字符串".format(key))
+
+        st: Optional[struct.Struct] = None
+        fmt_size: Optional[int] = None
+        if fmt:
+            try:
+                st = struct.Struct(fmt)
+            except struct.error as exc:
+                raise FrameRuleError("字段 {!r} 的 fmt {!r} 非法: {}".format(key, fmt, exc)) from exc
+            if st.size <= 0:
+                raise FrameRuleError("字段 {!r} 的 fmt {!r} 长度为 0".format(key, fmt))
+            if len(st.unpack(b"\x00" * st.size)) != 1:
+                raise FrameRuleError("字段 {!r} 的 fmt {!r} 必须只解析出一个值".format(key, fmt))
+            fmt_size = st.size
+
+        length = _compile_length(key, field.length)
+        if isinstance(length, int):
+            if length < 0:
+                raise FrameRuleError("字段 {!r} 长度为负数".format(key))
+            if length == 0 and st is not None:
+                raise FrameRuleError("字段 {!r} 为零长度，不能声明 fmt".format(key))
+            if fmt_size is not None and fmt_size != length:
+                raise FrameRuleError(
+                    "字段 {!r} 声明长度 {} 与 fmt {!r} 的字节数 {} 不一致".format(
+                        key, length, fmt, fmt_size
+                    )
+                )
+        elif isinstance(length, LengthExpr):
+            for ref_key, attr in length.refs:
+                if ref_key not in seen:
+                    raise FrameRuleError(
+                        "字段 {!r} 的长度表达式引用了不存在或尚未解析的字段 {!r}"
+                        "（只能引用前面的字段）".format(key, ref_key)
+                    )
+                if attr != "val" and attr not in _LEN_ATTRS:
+                    raise FrameRuleError(
+                        "字段 {!r} 的长度表达式引用了不支持的属性 {!r}".format(key, attr)
+                    )
+
+        group_refs: Optional[Tuple[str, ...]] = None
+        is_crc = bool(field.crc)
+        if field.group is not None:
+            group = field.group
+            if not isinstance(group, str) or not group:
+                raise FrameRuleError("字段 {!r} 的 group 必须是非空字符串".format(key))
+            refs = tuple(m.group(1) for m in _GROUP_REF_RE.finditer(group))
+            if not refs:
+                raise FrameRuleError("字段 {!r} 的 group 未包含任何 {{字段}} 引用".format(key))
+            for ref_key in refs:
+                if ref_key not in seen:
+                    raise FrameRuleError(
+                        "字段 {!r} 的 group 引用了不存在或尚未解析的字段 {!r}".format(key, ref_key)
+                    )
+            group_refs = refs
+            is_crc = True
+        elif is_crc:
+            if not seen:
+                raise FrameRuleError("校验字段 {!r} 之前没有可参与校验的内容".format(key))
+            group_refs = tuple(seen)
+
+        compiled.append(
+            CompiledField(
+                key=key,
+                length=length,
+                fmt=fmt,
+                fixed=field.fixed,
+                group_refs=group_refs,
+                is_crc=is_crc,
+                is_device=(device_field is not None and key == device_field),
+                desc=field.desc,
+                struct=st,
+                fmt_size=fmt_size,
+                byteorder="little" if fmt.startswith("<") else "big",
+            )
+        )
+        seen.append(key)
+
+    if device_field is not None and device_field not in seen:
+        raise FrameRuleError(
+            "device_field={!r} 不在规则里，可用字段: {}".format(device_field, seen)
+        )
+    for cf in compiled:
+        if cf.is_device and cf.fixed is not None:
+            raise FrameRuleError(
+                "设备号字段 {!r} 不能同时声明 fixed（设备号由 device_id/自动学习决定）".format(
+                    cf.key
+                )
+            )
+    return compiled

kkprotocol/contrib/__init__.py

@@ -0,0 +1,8 @@
+# -*- coding: utf-8 -*-
+"""贡献协议集（contrib）：从网上收集的真实通讯协议，用来压测 kkprotocol 的设计健壮性。
+
+这些模块**不会**出现在 ``kkprotocol.__init__`` 顶层导出里，只是包内模块，
+按需 ``from kkprotocol.contrib import dlt645`` 即可得到。每个模块都尽量用当前
+的声明式 ``FrameSpec`` / ``Protocol`` / ``FrameBuilder`` 落地，并显式标注哪些地方
+暴露了设计上的纰漏（见各模块 docstring 与 tests/test_contrib_protocols.py）。
+"""

kkprotocol/contrib/artnet.py

@@ -0,0 +1,55 @@
+# -*- coding: utf-8 -*-
+"""Art-Net（舞台灯光 UDP 协议，这里取它的以太网头部做压测）。
+
+Art-Net 报文以 **8 字节字符串 magic** ``"Art-Net\\0"`` 开头，然后是操作码、版本号等：:
+
+    "Art-Net\0"  OpCode(2, 小端)  ProtVer(2, 大端)  TalkToMe(1)  Priority(1) ...
+
+要点（压测点）：
+
+* 同步标记是**多字节字符串** ``b"Art-Net\\0"``，而不是单字节标志。
+  库的长度定界支持把 ``sync`` 配成多字节（``AbstractFrameCodec.sync = b"Art-Net\\x00"``），
+  这点设计是够用的——这正好补上“DelimiterFraming.start 只支持单字节”的反例：
+  **多字节 magic 走长度定界的 sync 就行，只有分隔符定界才卡在单字节**。
+* 这里是 UDP，长度由 IP 层给出，所以帧内没有长度定界字段，仅靠固定头部长度 + magic。
+
+说明：只解析前 14 字节的 ArtPoll 头部（magic + opcode + version + talktome + priority），
+足以验证多字节同步；完整 ArtDmx 的 512 字节数据段不在此建模。
+"""
+from __future__ import annotations
+
+from ..codec import AbstractFrameCodec, LENGTH_FRAMING
+from ..spec import Field
+
+
+class ArtNetCodec(AbstractFrameCodec):
+    # 多字节同步标记：这是“长度定界”支持、但“分隔符定界”的 start/end 不支持的能力
+    sync = b"Art-Net\x00"
+    framing = LENGTH_FRAMING
+    max_frame_size = 1024
+
+    def rules(self):
+        return [
+            Field.raw("magic", 8, fixed=b"Art-Net\x00"),
+            Field.u16("opcode", little_endian=True),
+            Field.u16("version", little_endian=False),
+            Field.u8("talktome"),
+            Field.u8("priority"),
+        ]
+
+    def crc_imp(self, data):
+        return 0
+
+
+def build_artpoll(version: int = 14, talktome: int = 0, priority: int = 0) -> bytes:
+    """组一条最小的 ArtPoll 头部（操作码 0x2000）。"""
+    return (
+        b"Art-Net\x00"
+        + (0x2000).to_bytes(2, "little")
+        + version.to_bytes(2, "big")
+        + bytes([talktome, priority])
+    )
+
+
+def codec() -> AbstractFrameCodec:
+    return ArtNetCodec()

kkprotocol/contrib/bacnet_mstp.py

@@ -0,0 +1,110 @@
+# -*- coding: utf-8 -*-
+"""BACnet MS/TP（楼宇自控，RS-485 令牌环）。
+
+帧结构（长度定界，固定 2 字节前导 55 FF）：::
+
+    55 FF 类型(1) 目的(1) 源(1) 长度(2, 大端)
+        [令牌帧到此为止]
+        头CRC(1, 覆盖 类型/目的/源/长度)
+        [数据帧另有] DATA(长度)  数据CRC(2, 覆盖 DATA)
+
+要点（压测点 —— 这是本次最关键的“设计缺口”样本）：
+
+* 一帧里**有两个校验和**（头 CRC8 + 体 CRC16），且头 CRC 在帧中部、体 CRC 在帧尾；
+* 解析侧：库会对**所有**标 ``crc=True`` 的字段逐个校验，所以两个 CRC **都能验**
+  （本模块用 ``to_codec`` 解析验证）；
+* **组帧侧**：``FrameBuilder`` 的 ``FrameSpec.checksum`` 只能声明**一个**校验和，
+  数据帧（头 + 体两个 CRC）目前**无法用 builder 一次组出来**——这是真实缺口
+  （见 ``build_data`` 只能手工构造）。建议未来支持“一帧多校验和 / 按字段独立计算”。
+* 令牌帧（长度=0）没有数据也没有体 CRC，和结构不同的数据帧属于“同一字节流里的多形态”
+  —— 这里用两份 spec（TOKEN / DATA）分别解析，和 example_modbus_rtu_multi 的多响应分派是同一类问题。
+
+校验多项式说明：BACnet 头 CRC8 用 0x07、体 CRC16 用 0x1021（初值 0xFFFF）属非反射族；
+离线无法用公开文档的 0x55 / 0xF0B8 残差反推到标准算法（文档示例自洽性存疑），但库只
+比对“校验值是否一致”，因此这里用自洽的 CRC 建模双校验结构，重点测库的解析能力。
+"""
+from __future__ import annotations
+
+from ..crc import crc16_ccitt, crc8
+from ..spec import ChecksumRule, Field, FrameSpec
+
+PRE1 = 0x55
+PRE2 = 0xFF
+
+
+def _header_crc(ftype: int, dst: int, src: int, length: int) -> int:
+    head = bytes([ftype, dst, src]) + length.to_bytes(2, "big")
+    return crc8(head, poly=0x07, init=0xFF)
+
+
+def _data_crc(data: bytes) -> int:
+    return crc16_ccitt(data, init=0xFFFF)
+
+
+SPEC_TOKEN = FrameSpec(
+    fields=[
+        Field.u8("pre1", fixed=PRE1),
+        Field.u8("pre2", fixed=PRE2),
+        Field.u8("ftype"),
+        Field.u8("dst", desc="目的 MAC 地址（设备号）"),
+        Field.u8("src"),
+        Field.u16("length", little_endian=False),
+        Field.checksum("hcrc", 1, group="{ftype}{dst}{src}{length}"),
+    ],
+    device="dst",
+    checksum=ChecksumRule("hcrc", lambda g: crc8(g, poly=0x07, init=0xFF)),
+    max_frame_size=8,
+    desc="BACnet MS/TP 令牌帧",
+)
+
+SPEC_DATA = FrameSpec(
+    fields=[
+        Field.u8("pre1", fixed=PRE1),
+        Field.u8("pre2", fixed=PRE2),
+        Field.u8("ftype"),
+        Field.u8("dst", desc="目的 MAC 地址（设备号）"),
+        Field.u8("src"),
+        Field.u16("length", little_endian=False),
+        Field.checksum("hcrc", 1, group="{ftype}{dst}{src}{length}"),
+        Field.raw("data", "{length.val}"),
+        Field.checksum("dcrc", 2, fmt="!H", group="{data}"),
+    ],
+    device="dst",
+    # 一帧双校验和：头 CRC8（覆盖类型/目的/源/长度）+ 体 CRC16（仅覆盖 DATA）。
+    # 解析侧已支持一帧多校验和（每个字段按各自 impl 独立校验）；组帧侧仍只回填第一个，
+    # 所以数据帧组帧走手工 build_data（见下方）。
+    checksum=[
+        ChecksumRule("hcrc", lambda g: crc8(g, poly=0x07, init=0xFF)),
+        ChecksumRule("dcrc", lambda g: crc16_ccitt(g, init=0xFFFF)),
+    ],
+    max_frame_size=512,
+    desc="BACnet MS/TP 数据帧",
+)
+
+
+def protocol_token(device_id=None, enforce=False):
+    from ..builder import Protocol
+    return Protocol(SPEC_TOKEN, device_id=device_id, enforce_device_id=enforce)
+
+
+def protocol_data(device_id=None, enforce=False):
+    from ..builder import Protocol
+    return Protocol(SPEC_DATA, device_id=device_id, enforce_device_id=enforce)
+
+
+def build_token(ftype: int, dst: int, src: int) -> bytes:
+    """组一条令牌帧（长度=0，无数据、无体 CRC）。"""
+    length = 0
+    head = bytes([PRE1, PRE2, ftype, dst, src]) + length.to_bytes(2, "big")
+    return head + bytes([_header_crc(ftype, dst, src, length)])
+
+
+def build_data(ftype: int, dst: int, src: int, data: bytes) -> bytes:
+    """手工组一条数据帧（同时算头 CRC8 与体 CRC16）。
+
+    注意：这条只能手工组，因为 FrameBuilder 只支持单校验和，组不出“头+体双 CRC”。
+    """
+    length = len(data)
+    head = bytes([PRE1, PRE2, ftype, dst, src]) + length.to_bytes(2, "big")
+    body = head + bytes([_header_crc(ftype, dst, src, length)]) + data
+    return body + _data_crc(data).to_bytes(2, "big")

kkprotocol/contrib/cctalk.py

@@ -0,0 +1,53 @@
+# -*- coding: utf-8 -*-
+"""ccTalk 货币交易外设串行协议（硬币/纸币识别器、找零器，TTL 多-drop 总线）。
+
+帧结构（长度定界，**没有帧头/帧尾定界符**）：::
+
+    [目的地址] [数据长度] [源地址] [命令头] [DATA...] [校验和]
+
+校验和：所有字节（含校验和）累加后 mod 256 == 0，因此校验和字节 = ``(256 - 前 N 字节和) % 256``。
+
+要点（压测点）：
+
+* **完全没有帧头/帧尾定界符**，也没有同步字节——帧边界只能靠“数据长度字段”推算；
+* 一旦流错位（丢/多一个字节），后续所有帧都会整体偏移，**无法靠同步锚点恢复**
+  （这与 DLT645/CJ/T188 有固定 0x68 能重同步形成对比）。
+* 校验和是“凑零和”式，不是 CRC。
+
+暴露的设计缺口：库的长度定界依赖一个同步锚点来寻找帧起点；ccTalk 这种“无锚点”
+协议在错位后恢复能力弱，属于协议本身的天花板，但库也应提供“无同步、纯长度推算”
+的明确模式（目前靠 ``sync=None`` 退化为“从缓冲区起点直接读”，错位即全盘皆错）。
+"""
+from __future__ import annotations
+
+from ..builder import FrameBuilder, Protocol
+from ..spec import ChecksumRule, Field, FrameSpec, LengthRule
+
+SPEC = FrameSpec(
+    fields=[
+        Field.u8("dest", desc="目的地址（设备号）"),
+        Field.u8("dlen"),
+        Field.u8("source"),
+        Field.u8("header"),
+        Field.raw("data", "{dlen.val}"),
+        Field.checksum("cs", 1, group="{dest}{dlen}{source}{header}{data}"),
+    ],
+    payload="data",
+    # ccTalk 长度字节 = 数据字节数（不含源/头/校验），圈住数据字段自身
+    length=LengthRule("dlen", span=("data", "data")),
+    checksum=ChecksumRule("cs", lambda group: (-sum(group)) & 0xFF),
+    device="dest",
+    max_frame_size=260,
+    desc="ccTalk",
+)
+
+_builder = FrameBuilder(SPEC)
+
+
+def protocol(device_id: int = None, enforce_device_id: bool = False) -> Protocol:
+    return Protocol(SPEC, device_id=device_id, enforce_device_id=enforce_device_id)
+
+
+def build(dest: int, source: int, header: int, data: bytes = b"") -> bytes:
+    """组一条 ccTalk 报文（长度与校验和自动填）。"""
+    return _builder.build_raw(None, data, dest=dest, source=source, header=header)

kkprotocol/contrib/cjt188.py

@@ -0,0 +1,57 @@
+# -*- coding: utf-8 -*-
+"""CJ/T188-2004 户用计量仪表数据传输技术条件（水/气/热表，RS-485）。
+
+帧结构（长度定界，同步字节 0x68）：::
+
+    68  T(1)  A0..A6(7)  C  L  DATA(L)  CS(1, 累加和)  16
+
+与 DLT645 相比：
+
+* 只有一个 ``0x68``（地址 7 字节后没有第二个 0x68），结构更干净；
+* 数据域**不做** +0x33 变换；
+* CS 同样是 0x68 到 DATA 末尾的累加和。
+
+用来验证：单固定字节同步 + 长度字段（span 圈数据）+ 和校验，是最“标准”的长度定界样本。
+"""
+from __future__ import annotations
+
+from ..builder import FrameBuilder, Protocol
+from ..crc import sum8
+from ..spec import ChecksumRule, Field, FrameSpec, LengthRule
+
+START = 0x68
+END = 0x16
+
+
+SPEC = FrameSpec(
+    fields=[
+        Field.u8("start", fixed=START),
+        Field.u8("type"),
+        Field.raw("addr", 7, desc="表号（低字节在前，BCD）"),
+        Field.u8("ctrl"),
+        Field.u8("len"),
+        Field.raw("data", "{len.val}"),
+        Field.checksum("cs", 1, group="{start}{type}{addr}{ctrl}{len}{data}"),
+        Field.u8("end", fixed=END),
+    ],
+    payload="data",
+    length=LengthRule("len", span=("data", "data")),
+    checksum=ChecksumRule("cs", sum8),
+    device="addr",
+    max_frame_size=128,
+    desc="CJ/T188-2004",
+)
+
+_builder = FrameBuilder(SPEC)
+
+
+def protocol(device_id: bytes = None, enforce_device_id: bool = False) -> Protocol:
+    return Protocol(SPEC, device_id=device_id, enforce_device_id=enforce_device_id)
+
+
+def build_request(addr: bytes, ctrl: int = 0x01, meter_type: int = 0x10,
+                  data: bytes = b"") -> bytes:
+    """组一条读表请求（默认读数据 CTR_0=0x01，冷水表 T=0x10）。"""
+    if len(addr) != 7:
+        raise ValueError("CJ/T188 地址必须 7 字节")
+    return _builder.build_raw(None, data, addr=addr, ctrl=ctrl, type=meter_type)

kkprotocol/contrib/dlt645.py

@@ -0,0 +1,81 @@
+# -*- coding: utf-8 -*-
+"""DL/T645-2007 多功能电能表通信协议（RS-485，国内电表常见）。
+
+帧结构（长度定界，同步字节 0x68）：:
+
+    68  A0..A5(6)  68  C  L  DATA(L, 每字节 +0x33)  CS(1, 累加和)  16
+
+要点（也是用来压测的点）：
+
+* 帧首/帧尾是固定字节 ``0x68`` / ``0x16``，地址之后还有一个 ``0x68`` —— 结构化帧头里
+  重复出现同步字节；若流错位落在中间的 0x68 上，只能靠长度 + 校验否证后重同步
+  （库当前只支持**单字节**同步锚点，无法表达“68 + 地址 + 68”这种结构化帧头）。
+* 数据域发送端逐字节 ``+0x33``、接收端 ``-0x33``（传输层字节变换，不是加密）；
+  这意味着数据里会出现 0x68 / 0x16 / 0x33，库没有“逐字节变换”原语，只能在
+  组帧/解析后手动 add33 / sub33。
+* CS 是从第一个 0x68 到 DATA 末尾所有字节的累加和（取低 8 位）。
+* 长度字段 ``L`` 只等于 DATA 字节数（不是“到帧尾”），靠 ``LengthRule(span=...)`` 圈定。
+
+结论：库能完整组帧 + 解析（长度字段被 ``span`` 正确回填），暴露的设计缺口见上面三点。
+"""
+from __future__ import annotations
+
+from ..builder import FrameBuilder, Protocol
+from ..crc import sum8
+from ..framing import LENGTH_FRAMING
+from ..spec import ChecksumRule, Field, FrameSpec, LengthRule
+
+START = 0x68
+END = 0x16
+
+
+def add33(data: bytes) -> bytes:
+    """数据域发送端编码：逐字节 +0x33。"""
+    return bytes((b + 0x33) & 0xFF for b in data)
+
+
+def sub33(data: bytes) -> bytes:
+    """数据域接收端解码：逐字节 -0x33。"""
+    return bytes((b - 0x33) & 0xFF for b in data)
+
+
+SPEC = FrameSpec(
+    fields=[
+        Field.u8("start", fixed=START),
+        Field.raw("addr", 6, desc="表号（低字节在前）"),
+        Field.u8("mid", fixed=START),
+        Field.u8("ctrl"),
+        Field.u8("len"),
+        Field.raw("data", "{len.val}"),
+        Field.checksum("cs", 1, group="{start}{addr}{mid}{ctrl}{len}{data}"),
+        Field.u8("end", fixed=END),
+    ],
+    payload="data",
+    # 长度字段 L 只等于 DATA 字节数：用 span=("data","data") 圈住数据字段自身
+    # （span 左闭右闭、起点计入，所以 “data..data” = 仅数据段长度）
+    length=LengthRule("len", span=("data", "data")),
+    checksum=ChecksumRule("cs", sum8),
+    device="addr",
+    max_frame_size=64,
+    desc="DL/T645-2007",
+)
+
+_builder = FrameBuilder(SPEC)
+
+
+def protocol(device_id: bytes = None, enforce_device_id: bool = False) -> Protocol:
+    """拿一个既能组指令又能解析的 Protocol。"""
+    return Protocol(SPEC, device_id=device_id, enforce_device_id=enforce_device_id)
+
+
+def build_request(addr: bytes, ctrl: int = 0x11, data: bytes = b"") -> bytes:
+    """组一条请求帧。``data`` 传应用层原始字节（不含 +0x33），长度即 L。"""
+    if len(addr) != 6:
+        raise ValueError("DLT645 地址必须 6 字节")
+    encoded = add33(data)
+    return _builder.build_raw(None, encoded, addr=addr, ctrl=ctrl)
+
+
+def decode_data(raw_data: bytes) -> bytes:
+    """把解析出来的 data 原始字节还原成应用层数据（-0x33）。"""
+    return sub33(raw_data)

kkprotocol/contrib/hdlc.py

@@ -0,0 +1,47 @@
+# -*- coding: utf-8 -*-
+"""HDLC / PPP 风格帧（标志 0x7E，0x7D 转义异或 0x20，FCS 为 CRC-16）。
+
+帧结构（分隔符定界，首尾共用 0x7E）：::
+
+    FLAG(0x7E)  ADDRESS(1)  CONTROL(1)  INFO(变长)  FCS(2, CRC-16)  FLAG(0x7E)
+
+这里用来验证：
+
+* 分隔符定界 + 转义（PPP/HDLC 标准做法）在通用引擎下能正确组帧/解析；
+* 净荷里出现 0x7E / 0x7D 时被转义，不会误判帧边界；
+* FCS 是一段末尾固定 2 字节的 CRC（这里用 ``crc16_x25`` 与现有 PPP 示例一致）。
+
+说明：真实 HDLC 的 FCS 字节序与补码约定各异，这里只验证“库的转义 + 末尾 CRC”链路，
+FCS 用库内一致的 ``crc16_x25`` 大端打包，不追求与某款硬件逐字节一致。
+"""
+from __future__ import annotations
+
+from ..crc import crc16_x25
+from ..framing import DelimiterFraming, wrap_frame
+from ..spec import ChecksumRule, Field, FrameSpec
+
+HDLC = DelimiterFraming(end=0x7E, start=0x7E, escape=0x7D, escape_xor=0x20)
+
+SPEC = FrameSpec(
+    fields=[
+        Field.u8("address"),
+        Field.u8("control"),
+        Field.rest("info", desc="信息字段，取到帧尾 0x7E 前"),
+        Field.checksum("fcs", 2, fmt="!H", group="{address}{control}{info}"),
+    ],
+    framing=HDLC,
+    # 必须声明 ChecksumRule，否则 to_codec() 的 crc_imp 默认返回 0，FCS 会校验失败
+    checksum=ChecksumRule("fcs", crc16_x25),
+    desc="HDLC/PPP style",
+)
+
+
+def codec():
+    return SPEC.to_codec()
+
+
+def build(address: int, control: int, info: bytes) -> bytes:
+    """组一条 HDLC 帧：先算 FCS，再整体加 0x7E 标志并转义。"""
+    inner = bytes([address, control]) + info
+    fcs = crc16_x25(inner).to_bytes(2, "big")
+    return wrap_frame(inner + fcs, HDLC)

kkprotocol/contrib/mbus.py

@@ -0,0 +1,61 @@
+# -*- coding: utf-8 -*-
+"""M-Bus（Meter-Bus，EN 13757-2/3 有线抄表总线）。
+
+长帧结构（长度定界，同步字节 0x68）：::
+
+    68  L  L  68  C  A  CI  DATA(L-3)  CS(1)  16
+
+要点（压测点）：
+
+* 长度字段 ``L`` **重复出现两次**（68 L L 68），且 L = 控制/地址/CI + 数据 的字节数；
+* CS 是第一个 0x68 到 DATA 末尾的累加和。
+
+暴露的设计缺口：库当前**只支持一个长度字段**自动回填，M-Bus 这种“长度字节冗余
+两次”的结构，组帧时第二份 L 无法被 builder 自动填成和第一份一样——所以这里组帧
+走手工构造（见 ``build_mbus``），解析走通用引擎（能正确切帧 + 校验）。这本身不是致命
+缺陷，但说明 builder 对“冗余长度/字段复制”没有原生支持。
+"""
+from __future__ import annotations
+
+from ..builder import Protocol
+from ..crc import sum8
+from ..spec import ChecksumRule, Field, FrameSpec
+
+START = 0x68
+END = 0x16
+
+
+SPEC = FrameSpec(
+    fields=[
+        Field.u8("start", fixed=START),
+        Field.u8("len"),
+        Field.u8("len2"),
+        Field.u8("mid", fixed=START),
+        Field.u8("ctrl"),
+        Field.u8("addr", desc="从站地址（设备号）"),
+        Field.u8("ci"),
+        Field.raw("data", "{len.val}-3"),
+        Field.checksum("cs", 1, group="{start}{len}{len2}{mid}{ctrl}{addr}{ci}{data}"),
+        Field.u8("end", fixed=END),
+    ],
+    payload="data",
+    checksum=ChecksumRule("cs", sum8),
+    device="addr",
+    max_frame_size=256,
+    desc="M-Bus long frame",
+)
+
+
+def protocol(device_id: int = None, enforce_device_id: bool = False) -> Protocol:
+    return Protocol(SPEC, device_id=device_id, enforce_device_id=enforce_device_id)
+
+
+def build_mbus(ctrl: int, addr: int, ci: int, data: bytes = b"") -> bytes:
+    """手工组一条 M-Bus 长帧（自动填两份相同的 L 与累加和 CS）。
+
+    注意：这里没有走 ``FrameBuilder``，因为第二份长度字节无法被 builder 自动复制。
+    """
+    length = 3 + len(data)  # C + A + CI + DATA
+    body = bytes([START, length, length, START, ctrl & 0xFF, addr & 0xFF, ci & 0xFF]) + data
+    cs = sum8(body)  # 从第一个 0x68 到 DATA 末尾
+    return body + bytes([cs, END])