powerz

powerz CLI reference

Read-only command-line client for the ChargerLAB POWER-Z KM003C (USB 5fc9:0063). Built for humans at a terminal and for AI agents and scripts: JSON on stdout, fixed output shapes, structured errors with stable exit codes, and a self-describing powerz schema. The authoritative, machine-readable version of this page is powerz schema; a test keeps it identical to the real output.

1. Build and connect

# macOS
brew install libusb pkgconf
# Debian/Ubuntu
sudo apt install libusb-1.0-0-dev pkg-config

go install github.com/ljagiello/gopower-z/cmd/powerz@latest

Connect the meter's USB-C port marked HID to the computer. Plug the source (charger) into the meter's female receptacle and the device under test onto its male plug. On macOS no driver or root is needed. On Linux, the in-kernel powerz hwmon driver owns the interface; powerz detaches it while running, and you need a udev rule granting access to 5fc9:0063 (otherwise exit code 6). Linux is built and unit-tested in CI but has not yet been run with a meter attached.

2. Quick start

powerz                       # dashboard on a terminal, one JSON reading when piped
powerz read                  # one snapshot
powerz measure --duration 10s # min/mean/max, energy, charge, USB-PD capture
powerz info                  # model, firmware, serial, settings
powerz pd --duration 30s      # decoded USB-PD traffic, then a summary line
powerz log --duration 1m --interval 500ms --format csv > run.csv
powerz schema                # the machine-readable reference

3. Agent contract

  • JSON whenever stdout is not a terminal (force it with --json, or text with --text). stdout carries data only; diagnostics and errors go to stderr.
  • Fixed shapes. Every documented key is always present. Unavailable values are null and empty lists are []. Every object carries schema_version (currently 1).
  • Units are in field names: _v, _a, _w, _wh, _mah, _c, _s, _ms, _uv, _ua, _sps, _percent.
  • Timestamps are UTC ISO 8601 with milliseconds: 2026-11-17T01:34:25.627Z.
  • Direction. Current and power are positive when flowing from the meter's female receptacle to its male plug, which is the normal set-up and matches the meter's screen. direction says so explicitly (receptacle_to_plug, plug_to_receptacle or none), and raw.ibus_ua keeps the meter's own signed value.
  • Errors are one JSON object on stderr with code, exit_code, retryable and an actionable hint.
  • A non-zero exit can still carry data. measure prints its object and pd its summary line when they end early: on SIGINT/SIGTERM (exit 130, "end_reason":"interrupted", which is what an agent harness timeout sends) or when the meter disappears, is taken by another program or cannot be drained (exit 3, 4 or 1, "end_reason":"error"). log lines already printed stay valid. Read stdout before discarding it.
  • Bounded. read, measure, info, devices and schema terminate on their own. log and pd take --duration, which automation should always set.
  • One process per meter. A concurrent call fails with busy (exit 4, retryable) unless it passes --wait 10s to queue.
  • Validation, not silent changes. Out-of-range values such as --interval 5ms are usage errors that state the limit.
  • Interpretations are separate. Fields under inferred are computed by powerz, not reported by the meter.
  • Unknown is not the same as empty. Firmware-dependent fields are decoded only for firmware 1.7.9 to 2.0.7, the versions that were analysed. For any other firmware, or when the version cannot be read (firmware_error says why), they are null, raw.tail_layout is unknown and inferred.dashboard_classifier is null. A null dashboard label with a non-null classifier means the screen shows [N/A].

4. Commands

CommandOutputFlagsPurpose
readone JSON object-One snapshot. Default command when stdout is not a terminal. Reads the firmware version first (CONNECT plus one MemoryRead) to decode the firmware-dependent fields.
measureone JSON object--duration 5s --interval 100ms (≥ 20 ms) --pd=trueSamples for a fixed time. Returns stats (min/mean/max/last of V, A, W, °C), energy and charge over integrated_s, the dominant direction, and the USB-PD capture with every record. end_reason says whether the window completed or ended early. The main command for agents.
logJSON lines or CSV--interval 200ms (≥ 20 ms) --format jsonl|csv --count/-n --durationStreams snapshots (same shape as read). CSV columns: time, vbus_v, ibus_a, power_w, direction, vbus_avg_v, ibus_avg_a, power_avg_w, temp_c, cc1_v, cc2_v, dp_v, dm_v, vdd_v.
pdJSON lines--interval 25ms (≥ 10 ms) --duration --count/-n --goodcrcOne record per captured USB-PD message or event, then a final "kind":"summary" line with counts, capabilities, contract, end_reason and a note when nothing was captured. Bytes the meter delivered that cannot be parsed are kept as "kind":"undecoded" records. Sends only GET_DATA for the PD buffer: no session and no memory reads.
infoone JSON object-USB descriptors; model, firmware and hardware versions (ISO dates), serial and UUID; settings (sample rate, name, brightness, raw codes). The identity comes from three memory blocks: a block that cannot be read leaves only its fields null and is listed in errors (exit 7).
devicesone JSON object-Lists connected meters without claiming them, so it works while another process holds the meter.
watchterminal UI--interval 200ms --no-pdLive dashboard for humans; refuses to run without a terminal.
schemaone JSON object-Commands, flags with types and defaults, typed field definitions with nullability, exit codes, verified facts and caveats.
versionone JSON object-Tool and schema version (also --version).
completionshell scriptbash|zsh|fish|powershellShell completion for commands and flags.
helptext-Usage of powerz or of one command (also --help on any command).

