kkprotocol 0.1.0__py3-none-any.whl

kkprotocol/contrib/modbus_ascii.py

@@ -0,0 +1,59 @@
+# -*- coding: utf-8 -*-
+"""Modbus ASCII（Modbus 的 ASCII 传输模式，与 RTU 同语义但用文本 hex 编码）。
+
+帧结构（分隔符定界）：::
+
+    ':'  <hex 对：地址 功能码 数据...>  <LRC(2 hex)>  CR LF
+
+要点（压测点）：
+
+* 协议**帧内载荷是 ASCII 十六进制文本**，每个字节用两个字符表示；库是字节级解析，
+  没有“先按 ASCII-Hex 解码”的传输层原语 —— 这里在组帧/解析后手动 hex 编解码，
+  说明库缺一个“传输编码（ASCII-Hex / Base64 / …）”钩子；
+* LRC 是地址..数据累加和的两补码（取低 8 位），落在帧内、以 2 个 hex 字符表示；
+* 分隔符是 ``':'`` 开头、``'\\n'`` 结尾（中间带 ``'\\r'``），无转义。
+
+和 Modbus RTU（见 example_modbus_rtu / example_modbus_rtu_multi）对照：同一套应用语义，RTU 用二进制 + CRC16，
+ASCII 用文本 + LRC，正好测“同协议不同传输编码”库能否分开表达。
+"""
+from __future__ import annotations
+
+from ..crc import sum8
+from ..framing import DelimiterFraming, wrap_frame
+from ..spec import Field, FrameSpec
+
+ASCII = DelimiterFraming(start=0x3A, end=0x0A)  # ':' ... '\n'
+
+
+SPEC = FrameSpec(
+    fields=[Field.rest("body", desc="ASCII-Hex 文本（地址/功能码/数据/LRC）")],
+    framing=ASCII,
+    desc="Modbus ASCII",
+)
+
+
+def codec():
+    return SPEC.to_codec()
+
+
+def lrc(bytes_: bytes) -> int:
+    """Modbus ASCII LRC：地址..数据的累加和的两补码（低 8 位）。"""
+    return (-sum8(bytes_)) & 0xFF
+
+
+def build(addr: int, func: int, data: bytes = b"") -> bytes:
+    """组一条 Modbus ASCII 帧（data 为应用层二进制字节）。"""
+    payload = bytes([addr, func]) + data
+    hexstr = payload.hex() + lrc(payload).to_bytes(1, "big").hex()
+    # 加 ':' 与 '\\n'，并保留结尾前的 '\\r'
+    return wrap_frame((hexstr + "\r").encode("ascii"), ASCII)
+
+
+def decode(body: bytes):
+    """解析 body：返回 (addr, func, data)，并校验 LRC。"""
+    text = body.replace(b"\r", b"").decode("ascii")
+    raw = bytes.fromhex(text)
+    pdu, lrc_byte = raw[:-1], raw[-1]
+    if lrc(pdu) != lrc_byte:
+        raise ValueError("LRC 校验失败")
+    return pdu[0], pdu[1], pdu[2:]

kkprotocol/contrib/nmea.py

