whatcable-macos-usb-inspector

# WhatCable macOS USB-C Inspector > Skill by [ara.so](https://ara.so) — Daily 2026 Skills collection. WhatCable is a macOS 14+ menu bar app (Swift/SwiftUI) that reads IOKit services to surface what each USB-C cable plugged into your Mac can actually do — speed, power rating, e-marker data, PDO profiles, and connected device identity — in plain English. ## Project Structure ``` Sources/WhatCable/ ├── WhatCableApp.swift # App entry point, menu bar setup ├── ContentView.swift # Main popover UI ├── PortSummary.swift # Plain-English logic per port ├── PDVDO.swift # PD VDO bit-twiddling / spec decoding ├── IOKitReader.swift # IOKit service queries └── ... scripts/ └── build-app.sh # Universal binary + notarisation ``` ## Install / Build ```bash # Run locally (development) swift run WhatCable # Build distributable universal app (arm64 + x86_64) ./scripts/build-app.sh # → dist/WhatCable.app # → dist/WhatCable.zip ``` Requires Swift 5.9 / Xcode 15+, macOS 14 (Sonoma) or later. ### Signed + Notarised Build ```bash cp .env.example .env # Edit .env: # DEVELOPER_ID="Developer ID Application: Your Name (TEAMID)" # NOTARY_PROFILE="WhatCable-notary" # Store notarytool credentials once xcrun notarytool store-credentials "WhatCable-notary" \ --apple-id "$APPLE_ID" \ --team-id "$TEAM_ID" \ --password "$APP_SPECIFIC_PASSWORD" ./scripts/build-app.sh ``` ## Key Concepts ### IOKit Service Families | Service | Purpose | |---|---| | `AppleHPMInterfaceType10/11/12` (M3+) | Per-port state, transports, plug orientation, e-marker presence | | `AppleTCControllerType10` (M1/M2) | Same, older HPM interface | | `IOPortFeaturePowerSource` | Full PDO list + live negotiated PDO | | `IOPortTransportComponentCCUSBPDSOP` | PD Discover Identity VDOs (SOP = partner, SOP' = cable e-marker) | ### USB PD VDO Decoding (PDVDO.swift) The core bit-twiddling follows USB Power Delivery 3.x spec. Cable e-marker VDOs encode speed and current in specific bit fields. ```swift // Example: decode cable speed from Passive Cable VDO struct PassiveCableVDO { let raw: UInt32 // Bits [5:3] — USB SuperSpeed signalling support var usbSSSignalling: UInt8 { UInt8((raw >> 3) & 0b111) } var dataRate: String { switch usbSSSignalling { case 0b000: return "USB 2.0 only" case 0b001: return "USB 3.2 Gen 1 (5 Gbps)" case 0b010: return "USB 3.2 Gen 2 (10 Gbps)" case 0b011: return "USB 3.2 Gen 2x2 / USB4 Gen 2 (20 Gbps)" case 0b100: return "USB4 Gen 3 (40 Gbps)" default: return "Unknown" } } // Bits [6:5] — VBUS current handling var currentCapability: String { switch (raw >> 5) & 0b11 { case 0b00: return "USB Type-C Default (≤3A)" case 0b01: return "3A" case 0b10: return "5A" default: return "Reserved" } } } ``` ### Reading IOKit Properties ```swift import IOKit func readPortProperties(serviceName: String) -> [String: Any]? { var iterator: io_iterator_t = 0 let matchDict = IOServiceMatching(serviceName) guard IOServiceGetMatchingServices(kIOMainPortDefault, matchDict, &iterator) == KERN_SUCCESS else { return nil } defer { IOObjectRelease(iterator) } var service = IOIteratorNext(iterator) var results: [String: Any] = [:] while service != 0 { defer { IOObjectRelease(service) service = IOIteratorNext(iterator) } if let props = copyProperties(service) { results.merge(props) { _, new in new } } } return results.isEmpty ? nil : results } private func copyProperties(_ service: io_service_t) -> [String: Any]? { var propsRef: Unmanaged<CFMutableDictionary>? guard IORegistryEntryCreateCFProperties(service, &propsRef, kCFAllocatorDefault, 0) == KERN_SUCCESS, let props = propsRef?.takeRetainedValue() as? [String: Any] else { return nil } return props } ``` ### Port Summary Plain-English Logic (PortSummary.swift) ```swift enum PortHeadline: String { case thunderbolt = "Thunderbolt / USB4" case usbDevice = "USB device connected" case chargingOnly = "Charging only" case slowCable = "Slow USB / charge-only cable" case nothing = "Nothing connected" } struct PortSummary { let headline: PortHeadline let chargingDiagnostic: String? let dataRate: String? let currentRating: String? let negotiatedPDO: PDO? let allPDOs: [PDO] static func from(ioKitProps: [String: Any]) -> PortSummary { let hasThunderbolt = ioKitProps["Thunderbolt"] as? Bool ?? false let hasUSB3 = ioKitProps["USB3"] as? Bool ?? false let isConnected = ioKitProps["Connected"] as? Bool ?? false let emarkerPresent = ioKitProps["CableEMarker"] as? Bool ?? false let headline: PortHeadline if !isConnected { headline = .nothing } else if hasThunderbolt { headline = .thunderbolt } else if hasUSB3 { headline = .usbDevice } else if emarkerPresent { headline = .chargingOnly } else { headline = .slowCable } // Parse PDOs for charging diagnostic let pdos = parsePDOs(from: ioKitProps) let negotiated = pdos.first(where: { $0.isActive }) let diagnostic = buildChargingDiagnostic(pdos: pdos, negotiated: negotiated) return PortSummary( headline: headline, chargingDiagnostic: diagnostic, dataRate: emarkerPresent ? decodeDataRate(ioKitProps) : nil, currentRating: emarkerPresent ? decodeCurrentRating(ioKitProps) : nil, negotiatedPDO: negotiated, allPDOs: pdos ) } } ``` ### PDO Parsing (Power Data Objects) ```swift struct PDO { let voltage: Double // Volts let maxCurrent: Double // Amps let maxWatts: Double // voltage * maxCurrent let isActive: Bool static func parse(raw: UInt32, isActive: Bool) -> PDO? { // Fixed supply PDO: bits [19:10] = max current (10mA units), // bits [29:20] = voltage (50mV units) let currentRaw = (raw >> 10) & 0x3FF let voltageRaw = (raw >> 20) & 0x3FF guard voltageRaw > 0 else { return nil } let voltage = Double(voltageRaw) * 0.05 let current = Double(currentRaw) * 0.01 return PDO( voltage: voltage, maxCurrent: current, maxWatts: voltage * current, isActive: isActive ) } } func parsePDOs(from props: [String: Any]) -> [PDO] { guard let pdoArray = props["PDOs"] as? [UInt32], let activePDOIndex = props["ActivePDOIndex"] as? Int else { return [] } return pdoArray.enumerated().compactMap { idx, raw in PDO.parse(raw: raw, isActive: idx == activePDOIndex) } } ``` ### SwiftUI Popover Pattern (ContentView.swift) ```swift import SwiftUI struct ContentView: View { @StateObject private var model = CableModel() var body: some View { VStack(alignment: .leading, spacing: 0) { HeaderView() Divider() ScrollView { VStack(alignment: .leading, spacing: 12) { ForEach(model.ports) { port in PortRowView(port: port) } } .padding() } } .frame(width: 360) .onAppear { model.refresh() } } } struct PortRowView: View { let port: PortSummary var body: some View { VStack(alignment: .leading, spacing: 4) { Label(port.headline.rawValue, systemImage: iconName(for: port.headline)) .font(.headline) if let diagnostic = port.chargingDiagnostic { Text(diagnostic) .font(.subheadline) .foregroundStyle(.secondary) } if let rate = port.dataRate { Text("Speed: \(rate)") .font(.caption) } } .padding(.vertical, 6) } func iconName(for headline: PortHeadline) -> String { switch headline { case .thunderbolt: return "bolt.fill" case .usbDevice: return "cable.connector" case .chargingOnly: return "battery.100.bolt" case .slowCable: return "exclamationmark.triangle" case .nothing: return "circle.dashed" } } } ``` ### Menu Bar App Setup (WhatCableApp.swift) ```swift import SwiftUI @main struct WhatCableApp: App { @NSApplicationDelegateAdaptor(AppDelegate.self) var appDelegate var body: some Scene { // No WindowGroup — pure menu bar app Settings { SettingsView() } } } class AppDelegate: NSObject, NSApplicationDelegate { var statusItem: NSStatusItem? var popover = NSPopover() func applicationDidFinishLaunching(_ notification: Notification) { NSApp.setActivationPolicy(.accessory) // hide from Dock by default statusItem = NSStatusBar.system.statusItem(withLength: NSStatusItem.variableLength) if let button = statusItem?.button { button.image = NSImage(systemSymbolName: "cable.connector", accessibilityDescription: "WhatCable") button.action = #selector(togglePopover) button.sendAction(on: [.leftMouseUp, .rightMouseUp]) } popover.contentViewController = NSHostingController(rootView: ContentView()) popover.behavior = .transient } @objc func togglePopover(_ sender: NSStatusBarButton) { if popover.isShown { popover.performClose(sender) } else { if let button = statusItem?.button { popover.show(relativeTo: button.bounds, of: button, preferredEdge: .minY) } } } } ``` ### Charging Diagnostic Helper ```swift func buildChargingDiagnostic(pdos: [PDO], negotiated: PDO?) -> String? { guard let active = negotiated else { return nil } let maxAvailable = pdos.map(\.maxWatts).max() ?? 0 let activeW = active.maxWatts let ratio = maxAvailable > 0 ? activeW / maxAvailable : 1.0 if ratio < 0.5 { return String(format: "Charging at %.0fW (charger can do up to %.0fW)", activeW, maxAvailable) } else if ratio < 0.9 { return String(format: "Cable is limiting charging speed (%.0fW of %.0fW available)", activeW, maxAvailable) } else { return String(format: "Charging well at %.0fW", activeW) } } ``` ## Common Patterns ### Adding a New Port Property 1. Read the raw value from IOKit props in `IOKitReader.swift` 2. Decode it (bit-fields) in `PDVDO.swift` or a dedicated decoder 3. Expose it on `PortSummary` struct 4. Display it in `PortRowView` or a detail expansion in `ContentView.swift` ### Handling Different Mac Generations ```swift let hpmServiceNames = [ "AppleHPMInterfaceType12", // M3-era "AppleHPMInterfaceType11", "AppleHPMInterfaceType10", "AppleTCControllerType10", // M1 / M2 ] func findHPMService() -> io_service_t { for name in hpmServiceNames { let service = IOServiceGetMatchingService( kIOMainPortDefault, IOServiceMatching(name) ) if service != IO_OBJECT_NULL { return service } } return IO_OBJECT_NULL } ``` ### Debug / Engineer Mode (⌥-click) ```swift @State private var showRawProps = false // In button handler: if NSEvent.modifierFlags.contains(.option) { showRawProps.toggle() } // In view: if showRawProps, let props = port.rawIOKitProperties { RawPropertiesView(props: props) } ``` ## Troubleshooting | Symptom | Likely Cause | Fix | |---|---|---| | No ports shown | IOKit service name mismatch | Try all `hpmServiceNames` variants; check `ioreg -l` output | | E-marker data missing | Cable has no e-marker chip | Expected for cables < 60W; only marked cables have VDOs | | PDO list empty | Device not PD-capable or port is source-only | Check `IOPortFeaturePowerSource` presence in `ioreg` | | Build fails on Intel | Architecture flag missing | Use `./scripts/build-app.sh` for universal build | | Gatekeeper warning | Ad-hoc signature only | Set `DEVELOPER_ID` in `.env` and re-run build script | | Wrong wattage shown | PD 3.2 EPR AVS PDO format | EPR PDOs use different bit layout; check PD 3.2 spec §6.4.1 | ### Inspect IOKit Live ```bash # Dump all HPM interface properties ioreg -l -n AppleHPMInterfaceType10 | less # Watch for USB-C connect/disconnect events ioreg -w 0 -l -c IOUSBDevice | grep -E "Product|Vendor|Speed" # Check power delivery objects ioreg -l | grep -A 20 IOPortFeaturePowerSource ``` ### Key IOKit Property Names to Watch ```swift // Connection state "Connected" // Bool "PlugOrientation" // Int (0 = unflipped, 1 = flipped) // Transports "USB2" // Bool "USB3" // Bool "Thunderbolt" // Bool "DisplayPort" // Bool // E-marker "CableEMarker" // Bool "CableVDO" // UInt32 — raw passive cable VDO "ActiveCableVDO1" // UInt32 — active cable VDO // Power "PDOs" // [UInt32] "ActivePDOIndex" // Int "NegotiatedWatts" // Double ```