schappim/gm1356-recordings
GitHub: schappim/gm1356-recordings
纯 Python 实现的 Benetech GM1356 声级计跨平台驱动工具，支持实时读数和设备内置日志下载，并完整记录了此前未公开的 USB-HID 通信协议。
Stars: 0 | Forks: 0
# gm1356-recordings
读取**实时读数**，并且——这是其他地方很难找到的功能——在 **macOS 和 Linux** 上，使用纯 Python 从 **Benetech GM1356** USB 声级计中**下载内置记录的日志**。无需 Windows，无需 SoundLAB。
GM1356（VID `0x64BD` / PID `0x74E3`，采用 NATIONS N32G45x MCU）是一个 USB-**HID** 设备，而不是串口——因此不会显示为 `/dev/tty*`。我能找到的所有开源工具都只能进行*实时*读取。本仓库还实现了**记录导入协议 (record-import protocol)**，因此您可以提取声级计存储的数据日志，并且[**完整记录了底层通信协议**](PROTOCOL.md)，这样下一个人就不必再次对其进行逆向工程了。
## 安装
需要 `libhidapi`：
```
# macOS
brew install hidapi
# Debian/Ubuntu
sudo apt install libhidapi-hidraw0
```
无需任何 Python 包（纯 `ctypes` 实现）。要求 Python 3.8+。
```
git clone https://github.com/schappim/gm1356-recordings.git
cd gm1356-recordings
```
## 下载存储的记录
```
python3 download_recordings.py # -> recordings.csv
```
```
downloaded 2 recording(s), 5658 samples
recording 0: 16 samples @ 1s dBA 30-130dB
2026-06-21 07:40:13 -> 2026-06-21 07:40:28
min 33.2 mean 34.6 max 40.6 dB
recording 1: 5642 samples @ 6s dBA 30-130dB
2026-06-21 07:41:53 -> 2026-06-21 17:05:59
min 35.9 mean 46.9 max 77.4 dB
wrote 5658 rows -> recordings.csv
```
`recordings.csv` 的列包括：`recording, timestamp, db, weighting, range`。
对声级计的内存而言，它是**只读**的——擦除数据只能通过长按前面板上的按钮来实现，因此本工具不会清除您的日志。
## 实时读数
```
python3 read_meter.py # stream ~2/sec until Ctrl-C
python3 read_meter.py --once
python3 read_meter.py --csv live.csv # also log to CSV
python3 read_meter.py --slow --dbc --range 2 # configure first
```
```
2026-06-21T07:17:02.602+00:00 60.4 dBA fast range 30-130
```
## 作为库使用
```
from gm1356 import Meter
with Meter() as m:
print(m.capture()) # Reading(db=47.3, weighting='dBA', ...)
for rec in m.download(): # list[Recording]
for ts, db in rec.rows():
print(ts, db)
```
## 工作原理
请参阅 **[PROTOCOL.md](PROTOCOL.md)** 以获取完整的逆向工程协议：HID 帧结构、实时的 `0xB3`/`0x56` 命令、magic-id quirk，以及下载握手过程 —— `0xB5` 导入 → `0xEF` 标头 → `0xC4` 拉取循环 (pull-loop) → `0xFD` 块标头 + 12位压缩样本 (`dB = value / 20`)。
## 致谢
**下载/导入协议**源自
[**gymnasty/gm1356**](https://github.com/gymnasty/gm1356) (Go) —— 这是此前唯一的相关实现。本仓库是一个独立的、有文档记录的 Python 移植版本和硬件验证，并包含了协议的详细说明。
实时协议的逆向工程人员：pvachon, ciembor, dobra-noc, michris, classilla,
Troy Simpson (ebswift), Andy Reischle (areresearch)。
## 许可证
MIT —— 请参阅 [LICENSE](LICENSE)。
标签：Python, USB-HID, 协议文档, 命令控制, 数据采集, 无后门, 物联网, 硬件接口, 逆向工具