@@ -0,0 +1,59 @@
+# -*- coding: utf-8 -*-
+"""NMEA-0183（GPS/船舶导航文本语句）。
+
+帧结构（分隔符定界，纯文本）：::
+
+    '$'  <语句体，逗号分隔字段>  '*'  <XX 校验和（2 hex）>  CR LF
+
+要点（压测点）：
+
+* 完全是**文本记录**协议：字段靠逗号分隔、校验和嵌在 ``*XX`` 里，不是固定字节布局；
+* 库是字节/字段级模型，对这种“分隔符内再嵌文本 + 内联校验和”的形态，靠一个 ``rest``
+  字段把整段拿到手，再在外面（或 crc_imp 里）做 XOR 校验；说明库对纯文本记录协议
+  只有“半原生”支持（能切帧，但字段解析得自己来）；
+* 校验和是 ``$`` 与 ``*`` 之间所有字符的异或，落在帧内而非帧尾。
+
+和 Modbus ASCII 一起，代表“分隔符定界 + 文本/ASCII 编码”这一类协议，测库对非二进制
+协议的包容度。
+"""
+from __future__ import annotations
+
+from ..framing import DelimiterFraming, wrap_frame
+from ..spec import Field, FrameSpec
+
+NMEA = DelimiterFraming(start=0x24, end=0x0A)  # '$' ... '\n'
+
+
+SPEC = FrameSpec(
+    fields=[Field.rest("body", desc="语句体 + '*XX' 校验和")],
+    framing=NMEA,
+    desc="NMEA-0183",
+)
+
+
+def codec():
+    return SPEC.to_codec()
+
+
+def sentence_checksum(text: str) -> int:
+    """'$' 与 '*' 之间字符的异或。"""
+    x = 0
+    for ch in text:
+        x ^= ord(ch)
+    return x
+
+
+def build(sentence: str) -> bytes:
+    """组一条 NMEA 语句（sentence 不含 '$'/'*XX'/CRLF，如 'GPGGA,....'）。"""
+    cks = sentence_checksum(sentence).to_bytes(1, "big").hex().upper()
+    body = (sentence + "*" + cks + "\r").encode("ascii")
+    return wrap_frame(body, NMEA)
+
+
+def decode(body: bytes):
+    """解析 body：返回 (语句体, 校验和是否通过)。"""
+    text = body.replace(b"\r", b"").decode("ascii")
+    if "*" not in text:
+        raise ValueError("缺少 '*' 校验和分隔符")
+    payload, cks = text.split("*", 1)
+    return payload, sentence_checksum(payload) == int(cks, 16)

kkprotocol/contrib/slip.py

@@ -0,0 +1,38 @@
+# -*- coding: utf-8 -*-
+"""SLIP（Serial Line Internet Protocol，RFC 1055）。
+
+定界方式：以 ``0xC0`` 为帧首尾标志，``0xDB`` 为转义字节：
+
+* ``0xC0`` -> ``0xDB 0xDC``
+* ``0xDB`` -> ``0xDB 0xDD``
+
+SLIP 本身没有长度字段也没有校验和（依赖上层协议）。这里用来验证：
+
+* 分隔符定界的转义/反转义正确性（净荷里含 0xC0 / 0xDB 时不能误判边界）；
+* 首尾共用同一个标志字节（``start == end == 0xC0``，PPP/HDLC 同款写法）。
+"""
+from __future__ import annotations
+
+from ..framing import DelimiterFraming, wrap_frame
+from ..spec import Field, FrameSpec
+
+SLIP = DelimiterFraming(
+    end=0xC0, escape=0xDB, escape_map={0xC0: 0xDC, 0xDB: 0xDD}
+)
+
+
+SPEC = FrameSpec(
+    fields=[Field.rest("data", desc="净荷，取到帧尾 0xC0 为止")],
+    framing=SLIP,
+    desc="SLIP",
+)
+
+
+def codec():
+    """返回一个可直接 feed() 的 SLIP 解析器。"""
+    return SPEC.to_codec()
+
+
+def build(data: bytes) -> bytes:
+    """组一条 SLIP 帧（加首尾 0xC0 + 转义）。"""
+    return wrap_frame(data, SLIP)

kkprotocol/contrib/xmodem.py

