typec

README

USB Type-C Power Delivery Module for Go

At the moment, only sink functionality is implemented. Sink refers to a power consumer. You can use the module to request specific voltage and current from USB-C power source such as wall adapters, power banks and more.

Goals:

• Easy to use, understand and modify.
• Familiar to Go programmers.
• Efficient resource utilization so it can run on microcontrollers and in embedded environments.
• Compatibility with various port controller hardware.

Non-goals:

• Following standard word for word.
• Implementing all PD functionality.

There are examples in the examples directory to get you started.

Note that the timing requirements of PD messaging is rather strict. As such, in environments where communication latency is high, it may not be possible to implement a working program. For example, on a linux desktop using the MCP2221 I2C bridge to communicate with FUSB302 PD port controller, each I2C transaction latency is too high (~10ms) for things to work. Your mileage may vary.

Documentation

Overview

Package typec defines high level interfaces and types for implementing a full USB Type-C power delivery stack.

Index

• Variables
• type Event
  • func (e *Event) Add(v Event)
  • func (e Event) Has(v Event) bool
  • func (e *Event) Pop() Event
  • func (e Event) String() string
• type PortController

Variables

var (
	// ErrTxFailed is returned by Tx() if all auto-retries have failed.
	ErrTxFailed = errors.New("failed to send pd message")

	// ErrRxEmpty is returned by Rx() if no more messages are left to read.
	ErrRxEmpty = errors.New("no more messages to read")
)

Types

type Event

type Event uint16

Event can store multiple events and return them in priority order.

const (
	EventResetReceived Event = 1 << iota // Hard reset received
	EventSendReset                       // Request to send hard reset signal to port partner
	EventPower0A5                        // 5V@0.5A non-PD power source
	EventPower1A5                        // 5V@1.5A non-PD power source
	EventPower3A0                        // 5V@3A non-PD power source
	EventAttached                        // VBUS power detected
	EventDetached                        // VBUS power lost
	EventRx                              // Received a message
	EventTimerTimeout                    // Active timer has timed out
)

The events are listed in order of priority from highest to lowest. This means that in presence of multiple pending events, highest priority one is attended to first.

const EventNone Event = 0

EventNone represents no event.

func (*Event) Add

func (e *Event) Add(v Event)

Add adds the events v to the set.

func (Event) Has

func (e Event) Has(v Event) bool

Has returns true if the event v is set without clearing it.

func (*Event) Pop

func (e *Event) Pop() Event

Pop returns the next high priority event and clears it.

func (Event) String

func (e Event) String() string

type PortController

type PortController interface {

	// Init (re-)initializes the state of the controller to a known initial
	// working state. Init must be called at least once and before any other
	// method of this interface. It may be called multiple times thereafter to
	// bring the controller back to its initial state (for instance after a
	// reset).
	Init() error

	// Tx sends a power delivery message to the port partner. CRC is
	// automatically calculated and appended to the header and the data. Tx will
	// block until a GoodCRC response is received or all auto-retries have
	// failed. ErrTxFailed will be returned if auto-retries fail. Alert must be
	// called after each call to Tx to check for possible events generated as
	// result of the call to Tx.
	Tx(pdmsg.Message) error

	// Rx returns a single received message. If no messages are left, ErrRxEmpty
	// is returned. Rx does not return GoodCRC messages and instead, discards
	// them internally. Alert must be called after each call to Rx to check for
	// possible events generated as result of the call to Rx.
	Rx() (pdmsg.Message, error)

	// SendReset sends a hard reset message to the port partner and blocks until
	// send is complete. Alert must be called after each call to SendReset to
	// check for possible events generated as result of the call to SendReset.
	SendReset() error

	// Alert is called by the policy engine either periodically or as a result of
	// hardware/software interrupts, to let the port conroller know it needs to
	// check on the hardware status/interrupts. It must also be called after each
	// call to Tx, Rx and SendReset.
	//
	// Port controller can respond with list of events resulting from processing
	// of interrupts. If the controller generates events outside of Alert(), it
	// must cache those and return them on the next Alert() call.
	Alert() (Event, error)
}

PortController provides an interface to operate a device, often an IC such as FUSB302, in USB Power Delivery sink mode only. The implementer must handle the physical and some protocol layer of the USB Power Delivery as detailed below.

Sink port controllers must:

• Handle entirety of Atomic Message Sequence from the protocol layer all the way to physical layer. This includes starting CRCReceiveTimer, GoodCRC message ID matching, retries, etc. Message ID counters are tracked in the policy engine however.
• Configure the port for sink operation after Init is called.
• Detect and set correct CC polarity upon attachment.
• Detect and report host current provided by the source as EventPower* events.

Port controllers should try to avoid heap allocation after initialization stage as much as possible, since they may be running on microcontrollers with limited/expensive garbage collectors.