Common flags, accepted before or after the command: --json --text --serial S --timeout D (≥ 100 ms) --wait D --trace. Flags take two dashes (--duration 10s or --duration=10s); -n for --count is the only shorthand. A single-dash long flag such as -duration is a usage error whose hint says so.

5. Output examples

All captured live from a KM003C on firmware 1.9.5 powering a test board at about 0.13 A.

powerz read

{
  "schema_version": 1, "time": "2026-11-17T01:34:25.627Z", "serial": "050002",
  "firmware_version": "1.9.5", "firmware_error": null,
  "vbus_v": 5.076484, "ibus_a": 0.132566, "power_w": 0.672969, "direction": "receptacle_to_plug",
  "vbus_avg_v": 5.076229, "ibus_avg_a": 0.132723, "power_avg_w": 0.673732,
  "temp_c": 27.906, "temp2_c": null,
  "cc1_v": 0.0003, "cc2_v": 1.6264, "dp_v": 2.9827, "dm_v": 0.0023, "vdd_v": 3.2049,
  "cc2_avg_v": 1.624, "dp_avg_v": 2.982, "dm_avg_v": 0.002,
  "sample_rate_sps": 50, "sink_battery_percent": null,
  "inferred": {
    "dashboard_label": null, "dashboard_label_2": "VOOC", "dashboard_classifier": "1.9.5",
    "cc": {"attached": "cc2", "advertisement": "3.0A", "advertised_current_a": 3,
           "text": "Type-C attached on CC2, source advertises 3.0A"}
  },
  "raw": {"ibus_ua": -132566, "vbus_uncal_avg_uv": 5077284, "ibus_uncal_avg_ua": -132767,
          "tail_layout": "line-averages", "tail_hex": "00 80 5A 06 A6 0B 02 00", "accel_status": null}
}

dashboard_label / dashboard_label_2 reproduce the two protocol lines on the meter's screen (here [N/A] and VOOC) using the meter firmware's own algorithm, named by dashboard_classifier. They describe the D+/D− voltage signature, not a confirmed protocol session. When the classifier is null (unknown or unanalysed firmware) the labels are unknown, not [N/A].

powerz measure --duration 2s

{
  "schema_version": 1, "serial": "050002", "firmware_version": "1.9.5", "firmware_error": null,
  "start": "2026-11-17T01:35:07.564Z", "end": "2026-11-17T01:35:09.565Z", "end_reason": "completed",
  "duration_s": 2, "integrated_s": 2, "interval_s": 0.1,
  "samples": 20, "failed_samples": 0, "last_error": null, "direction": "receptacle_to_plug",
  "stats": {
    "vbus_v":  {"min": 5.075507, "mean": 5.076038, "max": 5.076464, "last": 5.076093},
    "ibus_a":  {"min": 0.131757, "mean": 0.134602, "max": 0.140898, "last": 0.134642},
    "power_w": {"min": 0.668811, "mean": 0.683243, "max": 0.715156, "last": 0.683455},
    "temp_c":  {"min": 27.891, "mean": 27.907, "max": 27.914, "last": 27.906}
  },
  "energy_wh": 0.000379607, "charge_mah": 0.074784,
  "last": { …same shape as read… },
  "pd": {
    "messages": 0, "events": 0, "undecoded": 0, "source_capabilities": [], "last_request": null, "contract": null,
    "note": "no USB-PD activity was captured in this window; this is normal when nothing was connected or renegotiated (…) - reconnect the device during the capture to observe it",
    "records": []
  }
}

powerz info

