WhatCable

WhatCable: A Friendly Guide to USB-C’s Hidden Powers on macOS

Latest release Platform: macOS 14+ License: MIT

Introduction: Why a Tool for a Universal Connector

USB-C is designed to do many things with a single connector: power delivery, high-speed data, video output, and even complex negotiation between chargers, cables, and devices. But all those capabilities can be hard to infer just by looking at a cable in your drawer. A USB-C cable that looks identical to another can be a world apart in what it can actually do. WhatCable is a macOS menu bar app that translates the often-opaque USB-C landscape into plain English, per port on your Mac. It explains what the cable is actually delivering, why your Mac might be charging slowly, and which parts of the chain are limiting performance.

WhatCable surfaces the information already exposed by macOS via IOKit, but presents it in a friendly, real-time popover. It tells you not only whether you’re charging, but whether the cable, charger, or device is the bottleneck; it decodes the PD (Power Delivery) and e-marker data to give a clear view of capabilities and limits. The app is designed with engineers in mind who want to drill into the details, while still remaining accessible to anyone curious about why their port behaves the way it does.

What It Shows: A Per-Port Snapshot in Plain English

WhatCable isn’t content with a single metric. It presents a structured view for each physical USB-C port on your Mac, summarizing multiple dimensions of the connection:

• At-a-glance headline

• Thunderbolt / USB4

• USB device

• Charging only

• Slow USB / charge-only cable

• Nothing connected

• Charging diagnostic

• When something is plugged in, a banner calls out the bottleneck:

• “Cable is limiting charging speed” (cable rated below charger)

• “Charging at 30W (charger can do up to 96W)” (Mac is requesting less, e.g. battery near full)

• “Charging well at 96W” (everything matches)

• Cable e-marker info

• The cable’s actual speed (USB 2.0, 5/10/20/40/80 Gbps)

• Current rating (3A / 5A up to 60W / 100W / 240W)

• The chip’s vendor

• Charger PDO list

• Every voltage profile the charger advertises (5V / 9V / 12V / 15V / 20V…), with the currently negotiated profile highlighted in real time

• Connected device identity

• Vendor name and product type decoded from the PD Discover Identity response

• Attached USB devices

• Storage drives, hubs, peripherals listed under the port, along with their negotiated speed

• Active transports

• USB 2 / USB 3 / Thunderbolt / DisplayPort

• ⌥-click (Option-click) details

• Flip the menu bar icon to reveal the underlying IOKit properties for engineers

• Settings-driven refinements

• Hide empty ports

• Launch at login

• Run as a regular Dock app instead of a menu bar icon

• Get notifications when cables are connected or disconnected

• Quick nerd-friendly access

• Right-click the menu bar icon for: Refresh, Keep window open, Check for Updates, About, WhatCable on GitHub, and Quit

The Popover in Action

The WhatCable popover is the central, user-friendly interface. It’s designed to be glanceable yet informative, with color cues and concise language that makes the underlying technology approachable. It translates the notoriously technical PD landscape into plain-English explanations so you can quickly decide whether a cable is “good enough” for your needs, or if you’ve run into a bottleneck you can address.

Install and Get Started: Ready-to-Run on macOS Sonoma (and Beyond)

WhatCable is distributed as a universal macOS app that runs on Apple silicon and Intel Macs with a few important prerequisites and notes:

• Platform and compatibility

• Requires macOS 14 (Sonoma) or later

• Apple Silicon: supported

• Intel: not supported in terms of USB-C PD state exposure; the cable e-marker data isn’t exposed through public IOKit access, so WhatCable can’t surface the same data on Intel hardware

• How to install

• Download the latest WhatCable.zip from the Releases page

• Unzip and drag WhatCable.app into /Applications

• The app is signed with a Developer ID and notarised by Apple, so Gatekeeper warnings are minimized on supported macOS versions

• Run modes and behavior

• The app is a menu bar app by default, but there is a path to run as a regular Dock app if desired

• The manual install includes the whatcable CLI binary bundled inside the .app

• The CLI can be run from the shell either by symlinking or via Homebrew

