RedesignedRobot/kw330-obd-datastream

# KW330 OBD 数据访问 在 macOS、Linux 或 Windows 上读取 KONNWEI KW330（以及大多数 KONNWEI 手持系列）的实时 OBD-II 数据流，无需仅限 Windows 的软件，也无需第三方驱动。 KW330 是一款廉价的 OBD-II 手持诊断仪。其 USB 端口官方说明“仅用于固件更新”（通过仅限 Windows 的更新程序 `uplink.exe`），但该设备也暴露了一个普通的 USB CDC 串行端口，并且其设备上的“Print Data > Print Data Stream”功能会将整个实时数据流作为可读文本推送出来。因此，您只需使用几行 Python 代码，就可以在任何操作系统上记录和分析您的汽车数据。 我们研究该设备并在此构建了这个小型工具包。有两点最容易让人踩坑：供电方式，以及在触发前始终保持静默的串行端口。 ## TL;DR ``` pip install pyserial python3 scripts/find_port.py # confirm the device, get its port python3 scripts/capture.py # auto-detects; captures until Ctrl-C # 在 scanner 上：NORMAL mode > Print Data > Print Data Stream（点击一次） python3 scripts/structure.py kw330_capture_*.bin # raw to time-series JSON ``` 您将获得一个原始的 `.bin` 文件和一个结构化的 `*.json` 时间序列（基于车辆的“Time Since Engine Start”时钟按各个 PID 记录）。示例位于 `samples/` 中。 ## 陷阱 1：供电（“插在充电器上会亮，但连到我的 Mac 上没反应”） KW330 的 USB-C 端口缺少强制要求的 CC 电阻，因此它不是符合规范的 USB-C 设备；它本质上是一个披着 USB-C 外壳的传统端口。 | 连接方式 | 结果 | 原因 | |---|---|---| | 壁充或 USB-A 转 C 线缆 | 成功开机 | USB-A VBUS 始终供电；A-to-C 线缆提供了设备所缺少的 56k Rp 电阻 | | C-to-C 线缆连接到 Mac/笔记本电脑的 USB-C 端口 | 毫无反应 | 符合规范的主机在检测到接收端的 5.1k Rd 电阻前会切断 VBUS 供电，而该设备根本没有此电阻 | | 通过带独立电源的 USB 集线器 | 正常工作 | 集线器的下行端口会无条件提供 VBUS 供电 | 解决办法：通过带独立电源（或总线供电）的 USB 集线器连接扫描仪，不要直接连接到 USB-C 端口。电气详情请参阅 [docs/how-it-works.md](docs/how-it-works.md#power)。 ## 陷阱 2：线缆（“能通电但在电脑上始终无法识别”） 设备通电只能证明 VBUS 接通了。您还需要一根真正的数据线；许多线缆仅支持充电（没有 D+/D- 数据线）。如果设备灯亮了但没有出现串行端口，请换一根您实际用来传输过文件的线缆。 ## 电脑识别到的设备 KW330 会作为标准的 USB CDC-ACM 串行设备被枚举，名为 `STM32 Virtual COM Port`，USB ID 为 `0483:5740`。所有现代操作系统都内置了驱动程序；无需额外安装。 | 操作系统 | 设备节点 | 内置驱动 | |---|---|---| | macOS (10.14+) | `/dev/cu.usbmodem*` | `com.apple.driver.usb.cdc.acm` | | Linux | `/dev/ttyACM0`（首选 `/dev/serial/by-id/usb-STMicroelectronics_*-if00`） | `cdc_acm` | | Windows 10/11 | `COMx` | 内置 `usbser.sys` | 该系列中一些较便宜的型号会使用 WCH CH340 桥接器（`1A86:7523`），它会显示为 `/dev/ttyUSB0`、`/dev/cu.wchusbserial*` 或 CH340 COM 端口，并且在 Windows 或较旧的 macOS 上可能需要 WCH 驱动程序。我们未确认基于 CH340 的 KW330；我们测试的设备使用的是 STM CDC。 各操作系统的具体步骤：[macOS](docs/macos.md)、[Linux](docs/linux.md)、[Windows](docs/windows.md)。 ## 获取数据 1. 使用数据线通过带电源的集线器连接（详见陷阱 1 和 2）。 2. 确认端口：`python3 scripts/find_port.py` 3. 在扫描仪上，处于 NORMAL 模式下，进入 Print Data > Print Data Stream。请勿选择 Clear/Erase；那会清除存储的故障码。 4. 开始捕获，然后触发数据流： python3 scripts/capture.py --seconds 0 # 0 = 直到按下 Ctrl-C 点击一次 Print Data Stream。它会连续循环传输数据流；重复点击会导致输出重叠和混乱。 5. 结构化解析：`python3 scripts/structure.py .bin` ### 数据流格式 这是一种采用 latin-1 编码（非纯 ASCII：`0xB0` 是度数符号）、CRLF 换行符的连续文本流，开头带有一个微小的二进制横幅。每一行的格式为 `Label`（标签），后跟两个或更多空格，然后是 `value`（值）： ``` Engine Coolant Temperature 85 °C Engine RPM 674/min Vehicle Speed 2km/h ``` `structure.py` 会解析这些内容。有一个值得注意的关键点：KW330 传输的是分页滚动数据。它会发送当前屏幕上显示的 PID 页面，因此不同的参数是在略微不同的瞬间（相差约 10 秒）采样的，单次采样很少能包含所有 PID。数据流中唯一的时钟是车辆的“Time Since Engine Start”（秒），脚本以此为基准。请阅读输出中的 `capture_meta.IMPORTANT_caveats`。更多信息请参阅 [docs/how-it-works.md](docs/how-it-works.md#the-print-data-stream-protocol)。 ## 这适用于我的型号吗？ “Print Data”菜单和 USB 串行功能存在于手持式扫描仪中，而非蓝牙/Wi-Fi 适配器。 - 支持 USB 串行和 Print Data 的型号：KW330、KW850、KW860、KW830、KW818、KW680、KW590、KW350、KW360、KW450、KW460、KW480、KW681、KW870、KW880、KW890、KW206 - 不支持 USB 连接电脑 / Print Data 的型号：KW208、KW510、KW808、KW320、KW310、KW309 - 蓝牙/Wi-Fi ELM327 适配器（仅限手机 App，不适用此方法）：KW902、KW903、KW905、KW912 菜单措辞各有不同：Print Data、Print Data Stream、Print Freeze Data、Print DTC、Print All。在某些型号上，打印菜单会将存储的数据推送到供应商的 `uplink` 应用程序；而在 KW330 上，我们看到的是真正实时、持续更新的数据流。 ## uplink.exe 是什么？ 它是供应商提供的 Windows 更新程序：一个 Inno Setup 6.1.0 安装程序（基于 Delphi），用于解压真正的更新程序以及 CH340/STM 串行驱动程序。它是 Windows 专用的，使用此方法读取数据完全不需要它。 ## 仓库结构 ``` scripts/ find_port.py, capture.py, structure.py docs/ how-it-works.md, macos.md, linux.md, windows.md samples/ raw_datastream_frame.txt, timeseries_example.json (VIN redacted) ``` ## 安全与法律声明 - 只读操作。本项目仅读取扫描仪已经打印出来的数据流；它不会向车辆写入任何内容。除非您确实打算清除存储的代码，否则切勿在设备上选择 Clear/Erase。 - 驾驶时请勿操作扫描仪。请作为乘客或在静止状态下进行捕获。 - OBD 数据流包含您的 VIN。此处的示例已作涂码处理；在分享前请为您自己的数据进行涂码。 - 与 KONNWEI 无任何隶属关系。名称仅用于识别硬件。基于 MIT 许可协议，不提供任何担保。 我们对设备进行了实际研究（macOS 端已端到端验证；Linux 和 Windows 的具体细节已与供应商及内核文档进行了核对），并在此构建了相关工具。文档编写有 AI 协助参与。欢迎提交修正和其他型号的反馈报告。

标签：OBD-II, Python, 无后门, 汽车诊断, 物联网, 硬件接口, 逆向工具