@@ -0,0 +1,74 @@
+# -*- coding: utf-8 -*-
+"""XModem / YModem 文件传输协议（串口，块传输）。
+
+XModem 帧结构（长度定界，固定 133 字节，无帧头定界符，靠同步字节 0x01 找起点）：::
+
+    SOH(0x01)  块号(1)  ~块号(1)  DATA(128)  CRC16-CCITT(2)
+
+YModem 把 DATA 扩到 1024 字节、标志改成 STX(0x02)，其余相同。
+
+要点（压测点）：
+
+* **帧大小完全固定**（133 / 1029 字节），没有长度字段、也没有帧尾定界符 —— 只靠
+  起始字节 ``0x01``/``0x02`` 与固定数据长度切帧。库用 ``Field.raw("data", 128)`` 的
+  **常量长度** + 同步字节就能正确建模，不强制要长度字段，这点设计是够用的；
+* CRC 用 CRC-16/CCITT（多项式 0x1021，初值 0x0000，非反射）；
+* 块号与 ``~块号`` 是冗余关系（0xFF - 块号），库不自动校验这种“字段互证”，测试里手判。
+"""
+from __future__ import annotations
+
+from ..builder import FrameBuilder, Protocol
+from ..crc import crc16_ccitt
+from ..spec import ChecksumRule, Field, FrameSpec
+
+_XMODEM_CRC = lambda group: crc16_ccitt(group, 0x0000)
+
+SPEC_X = FrameSpec(
+    fields=[
+        Field.u8("soh", fixed=0x01),
+        Field.u8("blk"),
+        Field.u8("inv"),
+        Field.raw("data", 128),
+        Field.checksum("crc", 2, fmt="!H", group="{soh}{blk}{inv}{data}"),
+    ],
+    payload="data",
+    checksum=ChecksumRule("crc", _XMODEM_CRC),
+    max_frame_size=133,
+    desc="XModem (128-byte blocks)",
+)
+
+SPEC_Y = FrameSpec(
+    fields=[
+        Field.u8("stx", fixed=0x02),
+        Field.u8("blk"),
+        Field.u8("inv"),
+        Field.raw("data", 1024),
+        Field.checksum("crc", 2, fmt="!H", group="{stx}{blk}{inv}{data}"),
+    ],
+    payload="data",
+    checksum=ChecksumRule("crc", _XMODEM_CRC),
+    max_frame_size=1029,
+    desc="YModem (1024-byte blocks)",
+)
+
+
+def protocol_x() -> Protocol:
+    return Protocol(SPEC_X)
+
+
+def protocol_y() -> Protocol:
+    return Protocol(SPEC_Y)
+
+
+def build_xmodem(blk: int, data: bytes) -> bytes:
+    """组一条 XModem 块（data 必须正好 128 字节）。"""
+    if len(data) != 128:
+        raise ValueError("XModem 数据块必须 128 字节")
+    return FrameBuilder(SPEC_X).build_raw(None, data, blk=blk, inv=(0xFF - blk) & 0xFF)
+
+
+def build_ymodem(blk: int, data: bytes) -> bytes:
+    """组一条 YModem 块（data 必须正好 1024 字节）。"""
+    if len(data) != 1024:
+        raise ValueError("YModem 数据块必须 1024 字节")
+    return FrameBuilder(SPEC_Y).build_raw(None, data, blk=blk, inv=(0xFF - blk) & 0xFF)

kkprotocol/crc.py