{
  "schema_version": 1,
  "usb": {"manufacturer": "ChargerLab", "product": "POWER-Z KM003C", "serial": "050002", "bus": 2, "address": 20},
  "device": {"model": "KM003C", "firmware_version": "1.9.5", "firmware_date": "2025-01-07",
             "hardware_version": "2.2", "hardware_date": "2024-09-23", "serial": "050002",
             "uuid": "0123456789ABCDEF0123456789ABCDEF", "adc_tail_layout": "line-averages"},
  "settings": {"device_name": "POWER-Z", "sample_rate_sps": 50, "brightness_percent": 49, "rotation_code": 2,
               "auto_rotate": true, "language_code": 1, "theme_code": 0, "checksum_ok": true},
  "errors": []
}

powerz pd --duration 20s

One line per record, then a summary. PD records keep a fixed shape too: message fields are null on events and the other way round. A record looks like this:

{"schema_version":1,"time":"…","meter_time_ms":10000,"kind":"message","sop":"SOP","message":"Source_Capabilities",
 "class":"data","power_role":"source","data_role":"dfp","spec_revision":"3.x","message_id":0,"from_meter":false,
 "objects_hex":["0001912C","0002D12C"],
 "source_capabilities":[{"index":1,"type":"fixed","min_voltage_v":5,"max_voltage_v":5,"max_current_a":3,
   "max_current_20v_a":null,"max_power_w":15,"raw_hex":"0001912C","text":"Fixed 5.00V 3.00A (15.0W)"}, …],
 "request":null,"event":null,"cc_line":null,"param":null,"raw_hex":"…"}
{"schema_version":1,"kind":"summary","time":"…","end_reason":"completed","duration_s":20,"messages":0,"events":2,
 "undecoded":0,"source_capabilities":[],"last_request":null,"contract":null,
 "note":"the device was attached/detached during the capture (see events) but no USB-PD messages were exchanged: …"}

The record above is illustrative: no PD negotiation has been captured live yet. The summary line has the shape of real output. When measure or pd is stopped early, the same objects are printed with "end_reason":"interrupted" (exit 130) or "error" (the error's exit code).

6. Errors and exit codes

{"schema_version":1,"error":{"code":"busy","exit_code":4,"message":"km003c: meter is in use by another program (…)",
 "retryable":true,"hint":"another program holds the meter (…); retry, or pass --wait 10s to queue behind it"}}
{"schema_version":1,"error":{"code":"usage","exit_code":2,"message":"unknown command \"mesure\"",
 "retryable":false,"hint":"did you mean `powerz measure`? commands: devices, help, info, log, measure, pd, read, schema, version, watch"}}
exit_codecodeRetryableMeaning
0--Success
1errornoI/O or protocol failure
2usagenoUnknown command, bad flag or value (the hint lists valid flags and formats)
3not_foundnoNo meter connected (or none with --serial; the message lists connected serials). If the meter disappeared mid-run, measure/pd printed what they had (end_reason error)
4busyyesAnother process holds the meter; use --wait. If it was taken mid-run, measure/pd printed what they had
5timeoutyesThe meter did not answer in time
6permission_deniednoThe OS denied USB access (Linux udev)
7partialyesstdout JSON is valid but incomplete (failed_samples > 0, or info.errors not empty)
130interruptednoSIGINT / SIGTERM; measure and pd printed what they had collected (end_reason interrupted)

7. Agent recipes

How much power does the attached device draw?

powerz measure --duration 30s --wait 10s
# .stats.power_w.mean / .max (peak draw), .energy_wh over .integrated_s, .direction

What does this charger offer, and what did the device negotiate?

USB-PD is only exchanged when the device attaches or renegotiates, so start the capture first and connect the device during it:

powerz measure --duration 20s
# .pd.source_capabilities[]  offered PDOs (fixed/PPS/AVS: volts, amps, watts)
# .pd.contract               the Request the source accepted and confirmed with PS_RDY
# .pd.note                   set when nothing was captured
# .last.inferred.dashboard_label*  the meter's D+/D- protocol labels

Handling failures

8. Safety model

Every frame is checked against a whitelist (hardware/km003c/guard.go) right before it goes to the device. A fuzz test proves the whitelist accepts exactly these frames and nothing else:

Never sent: settings writes, factory reset, firmware/DFU commands, authentication, stream control, and the CDC text commands that make a charger raise VBUS. powerz cannot change the voltage on the bus. Ending each session with DISCONNECT means the meter does not queue an unsolicited frame for the next program.

Stall hazard: the meter stalls, and its watchdog reboots it, if a request arrives while an earlier reply or zero-length packet is still queued. powerz matches replies by transaction id, consumes the ZLP after MemoryRead data, and drains the endpoint after any failed exchange, after an idle gap and before closing. Fake-meter regression tests and fuzzing cover these paths.

9. Verified and caveats

View this page's source on GitHub