• Homebrew installation (recommended for ease)

• brew tap darrylmorley/whatcable

• brew install --cask whatcable

• This installs the menu bar app and symlinks the whatcable CLI into your PATH

• Important notes about availability

• The command-line interface is packaged alongside the app

• The CLI is not automatically on the PATH unless installed via Homebrew or symlinked manually

• On manual installs, you can symlink the CLI:

  • ln -s /Applications/WhatCable.app/Contents/Helpers/whatcable /usr/local/bin/whatcable

• What it requires from the system

• Access to IOKit-based information about ports, PD, and e-marker data

• No entitlements, no private APIs, and no background daemons

Command-Line Interface: Power to Scripting and Demos

WhatCable ships with a CLI that mirrors the same diagnostic engine as the GUI. It’s designed for power users, automation, or demos where you want to stream data or integrate it into a shell workflow:

• Basic usage

• whatcable

• What it outputs: a human-readable summary of every port

• Structured output

• whatcable --json

• Produces JSON that can be piped into jq for filtering and processing

• Live updates

• whatcable --watch

• Streams updates as cables are connected or disconnected (Ctrl+C to stop)

• Raw data

• whatcable --raw

• Includes underlying IOKit properties for deeper debugging

• Version and help

• whatcable --version

• whatcable --help

• How to access the CLI if you installed manually

• The binary lives at WhatCable.app/Contents/Helpers/whatcable

• Symlink it into PATH to use it from the shell

• If you install via Homebrew

• The Homebrew install handles the PATH integration automatically, so you can call whatcable directly from any shell

WhatCable’s Architecture: How It Dives into USB-C PD and E-Markers

WhatCable does not rely on hacks or hidden APIs. It reads four families of IOKit services to assemble a coherent picture of each port’s capabilities and state:

• AppleHPMInterfaceType10/11/12 and AppleTCControllerType10/11

• Provide per-port state: connection status, transport types, plug orientation, and e-marker presence

• Notably, Type11 is what the M2 MacBook Air uses for MagSafe 3 ports

• IOPortFeaturePowerSource

• Supplies the full Power Delivery Object (PDO) list from the connected source

• Highlights the “winning” PDO that the system is currently negotiating

• IOPortTransportComponentCCUSBPDSOP

• Exposes PD Discover Identity VDOs for both the port partner (SOP) and the cable e-marker (SOP’)

• XHCI controller subtree

• Maps every connected USB device to its physical port via the UsbIOPort registry path

• On machines that don’t expose UsbIOPort, the mapping falls back to a bus-index derived from the controller’s locationID

Cable Speed, Power, and Negotiation: The PD Decoder

WhatCable decodes the PD negotiation and cables against the USB Power Delivery 3.x specification. It translates the negotiation messages into actionable data:

• Cable speed and data rate

• USB 2.0, 5/10/20/40/80 Gbps speeds

• Power rating

• Current rating possibilities: 3A, 5A

• Power levels up to 60W / 100W / 240W depending on cable and charger capabilities

• Vendor information

• The chip’s vendor is identified where possible, enabling quick recognition of familiar brands

• Real-time status

• The currently negotiated voltage and current are shown, so you can gauge how well a charger, cable, and device are aligned

Build from Source: Developing with WhatCable

If you want to tinker with WhatCable or contribute improvements, you can build from source using Swift and Xcode:

• Quick build for a local test

• swift run WhatCable # menu bar app

• swift run whatcable-cli # CLI

• Requirements

• Swift 5.9 (Xcode 15+)

• Building a distributable .app

• Use the provided script to produce a universal app and a signed, notarised distribution:

• ./scripts/build-app.sh

• This generates dist/WhatCable.app (arm64 + x86_64) and dist/WhatCable.zip

• Release workflow (high level)

• One-time: create a release notes file (e.g., v0.5.3.md)

• Run the release script with the version

• The wrapper handles: version bump, build, sign, notarise, smoke tests, and catapulting a GitHub release

• Notarisation workflow can involve notarytool credentials and Developer ID signing steps

• Gatekeeper considerations: ad-hoc signing works locally but not on other Macs, whereas a fully notarised distribution is gatekeeper-friendly

