1. 把 TGAM 串口解析封装成功能库:先想清楚它解决什么问题
把 TGAM 串口解析封装成一个可复用的 Python 功能库,是我最近做脑电采集小工具时最省事的一步。TGAM 模块通过串口以 57600 波特率往外吐 0xAA 0xAA 开头的二进制包,包里既有信号质量、注意力、冥想值,也有 RAW Wave 原始波形。若把找同步头、切包、校验和、TLV 解析全塞进绘图循环,代码会又长又难排查;绘图一卡,解析也跟着丢包。这个功能库只做一件事:从字节流里稳定拿出完整包,解析成 numpy 数组和指标字典,绘图、存储、上报各自接走。它适合已经能把串口打开、但被波形跳跃或坏包率折腾过的嵌入式/Python 开发者,也适合第一次接 TGAM、想把协议层和 UI 层隔开的人。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 功能库的边界:pyserial 负责字节流,numpy 负责波形数组
2.1 串口参数与帧格式:57600 波特率下的 AA AA 包
先把串口打开这件事做对,后面的解析才有意义。材料里的读取入口是 pyserial,参数很朴素,但每一个都影响后面切包:port 是系统枚举出来的串口名,代码里写的是 COM5,换一台机器就要换成实际端口;baudrate=57600 必须和 TGAM 固件输出一致,波特率不对时读到的不是“慢一点”,而是整段字节错位;timeout=0.1 让 read() 在没有数据时返回,而不是把线程卡死。我一般不会把 timeout 设成 0,因为 0 会变成忙等,CPU 占用会很难看。
python复制import serial
import numpy as np
ser = serial.Serial(
port='COM5', # 换成实际枚举到的串口
baudrate=57600, # 与 TGAM 固件输出保持一致
timeout=0.1, # 读空即返回,避免阻塞
)
这段代码只做了一件事:建立一个带超时的串口对象。port 写错会直接抛打开失败;baudrate 写成 115200 这类值,读回来的字节会整体错位,校验和基本过不了;timeout 太大,绘图线程会等;太小或为 0,又会把 CPU 拉满。numpy 在这里不是拿来算滤波的,而是接住 RAW Wave 数组,后面按批处理时比 Python 列表省事。
TGAM 的包结构可以用一张表固定下来,后面所有切包代码都围着它转:
| 偏移 | 字段 | 长度 | 说明 |
|---|---|---|---|
| 0-1 | 同步头 | 2 字节 | 固定 0xAA 0xAA |
| 2 | plen | 1 字节 | 载荷字节数 |
| 3 到 3+plen-1 | payload | plen 字节 | TLV 或 RAW 数据 |
| 3+plen | checksum | 1 字节 | sum(plen + payload) & 0xFF |
一帧总长是 plen + 4。代码里判断“够不够一帧”用的是 len(buffer) < 3 + plen + 1,也就是同步头 2 字节、长度 1 字节、载荷 plen 字节、校验 1 字节。这个偏移关系一旦记错,典型现象就是“偶尔能解出信号质量,但 RAW 全是乱的”。
2.2 为什么把解析逻辑独立成库而不是塞进绘图循环
我见过也写过把 ser.read()、找 0xAA、解 TLV、更新曲线全放在一个 while True 里的版本。那种写法在实验室桌面跑 demo 没问题,一旦绘图稍微重一点,串口缓冲区就开始堆包,最后看到的现象是“波形越跑越滞后”,而不是报错。血泪经验是:串口读取和绘图刷新是两种节奏,硬绑在一起,任何一边抖动都会把另一边拖下水。
独立成功能库的第一个好处是职责清楚。pyserial 只负责把字节流读进来,numpy 只负责把 RAW 点组织成数组,协议解析只负责“这一帧里有什么”。绘图模块拿到的是已经解析好的 dict,它不需要知道 0xAA 0xAA 在哪、校验和怎么算。第二个好处是可测试:没有串口也能喂一段 payload 给 parse_packet,用固定字节样本锁住行为,改代码时不用每次插硬件。第三个好处是坏包可统计:同步失败、校验失败、TLV 越界分别计数,出了问题能定位到“是串口没同步”还是“固件 RAW 打包方式变了”,而不是对着一条抖动的曲线猜。
这里有一个边界要提前说清:功能库不负责“把波形画得好看”,也不负责“把数据存成什么文件格式”。它只保证从字节流到结构化结果这一段稳定。绘图节流、落盘、上报都放在库外,这样换 UI 或换存储方式时,解析层不用动。
2.3 功能库对外接口设计:read_packet / parse_packet / 输出字典
接口我尽量压到三个:read_packet() 负责读串口并返回一个完整包的解析结果,没有完整包时返回 None;parse_packet(payload) 只解析载荷,不碰串口;close() 释放串口。返回值统一用字典,键名固定为 raw、signal、attention、meditation,有哪个就放哪个。这样上层写 if 'raw' in result 就能决定要不要推波形,不用关心协议细节。
python复制class TGAMParser:
def __init__(self, port='COM5', baudrate=57600, timeout=0.1):
self.ser = serial.Serial(port, baudrate=baudrate, timeout=timeout)
self.buffer = bytearray()
self.bad_packets = 0
def read_packet(self):
# 读串口、找同步头、切完整包;没有完整包返回 None
...
def parse_packet(self, payload):
# 只解析载荷,不碰串口
...
def close(self):
self.ser.close()
这个骨架里,buffer 用 bytearray 而不是 bytes,因为要频繁切片和追加;bad_packets 放在类里,方便上层隔一段时间打印一次坏包数。read_packet 返回 None 不是异常,而是“这一轮没凑齐一帧”,调用方继续循环即可。parse_packet 不依赖串口,后面做单元测试可以直接 TGAMParser.__new__(TGAMParser) 绕过 __init__,避免测试时去打开 COM5。
3. 功能库核心实现:同步头、长度、校验和与 TLV 解析
3.1 接收缓冲区的滑动窗口:先找 AA AA 再切包
串口读进来的第一段字节不一定从帧头开始,可能是上一帧的尾巴,也可能是半包。所以 read_packet 的第一原则是“先同步,再切包”。材料里的做法是:不断从缓冲区头部检查 0xAA 0xAA,不是就 pop(0) 丢掉一个字节;是的话读第三字节 plen,如果缓冲区还不够 plen + 4,就 break 保留现场,等下一轮 read() 补字节;够了就切出候选包,算校验和,校验通过才解析并删除整帧,校验失败也要删除整帧并计数。
python复制def read_packet(self):
while True:
data = self.ser.read(512)
if data:
self.buffer.extend(data)
while len(self.buffer) >= 4:
if self.buffer[0] == 0xAA and self.buffer[1] == 0xAA:
plen = self.buffer[2]
if len(self.buffer) < 3 + plen + 1:
break
packet = bytes(self.buffer[2:3 + plen])
checksum = self.buffer[3 + plen]
if sum(packet) & 0xFF == checksum:
result = self.parse_packet(packet[1:])
del self.buffer[:3 + plen + 1]
return result
else:
self.bad_packets += 1
del self.buffer[:3 + plen + 1]
else:
self.buffer.pop(0)
return None
这段代码里,self.ser.read(512) 一次读一块,减少循环次数;timeout=0.1 保证没有数据时也不会永久卡住。while len(self.buffer) >= 4 是最小可切包长度,因为同步头 2 字节加长度 1 字节加校验 1 字节至少 4 字节。packet = bytes(self.buffer[2:3 + plen]) 取的是“长度字节 + 载荷”,校验和覆盖这个范围,不是只覆盖载荷。校验失败时仍然 del self.buffer[:3 + plen + 1],这一点很关键:坏包如果不推进,下一轮还会从同一个位置重新检查,缓冲区会越积越乱。同步头不对时 pop(0) 是滑动窗口,虽然逐字节丢在高速流下不算最快,但逻辑最不容易错。
注意:如果长时间找不到
0xAA 0xAA,逐字节pop(0)在数据量大时会有点慢。常见做法是先找到下一个0xAA的位置再整体切片,但前提是同步逻辑已经稳定,否则容易引入新的偏移错误。
3.2 校验和计算范围:别把长度字节漏掉
校验和是这套解析里最容易翻车的地方。材料里的写法是 sum(packet) & 0xFF == checksum,而 packet 来自 buffer[2:3 + plen],它包含 plen 本身和后面的 payload。换句话说,校验和覆盖“长度字节 + 载荷”,不覆盖两个 0xAA,也不覆盖校验字节自己。只算 payload 的写法在少数帧上可能碰巧过,但大多数帧会失败,表现就是“坏包率很高,偶尔又能解出一两个指标”。
python复制def checksum_ok(buffer, plen):
packet = bytes(buffer[2:3 + plen]) # 长度字节 + 载荷
checksum = buffer[3 + plen]
return (sum(packet) & 0xFF) == checksum
这个函数把校验范围单独抽出来,方便在排查时打印 packet 的十六进制。plen 是载荷字节数,不是总包长;3 + plen 是校验字节在缓冲区里的下标。常见误用有两种:一种是把 packet 写成 buffer[3:3+plen],漏掉长度字节;另一种是切包时把 plen 当成总长,导致校验字节位置整体偏一位。两种都会让 bad_packets 持续上涨,而且波形看起来像“有信号但全是毛刺”。
3.3 解析 TLV:信号质量、注意力、冥想值
校验通过后,packet[1:] 才是真正的 payload,因为 packet[0] 是 plen。TLV 的读法是:先读一个字节 code,如果 code 不是 0x80,再读一个字节 length,然后取 value = payload[i:i+length]。材料里认了三个指标:code == 0x02 取 signal,code == 0x04 取 attention,code == 0x05 取 meditation。这里要特别注意,0x02 在普通 TLV 里是信号质量,但在 0x80 子码 0x02 下是 RAW Wave,两个不是一回事,所以解析顺序必须先判断 0x80。
python复制def parse_packet(self, payload):
res = {}
raws = []
i = 0
while i < len(payload):
code = payload[i]
i += 1
if code == 0x80:
# RAW Wave 分支,后面单独讲
break
if i >= len(payload):
break
length = payload[i]
i += 1
value = payload[i:i + length]
i += length
if len(value) < length:
continue
if code == 0x02:
res['signal'] = int(value[0])
elif code == 0x04:
res['attention'] = int(value[0])
elif code == 0x05:
res['meditation'] = int(value[0])
return res
这段代码的边界检查是必须的:i >= len(payload) 防止读 length 时越界;len(value) < length 防止 value[0] 在空数组上抛异常。int(value[0]) 只取第一个字节,是因为材料里的这三个指标都是单字节值。如果固件把指标扩展成多字节,这里要按协议改,不能想当然地取 value[0]。实际排查时,如果发现 signal 偶尔缺失,先看 bad_packets 有没有涨,再看 payload 末尾是不是被截断。
3.4 RAW Wave 的两种打包方式:三字节解两点与两字节解一点
RAW Wave 是这套解析里最“玄学”的部分。材料给了一段自适应逻辑:进入 0x80 后读子码,如果是 0x02,取剩余字节 remaining = payload[i:];如果 len(remaining) % 3 == 0,按三字节解两点,否则按两字节解一点。三字节的公式是 raw1 = (a << 4) | (b >> 4),raw2 = ((b & 0x0F) << 8) | c;两字节的公式是 raw = remaining[j] | (remaining[j+1] << 8),如果 raw > 32767 就减 65536 做有符号补偿。
python复制if sub_code == 0x02:
remaining = payload[i:]
if len(remaining) % 3 == 0:
for j in range(0, len(remaining) - 2, 3):
a = remaining[j]
b = remaining[j + 1]
c = remaining[j + 2]
raw1 = (a << 4) | (b >> 4)
raw2 = ((b & 0x0F) << 8) | c
raws.extend([raw1, raw2])
else:
for j in range(0, len(remaining) - 1, 2):
raw = remaining[j] | (remaining[j + 1] << 8)
if raw > 32767:
raw -= 65536
raws.append(raw)
if raws:
res['raw'] = np.array(raws)
break
三字节解两点每 3 个字节出 2 个 12 位值,两字节解一点每 2 个字节出 1 个 16 位有符号值。len(remaining) % 3 == 0 只是材料里的自适应判断,不是协议绝对规则:如果固件实际用两字节模式,而剩余长度恰好是 3 的倍数,就会误进三字节分支,波形会出现周期性跳跃。材料也提醒了,不同固件的位拆分配置可能有差异,发现解出来的波形有周期性奇怪跳跃,优先查协议文档里的 RAW Wave Value 描述,以手里的实际固件版本为准。我一般会把这段解码抽成带 mode 参数的函数,先用抓到的原始字节跑测试,确认模式后再接实时流。
4. 功能库的调用与验证:把解析结果接到实时波形
4.1 最小可运行脚本:从 COM5 读 512 字节到输出 numpy 数组
功能库写完,先不要急着接绘图。最小验证脚本只做三件事:创建解析器、循环 read_packet()、把结果交给一个回调。回调里判断 raw 在不在,在就拿到 numpy 数组;判断 signal 在不在,就打印信号质量。这样即使绘图模块还没写,也能确认串口和协议层是通的。
python复制def on_result(result):
if 'raw' in result:
wave = result['raw']
# 把 wave 推给绘图模块,不要在这里做重绘
print('raw points', len(wave))
if 'signal' in result:
print('signal', result['signal'])
parser = TGAMParser(port='COM5', baudrate=57600, timeout=0.1)
try:
while True:
result = parser.read_packet()
if result:
on_result(result)
finally:
parser.close()
read_packet() 返回 None 时不要当成错误,它只表示这一轮没凑齐完整包,继续循环即可。on_result 里不要做 plt.plot 这种重操作,否则会把串口读取拖慢;我一般只把 wave 塞进队列或列表,由另一个刷新节奏去画。finally: parser.close() 是为了异常退出时释放串口,否则下次打开 COM5 会失敗,这是很常见的翻车点。
4.2 用日志和统计验证:坏包率、信号质量、波形幅值
接实时流之前,先让统计跑一段时间。parser.bad_packets 是校验失败计数,stats 里记成功包数和 RAW 点数。看三个东西:坏包率是不是稳定在很低水平;signal 是不是在合理范围内跳动;raw 数组长度是不是每次都是 2 的倍数(三字节解两点)或任意偶数/奇数(两字节解一点,取决于剩余长度)。如果坏包率持续上涨
