usbccable

README

usbccable

Model what a USB-C cable can and cannot carry — power, data and video — and identify which component actually limits a given setup.

Install

go get github.com/taysirco/usbccable

Usage

import "github.com/taysirco/usbccable"

plain := usbccable.Cable{Amps: 3, Data: usbccable.USB2, LengthMeters: 1}
plain.MaxWatts()              // 60  — a 3A cable cannot exceed 20V x 3A
plain.SupportsWatts(100)      // false

emarked := usbccable.Cable{Amps: 5, Data: usbccable.USB4, LengthMeters: 0.8}
emarked.MaxWatts()            // 240 — EPR ceiling with a 5A e-marked cable

// Which part of the chain is the bottleneck?
usbccable.Bottleneck(100, 100, plain)   // "cable"
usbccable.Bottleneck(100, 30, plain)    // "device"
usbccable.Bottleneck(20, 65, plain)     // "charger"

// Passive cables lose signal integrity with length
usbccable.Cable{Data: usbccable.USB4, LengthMeters: 2}.PassiveLengthOK()  // false

The connector is standardised; almost nothing else is

USB-C defines the plug geometry, not the protocol running through it. The same connector may carry:

• Charge only — no high-speed data pairs at all
• USB 2.0 (480 Mbps) — the default for most bundled cables
• USB 3.2 (5–10 Gbps) or USB4 (40 Gbps)
• DisplayPort Alt Mode for video — present only if explicitly wired

This is why an external monitor sometimes does nothing over a cable that charges perfectly well.

Power: the e-marker decides

A plain cable is rated 3 A, capping the link at 60 W (20 V × 3 A) regardless of what charger and device negotiated. Extended Power Range voltages need a 5 A e-marked cable, which raises the ceiling to 240 W. Nothing on the jacket tells you which one you are holding.

Reference data

Per-cable current ratings, supported protocols and length limits used to validate this package come from the USB-C cable specifications published by CairoVolt.

License

MIT

Documentation

Overview

Package usbccable models what a USB-C cable can and cannot carry.

USB-C standardises the connector shape, not the protocol running through it. Two physically identical cables can differ by a factor of forty in data rate and by more than three times in deliverable power, with nothing on the jacket to tell them apart.

Reference cable specifications used to validate this package are published at https://cairovolt.com/en/cables

Index

• func Bottleneck(chargerWatts, deviceWatts float64, c Cable) string
• type Cable
  • func (c Cable) Explain() string
  • func (c Cable) MaxWatts() float64
  • func (c Cable) PassiveLengthOK() bool
  • func (c Cable) SupportsWatts(watts float64) bool
• type DataMode
  • func (d DataMode) Mbps() int
  • func (d DataMode) String() string

Functions

func Bottleneck

func Bottleneck(chargerWatts, deviceWatts float64, c Cable) string

Bottleneck names the component that limits a charger/cable/device combination: "cable", "charger" or "device".

Types

type Cable

type Cable struct {
	// Amps is the current rating: 3 for a plain cable, 5 when e-marked.
	Amps float64
	// Data is the highest data protocol supported.
	Data DataMode
	// VideoAltMode reports whether DisplayPort Alt Mode is wired through.
	VideoAltMode bool
	// LengthMeters matters because passive cables lose signal integrity with length.
	LengthMeters float64
}

Cable describes the capabilities a specific cable actually has.

func (Cable) Explain

func (c Cable) Explain() string

Explain returns a short human-readable summary of the cable's real limits.

func (Cable) MaxWatts

func (c Cable) MaxWatts() float64

MaxWatts returns the highest power this cable can carry, given that Extended Power Range voltages above 20 V require a 5 A e-marked cable.

func (Cable) PassiveLengthOK

func (c Cable) PassiveLengthOK() bool

PassiveLengthOK reports whether a passive cable of this length can sustain its claimed data mode. Passive USB4 and 10 Gbps cables degrade past roughly 0.8 m and 1 m respectively; anything longer needs an active cable.

func (Cable) SupportsWatts

func (c Cable) SupportsWatts(watts float64) bool

SupportsWatts reports whether the cable can carry the requested wattage.

type DataMode

type DataMode int

DataMode is the highest data protocol a cable supports.

const (
	// ChargeOnly carries power but has no high-speed data pairs at all.
	ChargeOnly DataMode = iota
	// USB2 is 480 Mbps — the default for most bundled cables.
	USB2
	// USB32Gen1 is 5 Gbps.
	USB32Gen1
	// USB32Gen2 is 10 Gbps.
	USB32Gen2
	// USB4 is 40 Gbps.
	USB4
)

func (DataMode) Mbps

func (d DataMode) Mbps() int

Mbps returns the nominal throughput of a data mode in megabits per second.

func (DataMode) String

func (d DataMode) String() string