项目亮点#

为什么选择 TVLCOM?

• 固定帧格式（Header + FrameID + TLV 数据 + CRC16 + Tail）
• TLV 构造与解析工具，扩展类型方便
• 字节流解析状态机，适合串口等流式链路
• 回调分发器（Dispatcher），带 ACK/NACK 机制
• 传输层可插拔（内置串口，易扩展为 TCP/UDP 等）

WARNING

如果你的场景需要一个“既简单、又可靠、还容易扩展”的轻量通信协议，TVLCOM 会很合适。

快速开始#

环境准备

• Python >= 3.10
• Windows / Linux / macOS 均可（以 Windows 串口为主要测试场景）
• 依赖：pyserial

1
# 进入项目目录
2
cd E:\PROJECT_Python\TVLCOM
3

4
# 创建虚拟环境（可选）
5
python -m venv .venv
6
.\.venv\Scripts\activate
7

8
# 安装依赖（可编辑模式开发）
9
pip install -e .

串口端口号

请根据实际情况修改示例代码中的串口端口号（例如 COM3 更换为你的实际端口）。

1
cd E:\PROJECT_Python\TVLCOM
2
python main.py

基本用法示例#

发送一帧字符串 + 命令

1
from PYTVLCOM import (
2
    Dispatcher,
3
    TLVParser,
4
    FrameDefine,
5
    create_transport,
6
    createStringEntry,
7
    createCtrlCmdEntry,
8
    buildFrame,
9
)
10

11
transport = create_transport("serial", port="COM3", baud=115200, timeout=0.1)
12

13
dispatcher = Dispatcher(transport)
14
parser = TLVParser(dispatcher.handleFrame, on_error=print)
15

16
@dispatcher.type_handler(FrameDefine.TLV_TYPE_STRING)
17
def on_string(value_bytes: bytes):
18
    print("收到字符串:", value_bytes.decode("utf-8", errors="ignore"))
19
    return True
20

21
@dispatcher.cmd_handler(0x10)
22
def on_cmd_0x10():
23
    print("收到命令 0x10")
24
    return True
25

26
str_tlv = createStringEntry("hello TVLCOM")
27
cmd_tlv = createCtrlCmdEntry(0x10)
28
payload = cmd_tlv + str_tlv
29

30
frame = buildFrame(0x01, payload)
31
transport.send(frame)
32

33
# 简单接收循环（示意）
34
while True:
35
    data = transport.feed(1024)
36
    for b in data:
37
        parser.process_byte(b)

1
from PYTVLCOM import buildFrame, createInt32Entry, createStringEntry, FrameDefine
2

3
tlv1 = createInt32Entry(FrameDefine.TLV_TYPE_INTEGER, 42)
4
tlv2 = createStringEntry("parameter updated")
5

6
payload = tlv1 + tlv2
7
frame = buildFrame(0x02, payload)
8

9
your_send_function(frame)  # 将 frame 发送到你自己的链路

协议与帧格式（速览）#

固定帧结构

字段顺序	长度	描述
Header	2B	固定 0xF0 0x0F 用于同步
FrameID	1B	帧编号/逻辑会话 ID
DataLen	1B	TLV 数据区总字节长度
Data	N	若干 TLV 串接
CRC16	2B	对 FrameID + DataLen + Data 做 CCITT(0x1021, init=0xFFFF)，大端
Tail	2B	固定 0xE0 0x0D 结束标记

进阶话题#

扩展传输层

实现你自己的 Transport（TCP/UDP/CAN 等），并通过 @register_transport('your_name') 注册，然后用 create_transport('your_name', ...) 统一创建实例。

CRC 不匹配如何排查

• 两端必须使用相同的 CRC16-CCITT 参数（多项式 0x1021、初值 0xFFFF）。
• 计算范围为 FrameID + DataLen + Data，并以大端序写入结果。

更多信息（隐藏彩蛋）#

TLV 解析要点：循环读取 Data，每次取 [type, len, value] 并校验越界与长度一致性；任意阶段出现错误应回退到 SYNC。

结语#

TVLCOM 力求在“简单”与“可用”之间取得平衡，用统一帧格式与 TLV 表达常用的数据与命令场景，同时提供解析与分发工具，减少你在上位机/设备端的协议实现负担。欢迎基于此扩展更多 TLV 类型与传输方式。