CH37x Python Tool for CH32H417 USB 3.0 Speed Testing

Open, cross-platform host tooling for WCH's CH32H417 USB 3.0 SuperSpeed CH372/CH37x-style speed-test example.

The original vendor package includes MCU firmware, a Chinese Windows endpoint tester, a Linux C demo, and a macOS Xcode sample. This repository keeps those examples for reference and adds a Python command-line tool for simple throughput testing today, with a path toward structured data exchange later.

What This Is

• A Python CLI named ch37x for listing devices and measuring bulk transfer speed.
• A direct libusb backend implemented with Python ctypes, so no Python USB package is required when libusb is installed.
• Optional PyUSB and experimental macOS WCH DriverKit backends.
• Documentation of the device descriptors and endpoint pairing found in the CH32H417 firmware.

What This Is Not

• It does not modify the embedded firmware.
• It is not tied to the vendor Windows GUI.
• It is not a full application protocol yet. The current focus is endpoint discovery, read speed, write speed, and loopback testing.

Device Summary

The SuperSpeed firmware exposes a vendor-specific USB device:

Item	Value
VID/PID	1a86:5537
Product string	WCH USB3.0 DEVICE
Bulk OUT endpoints	0x01, 0x02, 0x03
Bulk IN endpoints	0x81, 0x82, 0x83
SuperSpeed max packet size	1024 bytes
Burst level	16 packets per burst in the provided firmware

Known firmware paths:

Test	Host writes	Host reads	Notes
Loopback A	0x01	0x82	OUT endpoint 1 is forwarded to IN endpoint 2
Loopback B	0x02	0x81	OUT endpoint 2 is forwarded to IN endpoint 1
Independent speed	0x03	0x83	Useful for separate write/read testing

More detail is in docs/PROTOCOL.md.

Repository Layout

ch37x_tool/      Python CLI and USB backends
Common/          Shared CH32H417 USB descriptor and endpoint source
V3F/, V5F/       Original MounRiver firmware project folders
CH37X_LINUX/     Vendor Linux driver and C demo
CH37xUSBClient/  Vendor macOS Xcode sample
docs/            Protocol notes and troubleshooting

Generated MounRiver obj/ folders, local Xcode state, .DS_Store, and the packaged vendor Windows EXE/ZIP are intentionally ignored.

Install

1. Install libusb

macOS:

brew install libusb

Ubuntu/Debian:

sudo apt install libusb-1.0-0

Windows:

Install a libusb-compatible driver for the device interface, commonly WinUSB through Zadig, then run the Python tool from PowerShell or Windows Terminal.

2. Install the Python tool

From the repository root:

python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install -e .

On Windows PowerShell:

py -m venv .venv
.\.venv\Scripts\Activate.ps1
py -m pip install -e .

Quick Start

List the device and endpoints:

ch37x list

Run a read throughput test:

ch37x read --ep 0x83 --duration 5 --size 1048576

Run a write throughput test:

ch37x write --ep 0x03 --duration 5 --size 1048576

Run a loopback throughput test:

ch37x loopback --out 0x01 --in 0x82 --duration 5 --size 1048576

You can also run without installing the console script:

python3 -m ch37x_tool list

Full command details are in PYTHON_TOOL.md.

How It Works

The firmware enumerates as a vendor-specific USB device and exposes several bulk endpoints. The Python tool opens the matching VID/PID, claims the USB interface, then performs repeated bulk transfers for a fixed duration.

For read and write tests, the tool counts bytes transferred and reports:

• total bytes
• elapsed time
• MiB/s
• Mbit/s

For loopback tests, the tool writes a deterministic byte pattern to an OUT endpoint, reads from the paired IN endpoint, optionally verifies the payload, and reports combined throughput.

Backends

Backend	Use case
auto	Default. Uses the open libusb path for normal operation.
libusb	Recommended open backend for macOS, Linux, and Windows with a compatible driver.
pyusb	Optional PyUSB wrapper over libusb.
macos-driver	Experimental WCH DriverKit user-client path; may require signed entitlements.

Example:

ch37x --backend libusb list

Troubleshooting

If the device appears in macOS System Information but ch37x list does not see it, a driver may already own the interface or the current terminal environment may not be able to enumerate USB devices through libusb. See docs/TROUBLESHOOTING.md.

On Linux, permission errors are usually solved with a udev rule for VID/PID 1a86:5537.

On Windows, make sure the interface uses WinUSB/libusb-compatible binding rather than a vendor-only driver.

Development

Run the lightweight syntax check:

python3 -m compileall -q ch37x_tool

Show CLI help:

python3 -m ch37x_tool --help

Current Status

The Python tool is intended as a clean first host utility for throughput testing. The protocol surface is still intentionally small, but the code is organized so future commands can build on the same device discovery and bulk transfer layer.

Licensing Note

The vendor examples keep their original notices and restrictions. The newly written Python tool is separated in ch37x_tool/ so it can be licensed cleanly when you decide how you want to publish it.