ChargerLAB POWER-Z KM003C — USB protocol specification
Hazard observed on this unit (fw 1.9.5): never write while EP 0x81 still holds data
If the host sends the next request while a reply is still queued on bulk IN EP 0x81, the meter never answers. Its USB stack stalls and the watchdog reboots it; the device then re-enumerates. The queued item can be the zero-length packet (ZLP) that ends a MemoryRead, or any unread reply. Our client hit this once.
- After a MemoryRead: read the 20-byte
C4confirmation, then the data transfer, then the trailing ZLP, before writing again (§9.2). - After any timed-out or failed exchange: drain EP 0x81 with short reads until a read times out, then write the next request.
- Keep one request in flight at a time.
Evidence: a ZLP follows each MemoryRead data transfer in active_bulk_log.json (W6#1–W6#3, see testdata/fw1.9.5/INDEX.txt). The stall and reboot were observed by the team during a client run; no capture file exists for it.
This is a byte-level specification for a Go client of the ChargerLAB POWER-Z KM003C (USB 5FC9:0063). It was written from source code, two vendor PDFs, the vendor's C++ sample and the published notes of other projects. Results from whitelisted reads on the user's unit (firmware 1.9.5) were added afterwards, and are marked as such.
0. How to read this document
Evidence labels
Every claim carries one of these labels:
| Label | Meaning |
|---|---|
| [source] | Taken from program source code (a struct, constant, encoder or parser). A reference such as R packet.rs:9-54 gives the file and line range at the pinned commit listed in §15. |
| [vendor-doc] | Taken from a ChargerLAB PDF (page number given). |
| [notes] | Taken from a project's prose: firmware reverse-engineering notes, or "[device]" observations that another project reports from its own hardware. These are useful but are not source code. Each one says which firmware it was observed on. |
Firmware versions behind the sources
- R / RR (okhsunrog). The reverse-engineering notes cover firmware V1.9.9.
- O (nesquikm/open-powerz). Device observations are on firmware 2.0.6, with a few on 2.0.7.
- V1 (vendor API PDF). The example appears to come from an older firmware or a KM002C, because its ADC payload is 40 bytes rather than 44.
- The unit on this machine runs application firmware 1.9.5 (build date 2025.1.7). That is older than both reference sources: R covers 1.9.9 and O covers 2.0.6.
- Its 0x420 info block reports version "2.2" (2024.9.23). This is not the application firmware version.
- Serial 050002, USB
bcdDevice0x0100, HID report descriptor0600ff0901a1010902150025ff75089540810209039102c0, CDC port/dev/cu.usbmodem0500022. - Version evidence: MemoryRead of 0x4420 and 0x420 (bulk_W6_2_plain.hex, bulk_W6_1_plain.hex).
- Which observations come from this unit. Results probed on this unit appear only in the two "Verified on device" callouts (§6, §14), the hazard box at the top, and rows tagged device fw 1.9.5. Every other device observation comes from other people's KM003Cs running firmware 1.9.9 or 2.0.6.
- Firmware package format. R documents the
.mencryptupdate file:- ten big-endian Qt
QStringfields (format labels, model, version, build date, CRC32, plaintext size, Chinese and English release notes), followed by oneQByteArrayholding the encrypted image; - the image is AES-128-ECB with key0, the memory-read key;
- the normal updater always uses base address
0x4000.
- ten big-endian Qt
Source keys (full URLs and SHAs in §15)
| Key | Project |
|---|---|
| K | Linux drivers/hwmon/powerz.c |
| V1 | Vendor PDF KM002C&3C API Description |
| V2 | Vendor PDF Protocol Trigger by Virtual Serial Port |
| VS | Vendor C++ sample hiddemo.cpp from ChargerLAB's official "limited toolkit" zip. This is the only vendor-published code. |
| R | okhsunrog/km003c-rs, Rust library km003c-lib/src/ |
| RR | okhsunrog/km003c-protocol-research |
| O | nesquikm/open-powerz, crates/powerz-protocol/src/ and docs/protocol.md |
| I | inuchanbt/KM003C-CLI |
| N | nbuchwitz/usb-meter |
| C | chaseleif/km003c |
| L | LongDirtyAnimAlf/km003c (Pascal) |
| NV | nevetssf/powerz |
1. TL;DR for the Go client
Primary transport: IF0 vendor bulk, OUT endpoint
0x01, IN endpoint0x81.- The Linux kernel driver uses this interface source K powerz.c:17-18, 126-130, 264-268.
- On macOS, libusb can claim IF0 without detaching a driver notes O protocol.md:58-61.
Read the ADC once. Write the 4 bytes
0C <id> 02 00and read one bulk transfer. The reply is 52 bytes (48 on older firmware):41 <id> xx xx+01 00 00 0B+ a 44-byte payload.- The kernel driver sends exactly
0c 00 02 00with no CONNECT, no authentication and no reset source K powerz.c:121-130. - The vendor PDF shows the same request bytes vendor-doc V1 p.3. The vendor's own C++ sample sends them over HID with nothing before them source VS hiddemo.cpp:230-252.
- The kernel driver sends exactly
No handshake is needed for ADC or PD polling.
- ADC on bulk: the kernel driver sends no CONNECT source K powerz.c:110-150.
- PD on bulk: I polls
PD_PACKETover IF0 without CONNECT source I transport.py:228-283, km003c_cli.py:817, and its README reports a working USB PD capture on hardware notes I README.md:354. - SETTINGS: shown to work without CONNECT only on CDC notes O protocol.md:378-382, 777-778. Whether SETTINGS on bulk works without CONNECT is unverified; send CONNECT first if it fails.
Authentication (0x4C, AES) only matters for:
- streaming control, which is AdcQueue start/stop and the PD sniffer;
- TICK and the offline-record list;
- writes.
CONNECT (0x02) is only needed on bulk, before a MemoryRead, which is how the device-info blocks are read (§9).
HID (IF3, interrupt endpoints
0x05/0x85) is ADC-only. Send exactly one request,0C <id> 02 00, zero-padded to 64 bytes.- A reply longer than 64 bytes hangs the firmware, and the watchdog reboots the meter 1.5–3.5 s later notes O protocol.md:741-769, firmware 2.0.6.
- The O library's HID transport refuses every other request source O transport/hid.rs:49-63.
Avoid CDC (IF2) for the binary protocol. On CDC:
- bytes
0x01,0x02and0x03start, keep alive and stop the vendor "ADCNEW" stream; - the same byte stream carries the ASCII "PDM" trigger commands, which change VBUS.
The CDC trigger-command list is in vendor-doc V2 p.1-2 and notes O protocol.md:771-970. The rule that CDC refuses frame types 0x01–0x03 is in source O transport/cdc_frame.rs:30-36.
- bytes
Never send these frame types:
0x04,0x08,0x09,0x0A,0x42,0x48,0x4A,0x4B,0x4D(§12). They are taken from:- the O command guard source O transport/guard.rs:18-27;
- the R/RR firmware notes notes RR docs/firmware/handlers.md:18-37.
2. USB identity and transports
| Item | Value | Evidence |
|---|---|---|
| VID:PID | 5FC9:0063 (KM003C); 5FC9:0061 is the KM002C |
source K powerz.c:264-268, source R device.rs:140-141 |
| Kernel binding | USB_DEVICE_INTERFACE_NUMBER(0x5FC9, 0x0063, 0x00): the hwmon driver binds interface 0 only |
source K powerz.c:264-268 |
| Device class | 0xEF/0x02/0x01 (IAD composite), USB 2.10, full speed, EP0 maximum packet 32 | notes O protocol.md:36, notes RR usb_transport.md:9-17 |
| Interface string of IF0 | APP in application mode; a BOOT or DFU string means bootloader |
notes O protocol.md:38, 530 |
Interfaces and endpoints
The endpoint addresses agree across sources: source R device.rs:143-151, source I transport.py:115,123, notes O protocol.md:45-50, notes RR usb_transport.md:116-126.
| IF | Class | Endpoints | Carries |
|---|---|---|---|
| 0 | 0xFF vendor | bulk OUT 0x01, bulk IN 0x81 (64 B packets) |
The full binary protocol. Every documented feature works here. |
| 1 | 0x02/0x02 CDC ACM | interrupt IN 0x83 (8 B, 10 ms) |
CDC notifications only |
| 2 | 0x0A CDC data | bulk OUT 0x02, bulk IN 0x82 |
One shared byte stream with three uses: the binary protocol (GET_DATA works), the ADCNEW push stream and the ASCII PDM trigger commands. macOS exposes it as /dev/cu.usbmodem*. |
| 3 | 0x03 HID, usage page 0xFF00 | interrupt OUT 0x05, IN 0x85 (64 B, 1 ms) |
One 64-byte input report and one 64-byte output report, no report ID. Only the ADC snapshot is safe here. |
Source C's endpoint map does not match the KM003C layout. source C record.py:59-64 pairs IF1 with
0x05/0x85and IF3 with0x03/0x83. That disagrees with R, I, O and RR. Interface numbering reportedly differs between models (the KM002C is said to put HID at IF1) notes O protocol.md:52-54.Select interfaces by class (0xFF vendor, 0x03 HID, 0x0A CDC data), not by number, and read the endpoint addresses from the configuration descriptor.
Vendor statement about transports
vendor-doc V1 p.1 says there are three interfaces, and that the same commands work on all of them:
| Interface | Stated throughput |
|---|---|
| WinUSB / "USB USER" | 200 KB/s |
| CDC (baud rate is ignored) | 200 KB/s |
| HID (data limited to 64 bytes) | 60 KB/s |
On the extended-header size field, the two vendor sources disagree:
- The PDF says it must not exceed 1024−8 bytes,
chunk*sizemust not exceed 4080, and the HID interface must not exceed 60 vendor-doc V1 p.1. - The vendor sample code says "must not exceed 4095−8 bytes; CDC and HID less than 64 bytes" (
不能超过4095-8个字节 CDC HID 小于 64字节) source VS hiddemo.cpp:91.
Device observations on firmware 2.0.6 show that "same commands everywhere" is only partly true notes O protocol.md:55-57, 741-783. On CDC, a 188-byte SETTINGS reply was observed to work, contrary to the VS comment (§14 C21).
Vendor endpoint selection. The VS demo enables libusb_set_auto_detach_kernel_driver, claims every interface, and picks endpoints by transfer type: the first interrupt IN/OUT is "hid", and the first bulk IN/OUT is "user" (IF0, which comes before the CDC bulk pair) source VS hiddemo.cpp:133-224.
Transport framing rules
Bulk (IF0)
- One request is one OUT transfer.
- One response is one IN transfer, delimited by a short packet.
- R reads into a 2048-byte buffer and joins transfers until a short packet source R device.rs:155, 718-741. I reads with a 65536-byte buffer source I transport.py:121-127.
- The vendor app sends a zero-length packet after any OUT write whose length is a non-zero multiple of 64 notes O protocol.md:62-64; source O transport/bulk.rs:19-23. Requests in the safe set are 4 or 36 bytes, so this never applies to them.
Stale data at open (bulk)
A stale DISCONNECT (03 xx 00 00) often waits on EP 0x81 when the device is opened. Drain the IN endpoint with short reads until one times out source O transport/bulk.rs:25-36, notes O protocol.md:142, 709.
HID (IF3)
- Output report: 64 bytes, request zero-padded. Through hidapi you write 65 bytes, where byte 0 is report ID
0x00. That leading 0x00 is a hidapi convention and is not sent on the wire source O transport/hid.rs:66-73, source I transport.py:43-50, source NV constants.py:29. - Input report: 64 bytes, response zero-padded, no report-ID byte notes O protocol.md:743-745.
- Linux hidraw: N writes the bare 4-byte request to
/dev/hidraw*and reads 64 bytes source N connection.py:143-152, meter.py:191-193.
CDC (IF2)
- Bytes are written to the tty. The baud rate is ignored vendor-doc V1 p.1. The vendor tools use 2 000 000 8N1 notes O protocol.md:774-775.
- Replies, ADCNEW frames and PDM text lines can be interleaved on the same stream. Demultiplex by header and id notes O protocol.md:820-828, source I transport.py:243-266.
3. Packet headers
Every frame begins with one 4-byte little-endian u32. Bit 0 is the least significant bit of byte 0. The same word is read in one of three views.
3.1 Control view (requests and control replies)
bit: 31 17 16 15 8 7 6 0
+----------------------------+--+---------------+-+-------------+
| att (15 bits) |e | id (8 bits) |x| type (7) |
+----------------------------+--+---------------+-+-------------+
byte: [3]..............[2]bit1 [2]b0 [1] [0]b7 [0]b0..6
| Bits | Field | Meaning | Evidence |
|---|---|---|---|
| 0–6 | type | Message type. Values below 0x40 are control; 0x40 and above are data. | vendor-doc V1 p.1 type:7 "大于63为数据" (values above 63 are data); source R packet.rs:9-20; source O frame.rs:205-214 |
| 7 | extend / reserved | 0 in requests. V1 says it is "used to transmit very large packets". It is set on the MemoryRead confirmation C4. |
vendor-doc V1 p.1; source R packet.rs:13-15; notes O protocol.md:80, 97 |
| 8–15 | id | Transaction id. The PDF says "default 0"; the VS comment says "keeps incrementing". The VS demo never sets it, so it always sends 0. | vendor-doc V1 p.1 ("id 默认0"); source VS hiddemo.cpp:72, 235-237 ("id 不停的累加"); source R packet.rs:16 |
| 16 | enc | V1 says "data is in encrypted format". 0 in every request. | vendor-doc V1 p.1; source O frame.rs:211 |
| 17–31 | att | Attribute mask or argument (15 bits) | vendor-doc V1 p.1; source R packet.rs:19; source K powerz.c:121-124 |
Encoding. word = type | id<<8 | att<<17, then write it little-endian.
The same formula appears in three sources: source N protocol.py:90, source I protocol.py:62-65, source O frame.rs:240-245.
Because att starts at bit 17, the att value shows up doubled in byte 2:
- att 1 encodes as
02 00; - att 0x10 encodes as
20 00; - att 0x200 encodes as
00 04.
The ADC request built this way is 0C 00 02 00 in four places: source K powerz.c:121-124, vendor-doc V1 p.3, source R tests/adc_tests.rs:74-90, source C record.py:11.
3.2 Data view (PUT_DATA and other data-type frames)
| Bits | Field | Meaning | Evidence |
|---|---|---|---|
| 0–6 | type | 0x41 = PUT_DATA | vendor-doc V1 p.2; source R packet.rs:22-35 |
| 7 | extend | 0 on PUT_DATA | notes O protocol.md:97 |
| 8–15 | id | Echo of the request id (exceptions below) | source R device.rs:167-169, 842-846; notes O protocol.md:98 |
| 16 | encode | 1 means the payload is AES-encrypted. It is 0 on PUT_DATA, and 1 on the MemoryRead confirmation and the auth reply. | source VS hiddemo.cpp:81 (encode : 1); vendor-doc V1 p.1; source R memory.rs:162-167; source O frame.rs:217-227 |
| 17–18 | permi | The session's auth level (0, 1 or 2) | source VS hiddemo.cpp:82 (permi : 2, so the field exists in vendor code); source O frame.rs:224; semantics notes O protocol.md:100, 109-111. R treats bits 16–21 as unused source R packet.rs:33. |
| 19–21 | reserved | source VS hiddemo.cpp:83; notes O protocol.md:101 | |
| 22–31 | obj | Opaque. Do not frame by it. Conflicting meanings are listed in §14. | source VS hiddemo.cpp:84; vendor-doc V1 p.1 ("4 bytes per object"); source R message.rs:416-423; notes O protocol.md:104-108 |
3.3 Extended (section) header
Each logical section inside a PUT_DATA starts with its own 4-byte header.
bit: 31 22 21 16 15 14 0
+-------------+---------+--+----------------------------+
| size (10) |chunk (6)|nx| att (15 bits) |
+-------------+---------+--+----------------------------+
| Bits | Field | Meaning |
|---|---|---|
| 0–14 | att | The single attribute bit this section answers |
| 15 | next | 1 means another section follows |
| 16–21 | chunk | Record count for ADC_QUEUE, so at most 63 records per reply |
| 22–31 | size | Payload bytes. For ADC_QUEUE this is the record size (20). |
The layout is the same in vendor-doc V1 p.1, source R packet.rs:47-54, source O frame.rs:278-306, source I protocol.py:100-122 and source N protocol.py:113-129.
Section payload length:
- ADC_QUEUE:
chunk * sizesource O frame.rs:296-304, source R packet.rs:491-501. - PD_STATUS (0x020) and RECORD_LIST (0x200): the size field is 0 or unusable, so the payload is the rest of the frame source O frame.rs:379-393. R derives the 0x020 boundary from queue prefixes instead source R packet.rs:492-493.
- Every other attribute:
size.
Section order. Sections arrive in ascending attribute-bit order. An attribute that is gated, or has nothing to report, is left out notes O protocol.md:128-130. An empty PUT_DATA is a bare 4-byte header such as 41 id 00 00. Bits 17–18 may be non-zero in it, as in 41 id 02 00 source R packet.rs:448-456, notes O protocol.md:196-198, 737.
Worked decode of a section header.
01 00 00 0Bis the LE word 0x0B000001.- att = 0x0B000001 & 0x7FFF = 1 (ADC).
- next = (word >> 15) & 1 = 0.
- size = 0x0B000001 >> 22 = 44.
source R tests/adc_tests.rs:12-26; source O tests/vectors/adc_52.hex.
4. Message types and safety classification
Classes used in the tables:
| Class | Meaning |
|---|---|
| SAFE-READ | No device-side state change |
| READ-CONSUMES | Read-only, but drains a device-side FIFO. Another consumer would lose that data. |
| SESSION | Changes only volatile session state (connect, auth level) |
| MODE | Starts or stops a volatile runtime mode (a stream or sniffer). Reversible, not persisted. |
| UNSAFE-WRITE | Persistent settings, calibration, flash or record changes |
| UNSAFE-POWER | Changes VBUS or the charger negotiation |
| UNSAFE-BOOT | Reset, bootloader, DFU or firmware erase |
| AVOID | Purpose unknown or not needed |
Names come from vendor-doc V1 p.2 (cmd_ctrl_msg_type, cmd_data_msg_type), source R packet.rs:59-94 and source O frame.rs:12-26. Semantics come from the cited notes.
| Type | Name | Request bytes | Reply | Class | Evidence and notes |
|---|---|---|---|---|---|
| 0x01 | SYNC | — | — | AVOID | Bulk: per-chunk acknowledgement during firmware download. CDC: ADCNEW keep-alive. notes O protocol.md:140, 789 |
| 0x02 | CONNECT | 02 id 00 00 |
05 id 00 00 (ACCEPT) |
SESSION (bulk only) | Required before MemoryRead or auth on bulk (firmware 2.0.6). No reply over HID. On CDC it starts an ADCNEW stream. notes O protocol.md:141, 477-484, 779-781. R retries up to 3 times because the device sometimes answers DISCONNECT first source R device.rs:975-996. The ADC read does not need it source K powerz.c:110-150. |
| 0x03 | DISCONNECT | 03 id 00 00 |
ACCEPT | SESSION | May arrive in place of PUT_DATA, meaning "no data", or stale at open. CDC: stops ADCNEW. notes O protocol.md:142, 735, 791 |
| 0x04 | RESET | — | — | UNSAFE-BOOT | vendor-doc V1 p.2; never sent source O transport/guard.rs:18-22 |
| 0x05 | ACCEPT | reply only | — | vendor-doc V1 p.2 | |
| 0x06 | REJECT | reply only | — | Sent when the auth level is too low, a stream is already started, or MemoryRead comes before CONNECT notes O protocol.md:734; also when MemoryRead validation fails notes RR handlers.md:183-200 | |
| 0x07 | FINISHED | reply only | — | Answer to settings and record writes notes O protocol.md:146; notes RR handlers.md:132-133 | |
| 0x08 | JUMP_APROM | — | — | UNSAFE-BOOT | Leaves DFU vendor-doc V1 p.2; notes O protocol.md:147 |
| 0x09 | JUMP_DFU | — | — | UNSAFE-BOOT | Enters firmware-update mode notes O protocol.md:148 |
| 0x0A | "GET_STATUS" (V1 name) | — | FINISHED | UNSAFE-WRITE | Misnamed. It is a settings-write message. Its keys include 0x08 = factory reset (erases settings and records). It works over CDC with no auth, and is ignored over bulk. notes O protocol.md:149, 366-436; forbidden source O transport/guard.rs:22 |
| 0x0B | ERROR | — | AVOID | vendor-doc V1 p.2 | |
| 0x0C | GET_DATA | 0C id <att*2 LE16> |
PUT_DATA 0x41 | Depends on the attribute (§5) | vendor-doc V1 p.2-3; source R message.rs:436-443 |
| 0x0D | GET_FILE | — | AVOID | Unused by the vendor app notes O protocol.md:152; firmware handler exists notes RR handlers.md:28 | |
| 0x0E | START_GRAPH (AdcQueue start) | 0E id <rate*2> 00; rate 0=2, 1=10, 2=50, 3=1000 SPS |
ACCEPT / REJECT | MODE | Needs auth level ≥1. On firmware 2.0.6 it is REJECTed at L0 and while a stream is already running. source R message.rs:444-451, adcqueue.rs:24-32; notes O protocol.md:153, 252-279; notes RR protocol_reference.md:200-223 |
| 0x0F | STOP_GRAPH | 0F id 00 00 |
ACCEPT / REJECT | MODE | REJECTed at L0 on firmware 2.0.6 notes O protocol.md:154 |
| 0x10 | ENABLE_PD_MONITOR (sniffer start) | 10 id 02 00 (att 1 = PD; O says 2..5 = UFCS) |
ACCEPT / REJECT | MODE | REJECTed at L0 on firmware 2.0.6. PD polling works without it. source R message.rs:17, 500-507; notes O protocol.md:155, 972-988 |
| 0x11 | DISABLE_PD_MONITOR | 11 id 00 00 |
ACCEPT / REJECT | MODE | source R message.rs:508-515 |
| 0x27 | NOT_READABLE | reply only | — | MemoryRead hit a bus fault source R packet.rs:86-87; notes RR handlers.md:202-209 | |
| 0x40 | HEAD | 40 id 00 01 + 16 zero bytes |
Type 0x40, id 0 | AVOID | O's static analysis says it is read-only. It is also part of the firmware-flash flow. notes O protocol.md:162, 533-534 |
| 0x41 | PUT_DATA | reply only | — | vendor-doc V1 p.2 | |
| 0x42 | firmware descriptor | 42 id 00 04 + 64 B |
UNSAFE-BOOT | Starts an erase notes O protocol.md:164; forbidden source O guard.rs:22 | |
| 0x44 | MEMORY_READ | 44 id 01 01 + 32 B AES |
C4 id 01 01 + 16 B, then raw ciphertext |
SAFE-READ, restricted | Allowed only at the 4 known addresses, on bulk, after CONNECT (§9). Other addresses reportedly crash the meter notes O protocol.md:520-521, 1241. |
| 0x48 | SET_DATA / settings batch | varies | FINISHED | UNSAFE-WRITE | Nested operations include 0x08 reset system and 0x09 reset both settings blocks, and need no auth notes RR handlers.md:117-170; forbidden source O guard.rs:22 |
| 0x4A | flash / memory write | encrypted | UNSAFE-WRITE | Needs auth L≥1 notes RR handlers.md:33, 104-105; forbidden source O guard.rs:22 | |
| 0x4B | offset memory read (0x98000000 + addr) | ? | AVOID | Framing unconfirmed notes RR handlers.md:34, 356-367 | |
| 0x4C | STREAMING_AUTH | 4C id 00 02 + 32 B AES |
4C 00 <lvl word> + 32 B |
SESSION | Raises the auth level, which unlocks privileged writes as a side effect. Not needed for basic reads (§10). |
| 0x4D | privileged settings batch | UNSAFE-WRITE | Needs L2 and writes calibration notes RR handlers.md:36, 117-150 |
5. GET_DATA attributes
Request: 0C id b2 b3, where (b3<<8 | b2) = mask << 1. Several bits can be OR-ed together; the reply then holds one section per attribute, chained by next. vendor-doc V1 p.2; source R packet.rs:151-170; notes O protocol.md:175-191
Read the "Auth (FW 1.9.9 / 2.0.6)" column as "minimum auth level on 1.9.9 / minimum auth level on 2.0.6".
| Mask | Name (vendor / R / O) | Request (id=0) | Reply section | Auth (FW 1.9.9 / 2.0.6) | Class and transport |
|---|---|---|---|---|---|
| 0x001 | ATT_ADC / Adc / ADC | 0C 00 02 00 |
44 B (40 B on older firmware) | 0 / 0 | SAFE-READ. Bulk, HID, CDC. |
| 0x002 | ATT_ADC_QUEUE / AdcQueue / ADC_QUEUE | 0C 00 04 00 |
chunk × 20 B records |
1 / 0 (conflict) | READ-CONSUMES. Bulk and CDC; never HID. |
| 0x004 | ATT_ADC_QUEUE_10K | 0C 00 08 00 |
Always empty | — | AVOID |
| 0x008 | ATT_SETTINGS / Settings / SETTINGS | 0C 00 10 00 |
180 B | 0 / 0 | SAFE-READ. Bulk and CDC (188 B reply); never HID. |
| 0x010 | ATT_PD_PACKET / PdPacket / PD_PACKET | 0C 00 20 00 |
12 B status plus event records | 0 / 0 | READ-CONSUMES (PD event FIFO). Bulk and CDC; HID is not safe. |
| 0x011 | ADC + PD_PACKET | 0C 00 22 00 |
44 + 12+ B (68 B total when idle) | 0 / 0 | Bulk and CDC only. 68 B reply reboots the meter over HID notes O protocol.md:757-760. |
| 0x020 | ATT_PD_STATUS / PdTrace / PD_STATUS | 0C 00 40 00 |
Size field = 0; rest of frame | 1 / 0 | READ-CONSUMES (trace queues). Bulk and CDC. |
| 0x040 | ATT_QC_PACKET / UFCS trace / QC_PACKET | 0C 00 80 00 |
12 B status plus UFCS records | 1 / 0 | READ-CONSUMES. Bulk and CDC. |
| 0x080 | TICK | 0C 00 00 01 |
8 B: u32 uptime ms + u32 0 | ? / 1 (empty at 0) | SAFE-READ |
| 0x100 | TICK2 | 0C 00 00 02 |
Always empty | — | AVOID |
| 0x200 | LogMetadata / RecordList | 0C 00 00 04 |
N × 48 B | 1 / 1 (empty at 0) | SAFE-READ |
| 0x400 | PDList | 0C 00 00 08 |
Always empty | — | AVOID |
Where each row comes from:
- Names: vendor names vendor-doc V1 p.2, plus
ATT_TICK = 0x080andATT_TICK__ = 0x100in the vendor sample source VS hiddemo.cpp:38-50; R names source R packet.rs:151-170; O names and the 0x080–0x400 rows notes O protocol.md:179-191; L constants source L km003c.pas:297-305. - The 1.9.9 gating: firmware decompilation shows
attribute_mask &= 0x19at auth level 0, which keeps only ADC, SETTINGS and PD_PACKET notes RR handlers.md:110-113, 254-270. - The 2.0.6 gating: device observations notes O protocol.md:181-206.
- HID PD reports: I found that "HID PD-only requests did not respond on the tested unit" notes I README.md:354. NV sends
0C 00 20 00over HID by default source NV constants.py:15-18,66; device/reader.py:41. R calls HID "ADC/PD polling" mode source R device.rs:196-224. Treat PD over HID as unsafe (§14 C8).
6. ADC snapshot (attribute 0x001)
Verified on device: the user's KM003C (application firmware 1.9.5, serial 050002)
These results come from whitelisted reads on 2026-11-16. Each row is verified (fw 1.9.5), pending or not probed. Evidence links point to the raw frames in hardware/km003c/testdata/fw1.9.5/; request ids 1–14 were on bulk, 15–17 on HID and 18–20 on CDC.
| Item | Spec says | Verified on device | Evidence (capture / date) |
|---|---|---|---|
| Firmware version (MemoryRead 0x4420, +0x1C) | Unknown (§9, C20) | verified (fw 1.9.5) Model KM003C, version 1.9.5, date 2025.1.7, u32@0 = 0x00004000. The 0x420 block reads KM003C / 2.2 / 2024.9.23. | bulk_W6_2_plain.hex, bulk_W6_1_plain.hex (2026-11-16) |
| ADC request over bulk IF0 | 0C id 02 00, no CONNECT or auth (§6.5) | verified (fw 1.9.5) Answered with no prior CONNECT or auth, 5 of 5. Latency 0.54–0.74 ms. | bulk_W1_1_req.hex, bulk_W1_1_resp.hex … bulk_W1_5_resp.hex |
| Reply length and section header | 52 B; 01 00 00 0B (size 44), or 48 B with size 40 | verified (fw 1.9.5) 52 B: 41 id 80 02 + 01 00 00 0B + a 44-byte payload. | bulk_W1_1_resp.hex |
| Reply id echo | Echoed (C6) | verified (fw 1.9.5) The request id was echoed on 20 of 20 requests across bulk, HID and CDC. | INDEX.txt (echo column) |
| Header bytes 2–3 (obj, permi) | Opaque; permi = auth level (C5) | verified (fw 1.9.5) permi = 0 without auth. obj = len/4 − 3 held for all four reply sizes: 20 B gave obj 2 (80 00), 52 B gave 10 (80 02), 68 B gave 14 (80 03), 188 B gave 44 (00 0B). Still frame by section headers. | bulk_W3_1_resp.hex, bulk_W1_1_resp.hex, bulk_W4_1_resp.hex, bulk_W2_1_resp.hex |
| Payload 0x00–0x23 scaling | µV, µA, °C = raw/128, 0.1 mV (§6.2) | verified (fw 1.9.5) Matches the meter's screen. Idle example: VBUS 5.173 mV, IBUS −28 µA, temperature raw 3366 = 26.30 °C, CC1 68.2 mV, CC2 27.8 mV, D+ 86.5 mV, D− 90.6 mV, VDD 3.206 V. | bulk_W1_1_resp.hex |
| Tail 0x24–0x2B and rate byte | Firmware-dependent; rate at 0x24 or 0x26 (C1, C2) | verified (fw 1.9.5) Tail = 00 80 1A 00 55 00 5A 00.
| bulk_W1_1_resp.hex … _5, bulk_W2_1_resp.hex (SETTINGS) |
| IBUS sign vs. power-flow direction | Conflicting (C3) | pending Only about 0 A was measured (±tens of µA of noise), so the sign convention is still open. | — |
| Same ADC request over HID IF3 | One 64-byte report, ADC only (§6.5) | verified (fw 1.9.5) 64 B: the 52-byte frame plus 12 zero bytes. 2.23–2.41 ms, no reboot. | hid_W1_1_req.hex (65 B hidapi buffer; the leading 00 is not on the wire), hid_W1_1_resp.hex … _3 |
| Same ADC request over CDC IF2 | Works; avoid other frames (§6.5, §11) | verified (fw 1.9.5) Exactly 52 B, 0.25–0.29 ms. | cdc_W1_1_resp.hex … _3 |
| SETTINGS over bulk without CONNECT | Unverified on bulk (§1, W2) | verified (fw 1.9.5) 188 B, sent before any CONNECT. Both CRC-32s verify. u32@0x60 = 0x4A (rate code 2, rotation 2). Name POWER-Z. | bulk_W2_1_resp.hex |
| PD_PACKET (0x10) and ADC+PD (0x11) | 12-byte status, plus records (§7) | verified (fw 1.9.5)
| bulk_W3_1_resp.hex … _3, bulk_W4_1_resp.hex |
| CONNECT and MemoryRead (bulk) | CONNECT then 44 id 01 01 + AES; no auth (§9.2) | verified (fw 1.9.5)
| bulk_W5_1_resp.hex, bulk_W6_1_req.hex, bulk_W6_1_resp.hex, bulk_W6_1_respdata.hex (and W6_2, W6_3) |
| Stale data on EP 0x81 at open | Often a stale 03 xx 00 00 (§2) | verified (fw 1.9.5) Nothing was stale at open in this run (the drain read 0 transfers). Draining is still required after failures: see the hazard box at the top. | INDEX.txt (drain note) |
6.1 Response frame
| Packet offset | Size | Content |
|---|---|---|
| 0 | 4 | Main header: 41 id xx xx (type 0x41; bytes 2–3 opaque) |
| 4 | 4 | Section header: 01 00 00 0B (att 1, next 0, chunk 0, size 44). Older firmware: 01 00 00 0A (size 40). |
| 8 | 44 (or 40) | ADC payload (6.2) |
- Total length is 52 bytes, or 48 on older firmware.
- K treats packet bytes 0–7 as
_unknown_1[8]and requiresactual_length >= 48source K powerz.c:20-34, 146-147. - The 40-byte form comes from vendor-doc V1 p.3 (
01 00 00 0A).
6.2 Payload layout
Offsets are relative to the payload start, which is packet offset 8. All values are little-endian.
Columns: Off is the payload offset and Pkt is the offset inside the full packet.
| Off | Pkt | Type | Field | Unit and scale | Agreement |
|---|---|---|---|---|---|
| 0x00 | 8 | i32 | VBUS | µV; V = raw/1e6 | All sources: source K powerz.c:22, 181 (/1000 gives mV); vendor-doc V1 p.3 ("单位1uV", unit 1 µV); source R adc.rs:72, 142; source O decode/adc.rs:43,60-62; source N meter.py:65,69; source I protocol.py:175 |
| 0x04 | 12 | i32 | IBUS, signed | µA; A = raw/1e6 | All sources: source K powerz.c:23, 173 (s32); vendor-doc V1 p.3; source R adc.rs:73. The sign convention conflicts (§14 C3). |
| 0x08 | 16 | i32 | VBUS average (smoothed) | µV | source K powerz.c:24,195; vendor-doc V1 p.3 ("平滑滤波后的平均电压", smoothed average voltage); source R adc.rs:74 |
| 0x0C | 20 | i32 | IBUS average (smoothed) | µA | source K powerz.c:25,175; vendor-doc V1 p.3; source R adc.rs:75 |
| 0x10 | 24 | i32 | VBUS average, uncalibrated | Raw. µV per source O decode/adc.rs:47 | vendor-doc V1 p.3 ("未校准", uncalibrated); source R adc.rs:76 ("Uncalibrated"); K skips it (_unknown_2) |
| 0x14 | 28 | i32 | IBUS average, uncalibrated | Raw / µA | Same sources as 0x10 |
| 0x18 | 32 | i16 | Temperature | °C = raw/128. 0x8000 = invalid. |
source R adc.rs:78-79, 155 (raw/128); source O decode/adc.rs:12, 49, 90-92 (adds the 0x8000 sentinel); source K powerz.c:27, 200 computes m°C = b[1]*2000 + b[0]*1000/128, which equals raw/128 only when raw ≥ 0; vendor-doc V1 p.3 (int16_t Temp, unit not stated) |
| 0x1A | 34 | u16 | CC1 voltage | 0.1 mV; V = raw/10000 | source K powerz.c:28,183 (/10 gives mV); vendor-doc V1 p.3 ("分辨率0.1mV", 0.1 mV resolution); source R adc.rs:80,160; source O decode/adc.rs:50,95-97 |
| 0x1C | 36 | u16 | CC2 voltage | 0.1 mV | Same sources as 0x1A |
| 0x1E | 38 | u16 | D+ voltage | 0.1 mV | Same sources as 0x1A |
| 0x20 | 40 | u16 | D− voltage | 0.1 mV | Same sources as 0x1A |
| 0x22 | 42 | u16 | Internal VDD | 0.1 mV (about 3.2 V seen) | source K powerz.c:32,191; vendor-doc V1 p.3 ("内部VDD电压", internal VDD voltage); source R adc.rs:84 |
| 0x24–0x2B | 44–51 | — | Tail: layout depends on firmware | — | See 6.3 |
Notes:
- Power is computed on the host as
V × I(signed) source R adc.rs:150; notes O protocol.md:239. - The temperature reads
0x8000(invalid) while the queue runs at 1000 SPS notes O protocol.md:224.
6.3 Tail bytes 0x24–0x2B: unresolved, decode as raw
Each source reads the tail differently:
| Source | 0x24 | 0x25 | 0x26–0x27 | 0x28–0x29 | 0x2A–0x2B |
|---|---|---|---|---|---|
| vendor-doc V1 p.3 (40-byte form) | uint8 Rate:2 (low 2 bits) |
n[3], continuing through 0x27 |
(0x26–0x27 are part of n[3]) |
— | — |
| source R adc.rs:85-89 (firmware 1.9.9 notes) | u8 sample-rate index (0=2, 1=10, 2=50, 3=1k, 4=10k SPS) | u8 "vendor flags" (128 seen) | u16 CC2 average, 1 mV | u16 D+ average, 1 mV | u16 D− average, 1 mV |
| source O decode/adc.rs:10, 55; notes O protocol.md:230-234 (firmware 2.0.6) | i16 second temperature (0x8000 = invalid), across 0x24–0x25 |
(part of the i16) | u8 at 0x26 = queue rate code 0..3; u8 at 0x27 unknown (0xF0) | u16 battery level ×10 | u16 unknown (0x00FF) |
| source L km003c.pas:229-234 | Rate | Flags | V_cc2_avg | V_dp_avg | V_dm_avg (same as R) |
| source I protocol.py:180-181 | payload[36] & 3 as rate |
Rest kept as raw hex | |||
| K | _unknown_3[4]; reads only up to 0x27 |
How the captured vectors fit each layout (my own decode of the bytes, §6.4):
| Vector | Tail bytes | Fits R? | Fits O? |
|---|---|---|---|
O adc_52.hex (firmware 2.0.6) |
00 80 02 F0 00 00 FF 00 |
No: CC2 average 0xF002 does not match CC2 = 29.4 mV | Plausibly, by inference: a separate O settings dump shows a meter rate of 50 SPS = code 2 notes O protocol.md:343-346. That dump is not from the same capture. |
R EXTENDED_ADC_DATA (tests/common/mod.rs:36-37) |
00 80 A4 0C 00 00 00 00 |
Yes: CC2 average 0x0CA4 = 3236 mV vs CC2 = 3237.1 mV | No: rate code 0xA4 is impossible |
R REAL_ADC_RESPONSE (tests/common/mod.rs:28-32) |
00 80 02 00 00 00 00 00 |
Ambiguous | Ambiguous |
Conclusion:
- Decode offsets 0x00–0x23 (36 bytes) only.
- Expose 0x24–0x2B as raw bytes.
- Accept a section size of 40 or 44, and never require more than 36.
6.4 Worked examples
Example A, firmware 2.0.6, idle, nothing attached source O tests/vectors/adc_52.hex:
41 01 80 02 01 00 00 0B 64 10 00 00 A1 FF FF FF 91 10 00 00 B0 FF FF FF
F5 10 00 00 00 00 00 00 BA 0E 25 03 26 01 D4 02 F2 02 30 7D 00 80 02 F0
00 00 FF 00
Decoded:
| Field | Raw | Value |
|---|---|---|
| Header | 41 01 80 02 |
type 0x41, id 1; bytes 2–3 = 0x0280, so obj = 10 and permi = 0 |
| VBUS | 4196 | 4.196 mV |
| IBUS | −95 | −95 µA |
| VBUS average | 4241 | µV |
| IBUS average | −80 | µA |
| VBUS uncalibrated | 4341 | |
| IBUS uncalibrated | 0 | |
| Temperature | 3770 | 29.45 °C |
| CC1 | 805 | 80.5 mV |
| CC2 | 294 | 29.4 mV |
| D+ | 724 | 72.4 mV |
| D− | 754 | 75.4 mV |
| VDD | 32048 | 3.2048 V |
O's prose gives the same values notes O protocol.md:236-238. I re-derived them from the hex.
Example B, with a 5 V source source R tests/common/mod.rs:26-32; asserted values in tests/adc_tests.rs:108-200:
41 00 80 02 01 00 00 0B 45 1C 4D 00 AE 9E FE FF ... C9 0C 8A 10 ...
| Field | Raw | Value |
|---|---|---|
| VBUS | 0x004D1C45 = 5053509 | 5.0535 V |
| IBUS | 0xFFFE9EAE = −90450 | −0.090 A |
| Temperature | 0x0CC9 = 3273 | 25.57 °C |
| CC1 | 0x108A = 4234 | 0.4234 V |
Example C, vendor PDF, 40-byte payload vendor-doc V1 p.3:
41 09 02 02 01 00 00 0A 05 3E 00 00 1A 00 00 00 ... 4D 84 69 0C D2 0C
The request was 0c 00 02 00, yet the reply id is 09; see §14 C6.
6.5 Recipe: "read ADC once" (bulk IF0)
- Find
5FC9:0063, open it and claim interface 0.- Linux: detach
powerzfirst. - macOS: no detach is needed notes O protocol.md:58-61.
- Do not USB-reset the device. R resets by default and then waits 1.5 s source R device.rs:510-521; nothing requires a reset. K never resets.
- Linux: detach
- Drain EP 0x81: read with roughly a 50–100 ms timeout until a read times out, discarding anything that arrives (for example
03 xx 00 00) source O transport/bulk.rs:25-36. Do the same after any timed-out or failed exchange, before the next write. On the user's unit, writing while EP 0x81 still held a reply or ZLP stalled the meter and caused a watchdog reboot; see the hazard box at the top device fw 1.9.5. id := next u8. Any value works; K uses 0. Write0C id 02 00(4 bytes) to EP 0x01.- Read EP 0x81 into a buffer of at least 2048 bytes, with a 1 s timeout.
- K waits only 5 ms source K powerz.c:134-135.
- RR measured a median ADC latency of 164 µs notes RR protocol_reference.md:694.
- The vendor app uses 1000 ms (2000 ms for CONNECT) notes O protocol.md:738.
- Validate the reply:
len >= 8.b[0] & 0x7F == 0x41. If it is0x03(DISCONNECT) or0x06(REJECT), retry once.b[1] == id. If the id differs, the frame is stale: skip it and keep reading until the timeout. Then drain EP 0x81 before the next write (§14 C6, resolved on fw 1.9.5).ext := LE32(b[4:8]),ext & 0x7FFF == 1, andsize := ext >> 22is at least 36.len >= 8 + size.- A 4-byte
41 id ..reply means empty: retry.
- Decode
b[8 : 8+size]with the table in 6.2. - Pacing:
- Keep one request in flight.
- The vendor app polls ADC about every 200 ms notes RR protocol_reference.md:614-621.
- O uses at least 60 ms between requests notes O protocol.md:718-719.
HID variant (IF3).
- Write the 64-byte output report
0C id 02 00followed by 60 ×00. Through hidapi that is a 65-byte buffer starting with00. - Read one 64-byte input report and parse it as above. Bytes after
8+sizeare zero padding. - Do not send anything else over HID source O transport/hid.rs:49-73, source N meter.py:178-204.
- The vendor's own sample does exactly this source VS hiddemo.cpp:230-252, 266-291. It sends a 64-byte interrupt OUT transfer whose first 4 bytes are
0C 00 02 00(id always 0), reads one 64-byte interrupt IN transfer, uses a 1000 ms timeout and polls every 150 ms. It checkstype == 0x41and sectionatt == 1, and displaysVbus_avgandIbus_avg.- In that sample, bytes 4–63 of the OUT buffer are uninitialised stack memory, so the firmware evidently ignores them. Zero-pad anyway.
- O also reports that control commands (CONNECT, 0x0E, 0x0F, 0x44, 0x4C) get no reply over HID notes O protocol.md:754-756.
CDC variant (not recommended).
- Write
0C id 02 00to the tty and read until a full 52-byte frame matches the id. I's hardware check confirmed it works notes I README.md:354; source I transport.py:268-283. - Never write
0x01,0x02or0x03frames there.
7. PD data (attribute 0x010) and related
7.1 PD status block (12 bytes)
When the payload is exactly 12 bytes, the reply is status only. When it is longer, the status block is the preamble of an event stream.
| Off | Type | Field | Unit |
|---|---|---|---|
| 0 | u32 | Device timestamp | ms |
| 4 | u16 | VBUS | mV |
| 6 | i16 | IBUS, signed | mA |
| 8 | u16 | CC1 (on a UFCS stream: D+) | mV |
| 10 | u16 | CC2 (on a UFCS stream: D−) | mV |
Sources: source R pd.rs:18-30, constants.rs:9-10; source O decode/pd_packet.rs:7-36; source I protocol.py:255; source L km003c.pas:173-180; notes O protocol.md:990-998.
7.2 Event and PD-message records after the status block
Each record starts with a flag/length byte b0.
b0 |
Record length (including b0) | Kind |
|---|---|---|
| bit 7 set | (b0 & 0x3F) + 1 |
PD message |
| bit 7 clear, bit 5 set | (b0 & 0x1F) + 1 + u16 at +6 |
Long (extended) PD message, per source O decode/pd_packet.rs:232-251 |
| bit 7 clear, bit 5 clear | (b0 & 0x1F) + 1 |
Event (for example 0x45 gives 6 bytes) |
- Bit 6 of
b0marks a record the meter sent itself notes O protocol.md:1008-1009. - The PD-message length rule agrees with R and I. They compute
wire_len = (b0&0x3F) − 5after a 6-byte header, which gives the same total source R pd.rs:222-252, constants.rs:36-40, source I protocol.py:283-306.
Record body:
| Offset | PD message | Event |
|---|---|---|
| +1 | u32 timestamp, ms, same clock as the status block | Same |
| +5 | SOP type in the low 3 bits: 0 SOP, 1 SOP′, 2 SOP″, 3 SOP′_Debug, 4 SOP″_Debug | Low nibble = event code, high nibble = parameter |
| +6 | u16 USB-PD message header | — |
| +8 | u32 × n data objects (no CRC) | — |
Sources: source O decode/pd_packet.rs:255-285; notes O protocol.md:1017-1031.
Event codes:
| Code | Event |
|---|---|
| 0 | none |
| 1 | attach (parameter 1 = CC1, 2 = CC2) |
| 2 | detach |
| 3 | bad message id |
| 4 | hard reset |
| 5 | cable reset |
| 6 | receive error (the parameter gives the cause) |
| 7 | monitor type |
| 8 | big message |
Sources: notes O protocol.md:1029-1031; source O decode/pd_packet.rs:286-322 (decode_event: low nibble = code, high nibble = parameter).
L's constants agree with this decoding: 0x11 attach CC1, 0x12 detach CC1, 0x21 / 0x22 connect / disconnect, 0x46–0x96 receive errors source L km003c.pas:283-295. R treats 0x45 + 0x21/0x22 as connect/disconnect and 0x11/0x12 as "legacy" source R constants.rs:21-34, pd.rs:202-219. See §14 C15.
Reading PD data:
- Classification: READ-CONSUMES. Records are queued in the device and drained by each poll.
- One section carries at most about 320 bytes. Poll quickly (every 5–40 ms) to keep up notes O protocol.md:980-984.
- PD polling works at L0 without 0x10 notes O protocol.md:977-984, notes RR protocol_reference.md:639-649.
7.3 Attribute 0x020 (PD_STATUS / PdTrace)
The section-header size is 0, so take the rest of the frame source O frame.rs:387-393, notes RR protocol_reference.md:392-397.
R reading (firmware 1.9.9): two length-prefixed queues: [n1:u8][code:u8, uptime_s:u32]... [n2:u8][code:u8, uptime_s:u32]... notes RR protocol_reference.md:380-408. O sees 2 or 12 trailing bytes notes O protocol.md:186, 193-195, which fits two empty queues (00 00) or one record in each queue.
Classification: READ-CONSUMES. A CLI does not need it.
7.4 Attribute 0x040 (QC_PACKET; really a UFCS sniffer)
- Firmware notes say this is a UFCS trace: a 12-byte preamble followed by 8-byte descriptors and frames notes RR handlers.md:300-320.
- When idle, O sees the 12-byte status plus 8 constant bytes notes O protocol.md:187, 1032-1033.
- It is not a "detected protocol" field (§13).
8. AdcQueue (attribute 0x002), SETTINGS (0x008) and other reads
8.1 AdcQueue
The CLI does not need this. The queue gives buffered high-rate samples.
Record (20 bytes):
| Off | Type | Field |
|---|---|---|
| 0x00 | (conflict, §14 C10) | 4 bytes of time information |
| 0x04 | i32 | VBUS, µV |
| 0x08 | i32 | IBUS, µA |
| 0x0C | u16 | CC1 |
| 0x0E | u16 | CC2 |
| 0x10 | u16 | D+ |
| 0x12 | u16 | D− |
- CC and D± units: 0.1 mV at rate code 0 (2 SPS), 1 mV at the faster rates.
- Sources: source R adcqueue.rs:24-32, 65-69, 125-157; source O decode/queue.rs:5-36; notes O protocol.md:271-291.
- Poll at least every 60 ms at 1000 SPS, or samples are lost notes O protocol.md:261-263.
8.2 SETTINGS
The reply is 188 bytes: header, then section att 8, size 180.
| Offset | Content |
|---|---|
| 0x00–0x5F | Block A (96 B) |
| 0x00 | u32 flags: bit 0 language; bits 3–9 brightness %; bits 10–11 dim timeout; bits 14–15 startup-logo time; bits 16–18 theme; bit 27 auto-rotate |
| 0x1C | 5 × i32 calibration array |
| 0x30 | 10 × i32 gains, about 1e6 |
| 0x58 | i32 offset |
| 0x5C | CRC-32 (IEEE/zlib) of 0x00..0x5B |
| 0x60–0xB3 | Block B (84 B) |
| 0x60 | u32 flags: bits 0–1 rotation; bits 2–3 = sample-rate code (0=2, 1=10, 2=50, 3=1000 SPS) |
| 0x70 | char[64] device name, e.g. POWER-Z |
| 0xB0 | CRC-32 of 0x60..0xAF |
Sources: source R settings.rs:10-17; notes RR protocol_reference.md:410-470; notes O protocol.md:297-346.
- Classification: SAFE-READ over bulk or CDC. Never over HID.
- Use: the rate code at 0x60 bits 2–3 can be compared with ADC tail byte 0x24 or 0x26 to settle §14 C1 without changing anything on the device.
8.3 TICK and LogMetadata/RecordList
- TICK (0x080): 8 bytes, u32 uptime in ms followed by u32 0. Needs auth level 1 notes O protocol.md:188. The name comes from source VS hiddemo.cpp:48.
- LogMetadata/RecordList (0x200): N × 48-byte catalog entries. Needs L1. Entry size: source R offline.rs:29 (
LOG_METADATA_SIZE = 48); notes RR protocol_reference.md:525-549; notes O protocol.md:544-549.
9. Device information (model, firmware, serial)
9.1 Without the protocol: USB descriptors (SAFE)
These need no protocol traffic:
| Descriptor | Value |
|---|---|
| iManufacturer | ChargerLab |
| iProduct | POWER-Z KM003C |
| iSerial | 050002 on this unit |
| IF0 interface string | APP = application mode, per notes O protocol.md:38 |
Neither the firmware version nor the OTP serial is in the descriptors.
9.2 MemoryRead (0x44): bulk only, after CONNECT, known addresses only
Preconditions:
- Bulk IF0 only. Over HID there is no reply; over CDC there is no reply, and CONNECT there starts ADCNEW notes O protocol.md:477-484, 754-756.
- CONNECT is required first. Without it the device answers
06 id 00 00REJECT. This was observed on firmware 2.0.6 notes O protocol.md:478-482, and O enforces it in code source O session/memory.rs:219. - No authentication is needed notes O protocol.md:477-478. The firmware 1.9.9 decompilation shows no auth check on 0x44 notes RR handlers.md:172-200.
Request (36 bytes): 44 id 01 01 followed by AES-128-ECB(key0, P).
- Bytes 2–3
01 01are a raw header word. Do not build them with the att<<17 encoder source R message.rs:516-523, notes RR protocol_reference.md:154-155. Pis 32 bytes of plaintext:
| Off | Field |
|---|---|
| 0x00 | u32 address |
| 0x04 | u32 length |
| 0x08 | u32 0xFFFFFFFF |
| 0x0C | u32 CRC-32 (IEEE, as zlib crc32) of P[0:12] |
| 0x10 | 16 × 0xFF |
Sources: source R auth.rs:271-292; source O crypto/mod.rs:15-51; notes O protocol.md:486-495.
- key0 = ASCII
Lh2yfB7n6X7d9a5Z=4C 68 32 79 66 42 37 6E 36 58 37 64 39 61 35 5A. It appears in source RR km003c_analysis/device/protocol.py:76-77 and asKEYS[0]in source O crypto/keys.rs:10-13.
Reply:
- A 20-byte framed confirmation:
C4 id <b2> 01followed by the plaintext echo of P[0:16] (address, length, magic, CRC).- Type
0x44has the extend bit set, which givesC4. b2bit 0 is the encrypted flag.- Sources: source R auth.rs:312-358, memory.rs:115-168; notes O protocol.md:497-502.
- Type
- Then unframed transfer(s) totalling
roundup16(length)bytes. If the flag is set, decrypt them with AES-128-ECB key0 and truncate tolengthsource R memory.rs:29-113. - Then a zero-length packet, observed after a 64-byte (multiple-of-64) data transfer. Read it before writing the next request; leaving it queued stalls the meter and triggers a watchdog reboot (see the hazard box at the top).
- On this unit: the confirmation arrived after 1.1–1.4 ms, the 64-byte ciphertext 14.5–15.2 ms after the request, then the ZLP.
- device fw 1.9.5 bulk_W6_1_resp.hex, bulk_W6_1_respdata.hex, INDEX.txt
Errors:
06REJECT: missing CONNECT, or bad magic, size or address.27NOT_READABLE: bus fault.
Sources: source R memory.rs:43-55, device.rs:179-187; notes RR handlers.md:183-209.
Chunking and pacing:
- Use at most 256 bytes per request. O observed truncation above that on 2.0.6 notes O protocol.md:504-509; R uses a 2528-byte chunk source R memory.rs:14 (§14 C11). The info blocks are only 64 bytes.
- Space reads at least 50–100 ms apart notes O protocol.md:520-521.
- Do not read while AdcQueue streaming is active source R device.rs:1155-1162.
Known addresses: the whitelist. Do not read any other address. Third parties report that other peripheral addresses crash the meter notes O protocol.md:520-521, 1241.
The firmware itself does not restrict addresses; the client-side whitelist is the only protection.
- The MemoryRead handler checks only three things: magic =
0xFFFFFFFF, size <0x3D0901, and address <0x983D0901. - There is no lower bound and no allow-list, so peripheral registers can be read. Reading some registers has side effects, such as FIFOs and clear-on-read status registers.
- Sources: firmware analysis §11 (1.9.5 through 2.0.7, identical logic), and notes RR handlers.md:172-200 (1.9.9).
Check the confirmation against the request. The confirmation echoes the address and length. The client must reject a C4 confirmation whose address or length differs from what was requested, and must not read the following data as the requested block.
- One case where they differ: the firmware may redirect reads inside the OTP window 0x03000C00–0x03000D7F to 0x03000D80 (firmware analysis §11).
- R performs the same check source R memory.rs:143-148.
- After a rejected confirmation, drain EP 0x81 before writing again: the ciphertext and the zero-length packet will still arrive (see the hazard box at the top).
| Address | Length | Content and parse |
|---|---|---|
0x00000420 |
64 | Info block. 0x10 model[12], e.g. KM003C. 0x1C version[12]: R calls it hardware version ("2.1"); O says it is likely the bootloader/hardware version ("2.5"). 0x28 date, 0x34 extra. source R auth.rs:164-178; source O decode/info.rs:26-40; see §14 C12. |
0x00004420 |
64 | Application firmware block. 0x00 u32 = 0x00004000; 0xFFFFFFFF means none. 0x10 model[12], 0x1C firmware version[12] (e.g. 1.9.9, 2.0.6), 0x28 firmware date[12]. source R auth.rs:180-196; source O decode/info.rs:26-40; notes O protocol.md:516 |
0x03000C00 |
64 | OTP/calibration block. The serial is the first ASCII token: R reads 7 bytes at 0x00, space-padded (e.g. 007965); O reads up to a space, NUL or 0xFF. R reads a 32-character hex UUID at 0x07..0x26. source R auth.rs:198-208; source O decode/info.rs:64-85 |
0x40010450 |
12 | MCU unique ID, used as the auth level-1 credential. Read it only if authentication is needed. source R auth.rs:43-47; source O session/memory.rs:15-21 |
R's whole "full init" sequence is: CONNECT, read 0x420, 0x4420 and 0x3000C00, read the UID, then StreamingAuth source R device.rs:961-1034. For a read-only info command, CONNECT plus the three 64-byte reads are enough.
10. Authentication (0x4C): what it gates
Request (36 bytes): 4C id 00 02 followed by AES-128-ECB(key3, P32).
- Bytes 2–3
00 02are a raw word: 0x0200 source R message.rs:524-531, source O session/auth.rs:48-53. - key3 =
Fa0b4tA25f4R038asource RR protocol.py:78-79, source O crypto/keys.rs:22-25 (KEYS[3]). - The P32 plaintext differs by source; per the 1.9.9 decompilation, only the credential bytes are checked:
| Source | P32 layout |
|---|---|
| source R auth.rs:383-403 | [u64 LE ms timestamp][12-byte credential][12 random bytes] |
| source O session/auth.rs:17-28 | [u64 ms][credential (≤16 B)][u64 random], padded with 0xFF |
Credential check: notes RR handlers.md:76-96.
Reply: 4C 00 <lo> <hi> followed by 32 bytes.
- The id is always 0 source R auth.rs:37, device.rs:1036-1050.
- The raw word bytes 2–3 hold: bit 0 = result/encrypted flag; bits 1–2 = auth level.
0x0201= level 0 (failed).0x0203= level 1.0x0205= level 2.- source R auth.rs:31-35, 468-495; notes RR handlers.md:98-102.
- The payload is the plaintext re-encrypted with
FX0b4tA25f4R038a(key3 with byte 1 =X) source O session/auth.rs:55-83, notes RR features/authentication.md:93-98.
Credentials:
- Level 1: the 12-byte UID read from 0x40010450.
- Level 2: a calibration credential. Sources disagree on which bytes (§14 C13).
- Behaviour: HID gets no reply. The level is lost when the device is reopened. Keep requests at least 1 s apart. notes O protocol.md:686-697; source O session/auth.rs:11-12
Gating summary
| Needs | Commands |
|---|---|
| Nothing (no CONNECT, no auth) | GET_DATA ADC on bulk, HID and CDC source K powerz.c; notes O protocol.md:240-241. PD_PACKET on bulk source I km003c_cli.py:817. SETTINGS on CDC notes O protocol.md:378-382. SETTINGS on bulk without CONNECT is unverified. |
| CONNECT only, on bulk | MemoryRead at the known addresses |
| Firmware-dependent at L0 | AdcQueue poll, 0x020, 0x040: masked at L0 on 1.9.9, served at L0 on 2.0.6 (§14 C7) |
| L ≥ 1 | 0x0E, 0x0F, 0x10, 0x11; TICK; RecordList; 0x4A flash write |
| L2 | 0x4D; calibration operations |
| Ungated and dangerous | 0x48 settings batch (including reset operations) notes RR handlers.md:117-170; 0x0A settings write over CDC notes O protocol.md:366-386 |
Recommendation: the Go client should never authenticate. Nothing it needs is gated, and authenticating only widens what a bug could do.
11. CDC-only behaviour: ADCNEW and PDM text (do not use)
ADCNEW stream
- Frames:
[type=0x02][att][obj = body words][crc8], then 20-byte records (u32 ms, i32 µV, i32 µA, 4 × u16). - Start:
02alone, or02 <att>where the high nibble is the content and the low nibble is the rate. - Keep-alive:
01. Stop:03. - The stream stops after one hour unless refreshed.
Sources: source I transport.py:286-338, protocol.py:310-327; notes O protocol.md:784-828.
Conflict: I says the CRC-8 algorithm is undocumented and leaves it unverified on hardware notes I README.md:198-206. O reports poly 0x29, init 0 notes O protocol.md:800.
Classification: MODE, CDC only. Not needed.
PDM text commands
These are lowercase ASCII, one command per write, with no terminator. Examples:
pdm openandpdm close;pdm set type=..,em=..;entry pd|qc|ufcs|fcp|scp|afc|vfcp|sfcp;qc 9V,qc3 volt=...,pd req=...,pd cmd=...,pd data=...;reset.
Sources: vendor-doc V2 p.1-2; source I transport.py:341-371; notes O protocol.md:830-970.
All of them are UNSAFE-POWER:
pdm openmakes the meter present Rd as a sink.- The
entryand request commands negotiate higher VBUS with the charger. entry listactively probes the charger and can raise VBUS notes O protocol.md:844-873.
12. Safe-read whitelist and never-send list
12.1 Whitelist: the only frames a read-only CLI should emit
| # | Bytes (id = ii) |
Transport | Purpose | Class |
|---|---|---|---|---|
| W1 | 0C ii 02 00 |
IF0 bulk, IF3 HID (padded to 64), IF2 CDC | ADC snapshot | SAFE-READ |
| W2 | 0C ii 10 00 |
Bulk, CDC | SETTINGS (rate code, device name). On bulk without CONNECT this is unverified; send W5 first if it fails. | SAFE-READ |
| W3 | 0C ii 20 00 |
Bulk, CDC | PD status and PD records | READ-CONSUMES |
| W4 | 0C ii 22 00 |
Bulk, CDC | ADC + PD in one request | READ-CONSUMES |
| W5 | 02 ii 00 00 |
Bulk only | CONNECT, before W6 | SESSION |
| W6 | 44 ii 01 01 + AES(key0, P) |
Bulk only, after W5 | MemoryRead of exactly 0x420/64, 0x4420/64 or 0x03000C00/64 (and 0x40010450/12 only if ever needed) |
SAFE-READ (restricted) |
Optional (READ-CONSUMES, and gating depends on firmware): 0C ii 04 00 (AdcQueue), 0C ii 40 00, 0C ii 80 00.
12.2 Never send
| Item | Why | Evidence |
|---|---|---|
Types 0x04, 0x08, 0x09, 0x42 |
Reset, DFU, firmware erase | source O guard.rs:18-22 |
Types 0x0A, 0x48, 0x4A, 0x4D |
Persistent writes, including factory reset and calibration | source O guard.rs:18-22; notes RR handlers.md:28-37, 117-170 |
0x4B |
Unconfirmed memory-read variant | notes RR handlers.md:356-367 |
0x40 HEAD, 0x0D, 0x0B |
Not needed; flash-flow related or unknown | notes O protocol.md:150-152, 162 |
0x0E, 0x0F, 0x10, 0x11 |
Need auth; change runtime modes | §4 |
0x4C |
Raises privileges; not needed | §10 |
| MemoryRead at any address not on the whitelist | Reported to crash the meter | notes O protocol.md:1241 |
| Any HID request other than W1 | Replies over 64 bytes hang and reboot the meter | notes O protocol.md:757-769; source O transport/hid.rs:49-63 |
On CDC: frame types 0x01–0x03, and any ASCII text |
Control ADCNEW; PDM changes VBUS | source O transport/cdc_frame.rs:30-36; vendor-doc V2 |
USB port reset, and vendor control request 0xC2/0x32 (170 B) |
Not needed; the control request's semantics are unknown | source R device.rs:510-521; notes RR usb_transport.md:226 |
13. "Detected fast-charge protocol" (shown on the screen)
No source exposes it as a binary read.
- None of the GET_DATA attributes documented by V1, R, RR or O carries the protocol name the meter shows on screen.
- The vendor name
ATT_QC_PACKET(0x040) is a UFCS sniffer stream, not a detection result (§7.4). The name is not evidence. - The only documented detection path is the CDC text command
entry list, and the per-protocolentry bc/entry apple. These actively probe the charger and can raise VBUS notes O protocol.md:865-873, 901-912. They are UNSAFE.
What a client can do instead, as inference only and labelled as such:
- show D+/D− voltages from the ADC (§6.2), for example BC1.2 or Apple divider levels;
- show passively captured PD Source_Capabilities, which appear in the PD records (§7.2) when the meter takes part in a negotiation.
14. Open questions and conflicts
Verified on device: conflict resolution (user's KM003C, fw 1.9.5)
These are results from the user's unit on 2026-11-16. Each row is verified (fw 1.9.5), pending or not probed. A result on 1.9.5 does not prove the same behaviour on 1.9.9 or 2.0.x; the conflict text below each heading still describes the other firmware versions. Rows marked "do not probe" need a risky request, so leave them unless the team lead approves.
| Conflict | Safe way to settle it | Verified on device | Evidence (capture / date) |
|---|---|---|---|
| C1 / C2: ADC tail and rate byte | Compare SETTINGS u32@0x60 bits 2–3 with ADC bytes 0x24 and 0x26 | verified (fw 1.9.5)
| bulk_W1_1_resp.hex … _5, bulk_W2_1_resp.hex |
| C3: IBUS sign | One reading with a load in a known direction | pending Only about 0 A has been measured so far. | — |
| C4: temperature encoding | Compare raw/128 with the on-screen temperature | verified (fw 1.9.5) raw/128 matches the screen (raw 3366 = 26.30 °C). Negative temperatures and the 0x8000 sentinel were not exercised. | bulk_W1_1_resp.hex |
| C5: obj and permi bits | Record bytes 2–3 of ADC replies of different lengths | verified (fw 1.9.5) obj = len/4 − 3 for 20, 52, 68 and 188-byte replies, and permi = 0 without auth. The vendor PDF example (obj 8 for a 48-byte frame) is still unexplained. | W3_1, W1_1, W4_1, W2_1 |
| C6: id echo | Send ADC requests with varying ids | resolved (fw 1.9.5) Echoed on 20 of 20 requests (ids 1–20) over bulk, HID and CDC, including CONNECT and the MemoryRead confirmation. Recommendation changed to match on type and id (see C6 below). | INDEX.txt |
| C7: level-0 gating | AdcQueue poll 0C id 04 00 at L0 (read-only, drains the queue) | not probed | — |
| C8: PD over HID | Do not probe (a reply over 64 bytes can reboot the meter) | not probed (by design) | — |
| C11: MemoryRead chunk limit | Not needed; info blocks are 64 B | not probed Only 64-byte reads were made; each returned one 64-byte data transfer plus a ZLP. | bulk_W6_1_respdata.hex |
| C12: meaning of the 0x420 block | CONNECT + MemoryRead 0x420/64 over bulk | verified (fw 1.9.5) Contents only: model KM003C, version 2.2, date 2024.9.23, extra empty. This differs from the application version 1.9.5, which fits O's "bootloader/hardware block" reading; what the field means is still unproven. | bulk_W6_1_plain.hex |
| C16: CONNECT necessity | ADC read without CONNECT; SETTINGS over bulk without CONNECT | verified (fw 1.9.5) ADC, SETTINGS, PD and ADC+PD all answered before any CONNECT was sent. CONNECT was used only ahead of MemoryRead. | INDEX.txt (order: W1–W4, then W5 CONNECT, then W6) |
| C18: ZLP on 64-byte-multiple replies | Observe bulk reads of 64-byte-multiple replies | verified (fw 1.9.5) Answered for MemoryRead: the 64-byte data transfer is followed by a ZLP. Leaving that ZLP (or any reply) unread before the next write stalls the meter and triggers a watchdog reboot; see the hazard box at the top. No 64-byte-multiple GET_DATA reply was seen; SETTINGS is 188 B. | INDEX.txt (drain note); active_bulk_log.json |
| C20: firmware version | CONNECT + MemoryRead 0x4420/64 over bulk | verified (fw 1.9.5) Application firmware 1.9.5 (2025.1.7). That is older than R's 1.9.9 and O's 2.0.6. | bulk_W6_2_plain.hex |
| C21: CDC reply size | Do not probe beyond the ADC read on CDC | not probed (by design). The 52-byte ADC reply over CDC worked. | cdc_W1_1_resp.hex |
| New: EP 0x81 stall | Always consume the post-MemoryRead ZLP; drain EP 0x81 after any failure | observed (fw 1.9.5) Writing while a reply or ZLP was still queued: no answer, USB stall, watchdog reboot, re-enumeration. | Team client run; no capture file |
C1 – ADC tail 0x24–0x2B. There are three layouts:
- V1: Rate:2 at 0x24.
- R and L (firmware 1.9.x): rate at 0x24, flags at 0x25, then CC2/D+/D− averages.
- O (firmware 2.0.6): T2 i16 at 0x24, rate at 0x26, battery at 0x28.
The captured vectors fit different layouts (§6.3), so the layout is firmware-dependent.
To resolve without changing anything: read SETTINGS and compare bits 2–3 of the u32 at 0x60 with ADC bytes 0x24 and 0x26. Also read the 0x4420 block to learn the firmware version.
C2 – Sample-rate field offset. It is 0x24 (V1, R, I) or 0x26 (O). Same evidence as C1.
C3 – IBUS sign convention.
- R: positive = power flows from the USB female (input) side to the male (output) side source R adc.rs:98-104.
- O: negative = current from the receptacle (female) to the plug (male) notes O protocol.md:219.
These are opposite. K only says the sign shows direction source K Documentation/hwmon/powerz.rst. To resolve: one measurement with a known load direction.
C4 – Temperature.
- R and O: i16/128 °C. O adds
0x8000= invalid. - K:
b1*2000 + b0*1000/128m°C, which is wrong for negative raw values. - V1 example: raw 0.
- NV: raw/100 source NV constants.py:51. It also masks CC/D± with 0x0FFF and divides by 1000 source NV constants.py:54-57, which contradicts every other source. Disregard NV's scalings.
C5 – Data-header bytes 2–3 (obj, permi).
- permi is settled. The vendor sample code declares
encode:1, permi:2, :3, obj:10source VS hiddemo.cpp:76-85. This matches O's reading that bits 17–18 hold the auth level. The PDF still shows the older unnamed:6vendor-doc V1 p.1. In the V1 example41 09 02 02and in R'sEXTENDED_ADC_DATA, permi = 1, which suggests those captures came from authenticated sessions. - obj is still in conflict:
- V1 and VS: payload size in 4-byte words.
- R:
len/4 − 3. - O: about
(len−12)/4, with exceptions. - The V1 example has obj = 8 for a 48-byte frame, where the R formula gives 9.
Treat obj as opaque. Treat permi as diagnostic only.
C6 – Transaction-id echo.
- R and O (device) observe the request id echoed; R matches on it source R device.rs:167-169.
- Exceptions: the 0x4C auth reply and the HEAD reply carry id 0.
- The vendor app never checks ids notes O protocol.md:721-722.
- The V1 example shows request id 0 and reply id 9. It is probably not the same exchange.
- The vendor sample always sends id 0 and checks only the type and section att source VS hiddemo.cpp:235-237, 275. Its own comment nonetheless says the id "keeps incrementing" source VS hiddemo.cpp:72.
- I matches on type only source I transport.py:274-279.
Resolved (fw 1.9.5). The user's unit echoed the request id on 20 of 20 replies, including the CONNECT ACCEPT and the MemoryRead C4 confirmation (§6 and §14 "Verified on device").
Recommendation: match replies on type AND id.
- Why not type only: a stale reply that arrives after a retry would be taken as the retry's answer. The retry's real reply then stays queued on EP 0x81, and the next write stalls the meter (see the hazard box at the top).
- What the powerz client does: it skips frames carrying a foreign id, keeps the last frame of the wanted type only as a fallback, and drains EP 0x81 before the next write.
- Exceptions that keep id 0: the 0x4C auth reply and the HEAD reply. The client never sends those requests.
C7 – Level-0 gating. On 1.9.9 the decompilation masks the attributes to 0x19 notes RR handlers.md:110-113. On 2.0.6, AdcQueue, 0x020 and 0x040 are served at L0 notes O protocol.md:203-206.
C8 – PD over HID.
- R presents HID as an "ADC/PD polling" mode source R device.rs:196-224.
- NV sends PD over HID by default.
- I got no reply to PD-only requests over HID.
- O observed hangs and reboots for any reply over 64 bytes.
Decision: HID is ADC-only.
C9 – Names of 0x020 and 0x040. V1 calls them ATT_PD_STATUS and ATT_QC_PACKET. R calls 0x020 PdTrace. RR and O treat 0x040 as UFCS.
C10 – AdcQueue record bytes 0–3. R reads u16 sequence + u16 marker source R adcqueue.rs:125-127. O reads a u32 ms time and says R's reading is wrong source O decode/queue.rs:27; notes O protocol.md:285.
C11 – MemoryRead chunk limit. R uses 2528 bytes source R memory.rs:14. O observed 256 notes O protocol.md:504-509. Use ≤ 256.
C12 – Meaning of the 0x420 block. R says model, hardware version and manufacturing date (24 B) source R auth.rs:165-178. O says model, version ("2.5", likely bootloader), date (12 B) and extra source O decode/info.rs:26-40.
C13 – Level-2 credential. R uses the first 12 bytes of the calibration record at 0x03000D80, falling back to 0x03000C00 source R device.rs:1095-1138. O uses the first 16 bytes of the OTP at 0x03000C00 source O session/auth.rs:14-38. This does not matter for a read-only client.
C14 – StreamingAuth plaintext layout. The two sources lay out the bytes after the credential differently (§10). Only the credential is checked.
C15 – PD connection events.
- R: marker
0x45, a 24-bit timestamp at +1..+3, and code0x21/0x22= connect / disconnect, with0x11/0x12as "legacy" source R pd.rs:202-219. - O and L: generic event records with a u32 timestamp. The code byte's low nibble is the event and the high nibble the CC line, so
0x11/0x21= attach on CC1 / CC2 source O decode/pd_packet.rs:255-322; source L km003c.pas:283-295.
C16 – CONNECT necessity. K, N, I and O show that the ADC needs no CONNECT. R's vendor mode always sends CONNECT plus a full init, including a USB reset. Decision: send CONNECT only before MemoryRead.
C17 – Unreliable sources. C's endpoint map and NV's scalings contradict the descriptors and every other source. They are kept only for completeness.
C18 – Bulk replies that are an exact multiple of 64 bytes. It is unknown whether the device ends them with a zero-length packet. A large read buffer plus a timeout is the robust approach. R's until_short_packet would error without a ZLP source R device.rs:722-729.
C19 – Vendor control request 0xC2/0x32, wLength 170. Seen during enumeration in VM passthrough; semantics unknown notes RR usb_transport.md:222-227. Do not send it.
C20 – Firmware of the local unit. Unknown. Learn it with W5 and W6 at 0x4420, which also helps decide C1, C2, C7 and C11.
C21 – Section-size limits in the vendor material.
- PDF: size ≤ 1024−8,
chunk*size≤ 4080, HID ≤ 60 vendor-doc V1 p.1. - Sample code: size ≤ 4095−8, and "CDC and HID less than 64 bytes" source VS hiddemo.cpp:91.
- O observed 188-byte SETTINGS replies working over CDC notes O protocol.md:777-778.
The HID limit is consistent across all of them. On CDC, prefer replies under 64 bytes (ADC only) unless the device agent confirms longer replies are safe there.
15. Sources
All repositories were read at the pinned commits below. Line numbers refer to those commits. Downloaded code was read and never executed.
K – Linux kernel
drivers/hwmon/powerz.cat torvalds/linux@4dd10fbbeb9c33709edc89916e19c03c780a0751: https://github.com/torvalds/linux/blob/4dd10fbbeb9c33709edc89916e19c03c780a0751/drivers/hwmon/powerz.c- The ADC request is lines 121–124; the struct is lines 20–34; the scaling is lines 171–203; the ID table is lines 264–268.
Documentation/hwmon/powerz.rstat the same tree.
V1 – vendor PDF KM002C&3C API Description (Chinese, 3 pages), mirrored at okhsunrog/km003c-protocol-research@776b783b76b17e7ba0b59e9fff1d123180f32d2c docs/official/KM002C&3C API Description.pdf.
- p.1: transports and
MsgHeader_TypeDef. - p.2: message and attribute enums.
- p.3: ADC example and
AdcData_TypeDef.
V2 – vendor PDF KM003C/002C Protocol Trigger by Virtual Serial Port (Instructions) (2 pages), same mirror and path prefix.
VS – vendor sample code hiddemo_vs2019_for km002/hiddemo.cpp (328 lines, SHA-256 6f6eb3625ea8c75aad685a73449df4b21d3d2db2df411179ae58af1a8b98dc57).
- Source: ChargerLAB's "limited toolkit" zip at https://www.chargerlab.com/wp-content/uploads/2019/05/hiddemo_vs2019_for-KM002C3C.zip, linked from the POWER-Z technical-support FAQ "Are there any open APIs?" at https://www.power-z.com/blogs/technical-support/power-z-km003c-km002c-technical-support.
- The zip was fetched and extracted by the hardware-research teammate. I read it here and did not build or run it.
- The zip's
KM002C&3C API Description.docxis byte-identical to the RR mirror copy (SHA-25623fc3127…bbbd42).
R – okhsunrog/km003c-rs@c063388ecab1a169326de1b57e650a3a45fc94f6. Paths are under km003c-lib/src/ unless they start with tests/, which means km003c-lib/tests/. Main files: packet.rs, adc.rs, message.rs, device.rs, auth.rs, memory.rs, pd.rs, constants.rs, adcqueue.rs, settings.rs, tests/common/mod.rs, tests/adc_tests.rs. https://github.com/okhsunrog/km003c-rs/tree/c063388ecab1a169326de1b57e650a3a45fc94f6
RR – okhsunrog/km003c-protocol-research@776b783b76b17e7ba0b59e9fff1d123180f32d2c. Its notes cover firmware V1.9.9 reverse engineering and USB captures.
- Code:
km003c_analysis/device/protocol.py. - Notes:
docs/protocol_reference.md,docs/usb_transport.md,docs/firmware/handlers.md,docs/features/authentication.md.
https://github.com/okhsunrog/km003c-protocol-research/tree/776b783b76b17e7ba0b59e9fff1d123180f32d2c
O – nesquikm/open-powerz@6180fe74afc4972aebfd9ef527bc9136872d86ea. Notes cover firmware 2.0.6 device observations plus static analysis of vendor PC software V2.5.2.
- Code under
crates/powerz-protocol/src/:frame.rs,decode/adc.rs,decode/info.rs,decode/queue.rs,decode/pd_packet.rs,transport/guard.rs,transport/hid.rs,transport/bulk.rs,transport/cdc_frame.rs,session/memory.rs,session/auth.rs,crypto/mod.rs,crypto/keys.rs. - Test vector:
crates/powerz-protocol/tests/vectors/adc_52.hex. - Notes:
docs/protocol.md.
https://github.com/nesquikm/open-powerz/tree/6180fe74afc4972aebfd9ef527bc9136872d86ea
I – inuchanbt/KM003C-CLI@823e6766a049805e533a83973e5cb6e9ceabf7de: km003c_modules/protocol.py, km003c_modules/transport.py, README.md. https://github.com/inuchanbt/KM003C-CLI/tree/823e6766a049805e533a83973e5cb6e9ceabf7de
N – nbuchwitz/usb-meter@3d065276e24cafcf419b3fb71bed948841493dda: src/usb_meter/protocol.py, meter.py, connection.py. https://github.com/nbuchwitz/usb-meter/tree/3d065276e24cafcf419b3fb71bed948841493dda
C – chaseleif/km003c@699a25ac9b3a26eaff11410f94a16b9506fc5972: record.py.
L – LongDirtyAnimAlf/km003c@be3fcf02865bdca0fd04f9309b0d6c6e9893ae21: PC/USBCController/km003c.pas.
NV – nevetssf/powerz@33b23b932eb302f53cae5185558e8f5984b7ea8a: src/powerz/constants.py, src/powerz/device/protocol.py, connection.py, reader.py.
Not consulted:
- sigrok: a web search found no sigrok/libsigrok driver for ChargerLAB. The libsigrok tree itself was not searched.
- Manuals archive: okhsunrog/km003c-resources (archived manuals and firmware) was not read.
- ADCNEW vendor note: the note that O and I cite for the CDC stream was not located.
- Derivative projects: jfessard/km003c-web, alanyeh1128/powerz-km003c-monitor, fejesd/mcp-powerz-km003c, KHWLGH/laPower, kbsing/km003c-app and weixunkkkkk/km003c-workbench-macos appear to derive from the above. They were found by search but not read.