Introduction
Acroname's USBHub3c industrial USB Hub (plus the PD Logger add-on feature) can generate and capture arbitrary Vendor-Defined Messages (VDMs), enabling scalable automated testing, debugging, configuration, and deployment of USB-C devices.
USB Power Delivery (USB PD) uses the Configuration Channel (CC) lines for host-device communication, including negotiation of power, roles, and Alternate Modes. VDMs are special PD messages that allow device manufacturers to control additional functions such as firmware updates, diagnostics, and device configuration.
VDMs come in two types:
- Structured VDMs: standardized messages in the USB PD specification used for device identity, cable discovery, alternate mode negotiation, and event signaling. Here, the term "vendor" in VDM includes standardization bodies such as VESA (for DisplayPort).
- Unstructured VDMs: vendor-specific payloads, often proprietary and not publicly documented. To know how these unstructured messages are formed, you'll want to:
- Use vendor developer documentation (usually requires an NDA)
- Reverse engineer through PD Logging with a device like USBHub3c
- Be the vendor, hopefully you can track down the internal documentation
- Rely on exiting community knowledge
Two main challenges come up when working with PD / VDMs:
- No OS support for sending arbitrary VDMs: Standard OS USB host stacks expose high-level interfaces for power roles and alt-mode selection but do not provide direct access to raw PD packets.
- PD / VDMs are point-to-point: CC-line messaging can't pass through conventional USB hubs, making it hard to parallelize operations.
USBHub3c solves these problems with the ability to generate and receive arbitrary VDMs across all six ports, enabling simultaneous automated testing across multiple devices.
Advantages of USBHub3c for VDM Testing
- Parallelization: Simultaneously inject and monitor PD/VDM traffic across multiple ports.
- Automation: BrainStem API provides simple scripting interface
- Detailed Logging: Captures PD / VDM exchanges for debugging and verification.
- Port automation: Quickly switch among hosts and devices, virtually plug and unplug connections.
Real-world Applications for USBHub3c + VDM Control
- Automated Firmware Provisioning
- Trigger DFU/bootloader modes (Apple, STM32, etc.) and update firmware or OS images.
- Device Configuration & Alternate‑Mode Management
- Enter or exit alternate modes (DisplayPort, Thunderbolt, USB4) using structured VDMs.
- Enable and test vendor-specific modes.
- Extended‑Power Negotiation & Charger Validation
- Test proprietary > 100 W profiles such as Dell 130 W and Lenovo 135 W that rely on VDM handshakes.
- Exercise VDM-enabled fast‑charging and PPS modes (Google Pixel, Samsung Galaxy)
- Diagnostics, Telemetry & Debugging
- Send VDMs that put a device into diagnostic mode, request logs, or enable self‑test.
- End‑of‑Line (EOL) & Interoperability Testing
- Verify a product’s VDM implementation (e.g. Discover Identity, Enter Mode, vendor‑specific commands) across multiple cables, power adapters, and hosts.
- Automate soak tests that repeatedly negotiate Alt Modes, extended‑power states, or debug modes, with or without virtual unplug cycles.
Real-World Example: Automating Apple DFU Mode
Apple’s Device Firmware Update (DFU) mode allows firmware update and OS deployment on MacBooks. Typically, entering DFU mode is entered manually with key combinations on boot, or via a point-to-point connection between DFU-enabled ports on a host and target MacBook. USBHub3c automates and scales up this process, enabling deployment without manual intervention across multiple Macs.
If you're specifically wanting to perform DFU-mode updates and looking for higher-level tools, check out our DFU Automator / Configurator shortcuts or Two Canoe's DFU Blaster Pro.
Code Example
Below is a Python example using the BrainStem API to reboot a connected MacBook into DFU mode. The DFU-mode VDM can be replaced with any specific message you would like to send. The target Mac's DFU-enabled port should be connected via USB-C cable to port 1.
To send VDMs with the BrainStem Python API, messages must include:
- A routing word indicating the Start of Packet (SOP).
- A structured VDM header specifying the vendor ID, message type, and command.
- The payload containing vendor-specific data.
import sys
import brainstem
from brainstem.result import Result
from brainstem.stem import USBHub3c
from brainstem import _BS_C
# Create USBHub3c object and connect
hub = USBHub3c()
if hub.discoverAndConnect(brainstem.link.Spec.USB) != Result.NO_ERROR:
print("Could not find USBHub3c – exiting")
sys.exit(1)
serial = hub.system.getSerialNumber().value
print(f"Connected to USBHub3c 0x{serial:08X}")
# VDM Commands are a minimum of 8 bytes chunked into 4-byte blocks
# First 4 bytes are SOP (Start of Packet)
# 0 = SOP
# 1 = SOP'
# 2 = SOP''
# 3 = SOP' Debug
# 4 = SOP'' Debug
# Second 4 bytes are the VDM header according to the USB PD Standard
# Any subsequent sets of 4 bytes are the attached VDO's
# Apple DFU-mode VDM sequence (little-endian)
dfu_vdm = [
0x04, 0x00, 0x00, 0x00, # Routing word – SOP'' debug for Apple DFU Mode
0x12, 0x80, 0xAC, 0x05, # VDM header – Apple VID 0x05AC, command 0x12
0x06, 0x01, 0x00, 0x00, # Payload – DFU trigger
0x00, 0x00, 0x01, 0x80 # Additional DFU flags
]
# Send VDM on port 1
err = hub.pd[1].set_UEIBytes(_BS_C.powerdeliveryVDM, dfu_vdm)
print(f"DFU VDM sent to Port 1, result: {err}")
hub.disconnect()Code Explanation:
- discoverAndConnect(): Locates and connects to the USBHub3c device.
- Start-of-Packet routing word: Indicates sending via SOP'' Debug
- VDM header: Apple's Vendor ID (VID) and the DFU command.
- Payload: Apple-specific bytes to trigger DFU mode.
- set_UEIBytes(): Sends the VDM via the designated port’s CC line.
Why SOP'' Debug?
Apple uses special SOP'' Debug messages for DFU Mode commands (if sending from a Downward-Facing Port (DFP) that is providing power). Normal VDMs from a DFP to a device would use SOP message. Much more information is on the Asahi Linux Wiki.
Logging with HubTool
We can view the sent message and response in real time in the HubTool application's PD Logging tab. Messages are time-stamped and show raw bytes along with message type and other details.
The DFU-mode VDM is on line 2 (TX) and the device's response is on line 4 (RX)
Conclusion
USBHub3c sends and receives USB PD messages—including custom VDMs—across all ports. This enables scalable interactive or automated workflows for configuration, updates, functional / interoperability testing, and device provisioning.
Add New Comment