@@ -0,0 +1,103 @@
+# -*- coding: utf-8 -*-
+"""常用校验算法（查表实现，纯标准库，无第三方依赖）。
+
+- :func:`crc16_modbus` CRC-16/MODBUS，多项式 0xA001，初值 0xFFFF，无异或输出
+- :func:`crc16_x25`    CRC-16/X-25（PPP/HDLC FCS-16），反射多项式 0x8408，初值 0xFFFF，输出异或 0xFFFF
+- :func:`sum8` / :func:`xor8` 简单累加/异或校验
+"""
+
+from __future__ import annotations
+
+__all__ = [
+    "crc16_modbus",
+    "crc16_x25",
+    "crc16_ccitt",
+    "crc8",
+    "sum8",
+    "xor8",
+]
+
+
+def _build_table(poly: int) -> tuple:
+    table = []
+    for index in range(256):
+        crc = index
+        for _ in range(8):
+            crc = (crc >> 1) ^ poly if crc & 0x0001 else crc >> 1
+        table.append(crc)
+    return tuple(table)
+
+
+def _build_table_msb(poly: int) -> tuple:
+    """非反射（MSB-first）CRC16 查表，用于 CCITT 这类不反射的算法。"""
+    table = []
+    poly &= 0xFFFF
+    for index in range(256):
+        crc = (index << 8) & 0xFFFF
+        for _ in range(8):
+            crc = ((crc << 1) ^ poly) & 0xFFFF if crc & 0x8000 else (crc << 1) & 0xFFFF
+        table.append(crc & 0xFFFF)
+    return tuple(table)
+
+
+_CRC16_MODBUS_TABLE = _build_table(0xA001)
+_CRC16_X25_TABLE = _build_table(0x8408)
+_CRC16_CCITT_TABLE = _build_table_msb(0x1021)
+
+
+def crc16_modbus(data: bytes) -> int:
+    """CRC-16/MODBUS。校验向量：``crc16_modbus(b"123456789") == 0x4B37``。"""
+    crc = 0xFFFF
+    table = _CRC16_MODBUS_TABLE
+    for byte in data:
+        crc = (crc >> 8) ^ table[(crc ^ byte) & 0xFF]
+    return crc
+
+
+def crc16_x25(data: bytes) -> int:
+    """CRC-16/X-25（PPP FCS）。校验向量：``crc16_x25(b"123456789") == 0x906E``。"""
+    crc = 0xFFFF
+    table = _CRC16_X25_TABLE
+    for byte in data:
+        crc = (crc >> 8) ^ table[(crc ^ byte) & 0xFF]
+    return crc ^ 0xFFFF
+
+
+def sum8(data: bytes) -> int:
+    """单字节累加和（取低 8 位）。"""
+    return sum(data) & 0xFF
+
+
+def crc16_ccitt(data: bytes, init: int = 0x0000) -> int:
+    """CRC-16/CCITT（非反射，多项式 0x1021，MSB-first）。
+
+    两种常用初值：XModem 为 ``0x0000``，BACnet 数据段为 ``0xFFFF``。
+    校验向量：``crc16_ccitt(b"123456789", 0x0000) == 0x31C3``（XModem），
+    ``crc16_ccitt(b"123456789", 0xFFFF) == 0x29B1``（CCITT-FALSE）。"""
+    crc = init & 0xFFFF
+    table = _CRC16_CCITT_TABLE
+    for byte in data:
+        crc = ((crc << 8) ^ table[((crc >> 8) ^ byte) & 0xFF]) & 0xFFFF
+    return crc
+
+
+def crc8(data: bytes, poly: int = 0x07, init: int = 0x00) -> int:
+    """通用非反射 CRC-8（MSB-first，逐位实现，无需查表）。
+
+    BACnet MS/TP 头部校验即 ``crc8(data, poly=0x07, init=0xFF)``；
+    其“发送值”为 ``(~crc8(...) & 0xFF)``，正确帧接收端复算结果为 0x55。"""
+    crc = init & 0xFF
+    poly &= 0xFF
+    for byte in data:
+        crc ^= byte
+        for _ in range(8):
+            crc = ((crc << 1) ^ poly) & 0xFF if crc & 0x80 else (crc << 1) & 0xFF
+    return crc
+
+
+def xor8(data: bytes) -> int:
+    """单字节异或校验。"""
+    result = 0
+    for byte in data:
+        result ^= byte
+    return result

kkprotocol/errors.py

@@ -0,0 +1,48 @@
+# -*- coding: utf-8 -*-
+"""异常定义。"""
+
+from __future__ import annotations
+
+__all__ = ["FrameCodecError", "FrameRuleError", "FrameBuildError"]
+
+
+class FrameCodecError(Exception):
+    """编解码器错误基类。"""
+
+
+class FrameRuleError(FrameCodecError, ValueError):
+    """规则/配置声明错误 —— 开发者写错了，属于代码缺陷，直接抛出不做重同步。
+
+    典型场景：字段 key 重复、长度表达式引用前向字段、fmt 字节数与声明长度不一致、
+    定界模式配置非法（定界符越界、转义字节与定界符冲突）。
+    """
+
+
+class FrameBuildError(FrameCodecError, ValueError):
+    """组帧失败 —— 参数缺失/类型不符/长度越界/回填不收敛。
+
+    与 :class:`FrameRuleError` 的区别：规则本身没错，是这次调用的入参或数据
+    凑不出合法帧，属于调用方需要修的地方。
+    """
+
+
+class FrameInvalid(Exception):
+    """内部信号：当前位置不是合法帧（脏数据 / 常量不符 / 校验失败 / 长度不符）。
+
+    ``consumed > 0`` 表示该候选帧在流中占用的字节数已知（分隔符模式必然已知），
+    重同步时可以直接跳过整段候选；``consumed == 0`` 表示只能逐字节/按锚点重试。
+    """
+
+    def __init__(
+        self,
+        reason: str,
+        *,
+        consumed: int = 0,
+        crc_failed: bool = False,
+        length_mismatch: bool = False,
+    ) -> None:
+        super().__init__(reason)
+        self.reason = reason
+        self.consumed = consumed
+        self.crc_failed = crc_failed
+        self.length_mismatch = length_mismatch

kkprotocol/example_device.py