• One-time setup for full notarisation (high-level steps)

• Identify a codesigning identity

• Store notary credentials in the keychain

• Create a .env file with DEVELOPERID and NOTARYPROFILE settings for automation

Caveats, Limitations, and Reality Checks

Every tool has its limitations, and WhatCable is no exception:

• E-marker visibility is limited

• Cable e-marker information only appears for cables that carry one. Most USB-C cables under 60 W are not marked.

• Trust in the e-marker

• WhatCable reads the e-marker data directly from the cable’s plug, assuming the chip is honest

• Counterfeit or mis-flashed cables can advertise capabilities they do not deliver; software cannot verify the inside of the jacket

• PD specification coverage

• The decoder targets PD 3.0 / 3.1

• PD 3.2 EPR variants may require tweaks as real data is observed

• Vendor name lookup

• The lookup table covers common vendors; unfamiliar devices may fall back to the hex VID

• macOS and hardware limitations

• macOS-only; iOS sandboxing and access constraints make USB-C e-marker access harder on other platforms

• Apple Silicon is required for full surface reflection of USB-C state. Intel Macs may not expose the same diagnostic data due to constraints in the Thunderbolt 3 controller driver

• Not on the App Store

• App Sandbox restrictions and IOKit access in the App Store environment would block the necessary reads

Contributing: How to Help and Where to Start

If you’re interested in contributing, the codebase is approachable and well-commented. Start with the areas that handle the UI, or drill into the core decoding logic:

• UI and presentation

• Sources/WhatCable/ContentView.swift contains the user interface and the per-port presentation logic

• Plain-English logic

• Sources/WhatCableCore/PortSummary.swift handles the human-readable descriptions

• PD decoding and VDO handling

• Sources/WhatCableCore/PDVDO.swift contains the bit-twiddling and interpretation of PD identity data

• Shared diagnostic engine

• WhatCableCore is shared by the menu bar app and the whatcable CLI (in Sources/WhatCableCLI/)

Credits: Built with Passion for Clarity

WhatCable was built by Darryl Morley. It’s the product of listening to frequent questions about cable quality and capabilities—“is this cable any good?” This project pursues the goal of turning technical probes into approachable, actionable information. The design intention is to empower users with real, live diagnostics that help them understand why devices charge slowly or why a particular cable or charger doesn’t seem to meet expectations.

Beyond the README: The Bigger Picture

USB-C is a single connector that hides a spectrum of technologies beneath a uniform surface. WhatCable aims to bring transparency to that spectrum. For developers, it demonstrates a practical use of macOS’ IOKit services to surface per-port state, PD identities, e-marker details, and the nuances of USB data transfers and video transports. For everyday users, it translates complexity into straightforward guidance: is the cable the bottleneck? Is the charger delivering the right voltage? Is the device pulling more current than the cable can safely handle? Is everything aligned for maximum performance, or is there a mismatch that you should address?

A Quick Recap of WhatCable’s Strengths

• Clear, per-port summaries that cover charging, data speeds, and device types
• Real-time identification of bottlenecks in charging scenarios
• Deep dives into e-marker data, PD voltages, and negotiated profiles
• Practical guidance for engineers via accessible IOKit details when needed
• A CLI that mirrors the GUI for scripting, automation, and demos
• An open-source approach that invites community improvements and transparency

Closing Thoughts: Why This Matters

USB-C is ubiquitous, and its promises are only as good as the cables and chargers behind it. WhatCable doesn’t just tell you that something is “wrong” or “right.” It explains what the system is actually doing, why it’s choosing certain voltages or currents, and where the uncertainties lie. In a landscape defined by negotiation and hardware variations, a tool that makes the negotiation audible—and visible—matters. It makes a complex interface feel familiar, whether you’re a curious user, a hardware enthusiast, or a developer desiring to peek under the hood.

If you’re curious to explore more, check out the project on GitHub and try WhatCable on a macOS Sonoma machine. The journey into USB-C’s capabilities is intricate, but WhatCable aims to make it navigable, reliable, and, most importantly, understandable.