@@ -0,0 +1,186 @@
+# -*- coding: utf-8 -*-
+"""两个可直接运行的示例帧，也是写自己协议时的参考模板。
+
+一、长度定界（推荐，TCP 场景首选）::
+
+    55 | len | ver | cmd | ser(2) | dev_id(4) | data(len-10) | crc(2)
+    len = ver..crc 的总字节数；crc = CRC16/MODBUS(len..data)，大端
+
+二、分隔符定界（PPP/HDLC 风格，串口/透传设备常见）::
+
+    7E | ff 03 | len | dev_id(4) | data(len) | fcs(2) | 7E
+    净荷中的 7E/7D 分别转义为 7D 5E / 7D 5D；fcs = CRC16/X-25(ff03..data)
+    len 只是参考值，真正切帧靠 7E —— 净荷里出现 7E 也不会误判。
+
+三、帧首就是设备号（没有固定帧头，设备号首帧未知）::
+
+    dev_id(4) | cmd | n | data(n) | crc(2)
+
+    设备号只在首帧/注册包未知，学到后就固定，因此把它当同步字用，
+    详见 :class:`HeadDeviceFrameCodec`。
+"""
+
+from __future__ import annotations
+
+import struct
+from typing import Any, Dict, List, Optional, Sequence, Union
+
+from .codec import AbstractFrameCodec
+from .crc import crc16_modbus, crc16_x25
+from .fields import Field
+from .framing import DelimiterFraming, wrap_frame
+
+__all__ = [
+    "DEVICE_FIELDS",
+    "HEAD_DEVICE_FIELDS",
+    "HEADER",
+    "PPP_FLAG",
+    "PPP_ESCAPE",
+    "DeviceFrameCodec",
+    "HeadDeviceFrameCodec",
+    "PppFrameCodec",
+    "build_device_frame",
+    "build_head_device_frame",
+    "build_ppp_frame",
+]
+
+HEADER = 0x55
+PPP_FLAG = 0x7E
+PPP_ESCAPE = 0x7D
+PPP_ADDRESS = 0xFF
+PPP_CONTROL = 0x03
+
+DEVICE_FIELDS: List[Field] = [
+    Field.u8("header", fixed=HEADER, desc="帧头"),
+    Field.u8("len", desc="ver..crc 的总字节数"),
+    Field.u8("ver", desc="协议版本"),
+    Field.u8("cmd", desc="命令字"),
+    Field.u16("ser", desc="序列号"),
+    Field.raw("dev_id", 4, desc="设备号"),
+    Field.raw("data", "{len.val}-10", desc="变长净荷"),
+    Field.checksum("crc", 2, group="{len}{ver}{cmd}{ser}{dev_id}{data}", desc="CRC16/MODBUS"),
+]
+
+PPP_FIELDS: List[Field] = [
+    Field.u8("addr", fixed=PPP_ADDRESS),
+    Field.u8("ctrl", fixed=PPP_CONTROL),
+    Field.u8("len", desc="净荷长度，仅作校验"),
+    Field.raw("dev_id", 4, desc="设备号"),
+    Field.raw("data", "{len.val}", desc="变长净荷"),
+    Field.checksum("fcs", 2, group="{addr}{ctrl}{len}{dev_id}{data}", desc="CRC16/X-25"),
+]
+
+HEAD_DEVICE_FIELDS: List[Field] = [
+    Field.raw("dev_id", 4, desc="设备号（帧首，首帧未知）"),
+    Field.u8("cmd", desc="命令字"),
+    Field.u8("n", desc="净荷字节数"),
+    Field.raw("data", "{n.val}", desc="净荷"),
+    Field.checksum("crc", 2, group="{dev_id}{cmd}{n}{data}", desc="CRC16/MODBUS"),
+]
+
+
+class DeviceFrameCodec(AbstractFrameCodec):
+    """长度定界示例：按 ``len`` 字段切帧，自动处理黏包/半包/脏数据。"""
+
+    device_field = "dev_id"
+
+    def rules(self) -> Sequence[Union[Field, Dict[str, Any]]]:
+        return DEVICE_FIELDS
+
+    def crc_imp(self, data: bytes) -> int:
+        return crc16_modbus(data)
+
+
+def build_device_frame(
+    ver: int = 1,
+    cmd: int = 0x03,
+    ser: int = 1,
+    dev_id: bytes = b"\x00\x00\x00\x01",
+    payload: bytes = b"\x01\x02",
+    bad_crc: bool = False,
+) -> bytes:
+    """按 :class:`DeviceFrameCodec` 的规则构造一帧（测试与模拟设备用）。"""
+    body = struct.pack("!BBH4s", ver, cmd, ser, dev_id) + payload
+    length = len(body) + 2
+    crc = crc16_modbus(bytes([length]) + body)
+    if bad_crc:
+        crc ^= 0xFFFF
+    return bytes([HEADER, length]) + body + struct.pack("!H", crc)
+
+
+class HeadDeviceFrameCodec(AbstractFrameCodec):
+    """帧首就是设备号、没有固定帧头的示例（设备号首帧未知，之后固定）。
+
+    这是"设备号打头"这类私有协议的标准配置：
+
+    * ``sync_from_device``：学到设备号后拿它当同步字，重同步从"逐字节试探"
+      变成"一次跳转"；
+    * ``lock_device_after_learn``：学到即固定，之后设备号不符的帧按脏数据丢掉
+      （多设备挂在同一条总线上时请关掉，改为看 ``frame.device_mismatch``）；
+    * ``max_frame_size``：取略大于真实最大帧（n 是 u8，最大 255+8），
+      假长度一旦超过它就立刻被判死，不至于把缓冲区堵住；
+    * ``preempt_on_sync``：默认关。开启后，若候选帧还在等长度、但它区间内已经
+      出现"完整且校验通过"的帧，就用锚点切断——这是长度定界下唯一能救回
+      "被假长度堵住的后续真帧"的手段，代价是载荷里恰好出现锚点字节串时可能误切；
+    * ``idle_timeout``：``read_frames`` 空闲 5 秒就把半包丢掉（TCP 建连瞬间
+      从帧中间接入时的兜底）。
+    """
+
+    device_field = "dev_id"
+    max_frame_size = 300
+    sync_from_device = True
+    lock_device_after_learn = True
+    preempt_on_sync = False
+    idle_timeout = 5.0
+
+    def rules(self) -> Sequence[Union[Field, Dict[str, Any]]]:
+        return HEAD_DEVICE_FIELDS
+
+    def crc_imp(self, data: bytes) -> int:
+        return crc16_modbus(data)
+
+
+def build_head_device_frame(
+    dev_id: bytes = b"\x00\x00\x00\x01",
+    cmd: int = 0x01,
+    payload: bytes = b"ping",
+    bad_crc: bool = False,
+) -> bytes:
+    """按 :class:`HeadDeviceFrameCodec` 的规则构造一帧。"""
+    body = dev_id + bytes([cmd, len(payload)]) + payload
+    crc = crc16_modbus(body)
+    if bad_crc:
+        crc ^= 0xFFFF
+    return body + struct.pack("!H", crc)
+
+
+class PppFrameCodec(AbstractFrameCodec):
+    """分隔符定界示例：0x7E 首尾定界 + 0x7D 转义，长度字段仅作校验项。"""
+
+    framing = DelimiterFraming(
+        end=PPP_FLAG, start=PPP_FLAG, escape=PPP_ESCAPE, escape_xor=0x20
+    )
+    device_field = "dev_id"
+
+    def rules(self) -> Sequence[Union[Field, Dict[str, Any]]]:
+        return PPP_FIELDS
+
+    def crc_imp(self, data: bytes) -> int:
+        return crc16_x25(data)
+
+
+def build_ppp_frame(
+    dev_id: bytes = b"\x00\x00\x00\x01",
+    payload: bytes = b"ping",
+    bad_fcs: bool = False,
+    declared_length: Optional[int] = None,
+    spec: Optional[DelimiterFraming] = None,
+) -> bytes:
+    """按 :class:`PppFrameCodec` 的规则构造一帧（含转义）。"""
+    spec = spec or PppFrameCodec.framing
+    length = len(payload) if declared_length is None else declared_length
+    body = bytes([PPP_ADDRESS, PPP_CONTROL, length]) + dev_id + payload
+    fcs = crc16_x25(body)
+    if bad_fcs:
+        fcs ^= 0xFFFF
+    return wrap_frame(body + struct.pack("!H", fcs), spec)