Power Delivery Entity

API Documentation: [cpp] [python] [.NET] [CCA] [REST]

Power Delivery or PD is a power specification which allows more charging options and device behaviors within the USB interface. This Entity will allow you to directly access the vast landscape of PD.

When the capabilities of a PD system are fully realized everything in the system is “smart”. That includes the device, the host and even the cable. All of these elements contain electronics that identify themselves and what they are capable of doing. Because of this complexity it is important to align on a few terms that will be used throughout this Entity.

Partner This refers to the side of the PD connection in question. The possible options for this parameter are.

  • Local Indicates the context/perspective of the Acroname device you are communicating with through a BrainStem connection.

  • Remote The context/perspective of anything other than the Acroname device.

Partner Type

Value

Define

Local

0

powerdeliveryPartnerLocal

Remote

1

powerdeliveryPartnerRemote

Power Role Indicates the direction of power. This value is typically used in the context of a “Partner”. i.e. The remote partner is sinking, which would mean the local partner is sourcing. The possible options for this context are:

  • Sink Indicates that the partner is taking power in/from.

  • Source Indicates that the partner is providing power out/to.

Power Roles are also used in the context of what a port is capable of doing.

  • Sink Device is capable of consuming power.

  • Source Device is capable of producing power.

  • Sink/Source Device is capable of both consuming or producing power. Dual Role Port (DRP)

Power Role

Value

Define

Disabled

0

powerdeliveryPowerRoleDisabled

Source

1

powerdeliveryPowerRoleSource

Sink

2

powerdeliveryPowerRoleSink

Source/Sink

3

powerdeliveryPowerRoleSourceSink

Power Data Objects (PDO)

  • PDO’s define what a device is capable of doing in the world of Power Delivery. PDO’s are bit packed integers defined by the PD Specification which vary in meaning based on the type of PDO.

Request Data Objects (RDO)

  • RDO’s are the final agreement after successful Power Delivery negotiations. This RDO is always sent by the sinking device and is the result of the sources advertised PDO’s and the needs/requirements of the sinking device. Only one RDO exists per valid connection.

Connection State (Get)

pd[x] . getConnectionState => (unsigned char) state

Gets the type of connection as defined by the Power Delivery Specification. The most common connections types are: Not Attached, Sourcing and Sinking.

Power Data Object (Get/Set)

pd[x] . getPowerDataObject => (unsigned int) pdo
pd[x] . setPowerDataObject <= (unsigned int) pdo

Gets and Sets the PDO for a given pd[x] instance, partner and power role.

For any one connection there are 4 locations in which PDOs exist: Remote Sink, Remote Source, Local Sink, and Local Source. Within each of PDO locations up to 7 PDOs can be defined.

Set calls are only allowed on Local Partner assuming the BrainStem device supports this feature.

Number of Power Data Objects (Get)

pd[x] . getNumberOfPowerDataObjects => (unsigned int) pdoCount

As previously stated 7 PDO’s can be defined per location; however, it is only required that there be 1. This API allows you the get the number of PDO’s available for a given partner and power role.

Reset Power Data Objects (Set)

pd[x] . resetPowerDataObjectToDefault => (void)

Resets the local partner PDO for a given power role and index.

Power Data Object List (Get)

pd[x] . getPowerDataObjectList => (unsigned int [MAX_PDOS]) list

Returns a list of all PDOs for a given pd[x] instance. This is equivalent to calling getPowerDataObject on all possible configurations.

Power Data Objects Enabled (Get/Set)

pd[x] . getPowerDataObjectEnabled => (unsigned char) enable
pd[x] . setPowerDataObjectEnabled <= (unsigned char) enable

Acroname products which support this feature can selectively enable and disable its local PDO’s. In that, if the local source location has 7 PDO’s, the user could disable all but the first PDO from being advertised by disabling them.

Power Data Object Enabled List (Get)

pd[x] . getPowerDataObjectEnabledList => (unsigned char) enableList

Convenience function to getPowerDataObjectEnabled. Returns a bit packed representation of the PDO enabled status.

Request Data Object (Get/Set)

pd[x] . getRequestDataObject => (unsigned int) rdo
pd[x] . setRequestDataObject <= (unsigned int) rdo

Gets and Sets the RDO for a given pd[x] instance and partner

Set calls are only possible on a local sinking partner assuming the BrainStem device supports this feature.

Power Role (Get/Set)

pd[x] . getPowerRole => (unsigned char) role
pd[x] . setPowerRole <= (unsigned char) role

The power role defines the type of PD connections the device supports. Devices can be disabled, sinking, sourcing or dual role ports (capable of sinking or sourcing).

Power Role Preferred (Get/Set)

pd[x] . getPowerRolePreferred => (unsigned char) role
pd[x] . setPowerRolePreferred <= (unsigned char) role

Dual role port typically have a preference of whether they are sinking or sourcing. For instance battery powered devices typically prefer to sink power since they have a finite amount of battery power; however, many of them can source power if requested to do so.

Cable Voltage Maximum (Get)

pd[x] . getCableVoltageMax => (unsigned char) voltage

Returns the maximum amount of voltage the attached cable is capable of handling. This information is defined in the emark of the cable and is used during PD negotiations for PDO compatibility.

Cable Current Maximum (Get)

pd[x] . getCableCurrentMax => (unsigned char) current

Returns the maximum amount of current the attached cable is capable of handling. This information is defined in the emark of the cable and is used during PD negotiations for PDO compatibility.

Cable Speed Maximum (Get)

pd[x] . getCableSpeedMax => (unsigned char) speed

Returns the maximum speed the attached cable is capable of handling. This information is defined in the emark of the cable.

Cable Type (Get)

pd[x] . getCableType => (unsigned char) cable

Returns whether the cable is active or passive and if it is emarked.

Cable Type Options

Value

Name

Description

0

Invalid

Invalid or unknown cable type

1

Passive

Passive cable (no active electronics)

2

Active

Active cable (contains active electronics)

Cable Orientation (Get)

pd[x] . getCableOrientation => (unsigned char) orientation

Indicates which side of the connection is being used for PD negotiations. This is based on physical CC strapping within the cable.

Request (Set)

pd[x] . request <= (unsigned char) request

Allows access to specific requests which are built into the PD specification. It is important to remember that these are requests and are not guaranteed to occur. Examples are resets, power, data, and VCONN role swaps.

Requests

Request

Value

Define

Hard Reset

0

pdRequestHardReset

Soft Reset

1

pdRequestSoftReset

Data Reset

2

pdRequestDataReset

Power Role Swap

3

pdRequestPowerRoleSwap

Power Fast Role Swap

4

pdRequestPowerFastRoleSwap

Data Role Swap

5

pdRequestDataRoleSwap

Vconn Swap

6

pdRequestVconnSwap

Sink GoTo Minimum

7

pdRequestSinkGoToMinimum

Remote Source Power Data Objects

8

pdRequestRemoteSourcePowerDataObjects

Remote Sink Power Data Objects

9

pdRequestRemoteSinkPowerDataObjects

Remote Source Extended Capabilities

10

pdRequestRemoteSourceExtendedCapabilities

Remote Sink Extended Capabilities

11

pdRequestRemoteSinkExtendedCapabilities

Status

12

pdRequestStatus

PPS Status

13

pdRequestPPSStatus

Battery Capabilities

14

pdRequestBatteryCapabilities

Battery Status

15

pdRequestBatteryStatus

Manufacturer Info Sop

16

pdRequestManufacturerInfoSop

Manufacturer Info Sop’

17

pdRequestManufacturerInfoSopp

Manufacturer Info Sop’’

18

pdRequestManufacturerInfoSoppp

Discover Identity Sop

19

pdRequestDiscoverIdentitySop

Discover Identity Sop’

20

pdRequestDiscoverIdentitySopp

Discover Identity Sop’’

21

pdRequestDiscoverIdentitySoppp

Revision

22

pdRequestRevision

Request Status (Get)

pd[x] . requestStatus => (unsigned char) status

Returns the most recent status for a given pd[x] instance. This is usually paired with the request command since they are not guaranteed and are asynchronous.

Flag Mode (Get/Set)

pd[x] . getFlagMode => (unsigned char) mode
pd[x] . setFlagMode <= (unsigned char) mode

Allows get and set of a flag configuration for a given USB Power Delivery Flag. The following flags can be configured to the following different modes:

Flags

Flag

Value

Define

Dual Role Data

1

pdFlagDualRoleData

Dual Role Power

2

pdFlagDualRolePower

Unconstrained Power

3

pdFlagUnconstrainedPower

Suspend Possible

4

pdFlagSuspendPossible

USB Com Possible

5

pdFlagUSBComPossible

Unchunked Message Support

6

pdFlagUnchunkedMessageSupport

Higher Capability

7

pdFlagHigherCapability

Capability Mismatch

8

pdFlagCapabilityMismatch

Giveback Flag

9

pdFlagGivebackFlag
Modes

Mode

Value

Description

Disabled

0

Flag will always report 0

Enabled

1

Flag will always report 1

Auto

2

Flag will show 0 or 1 correctly according to the rest of the hubs state/config

Override (Get/Set)

pd[x] . getOverride => (unsigned int) overrides
pd[x] . setOverride <= (unsigned int) overrides

Returns or sets the override configuration for the Power Delivery connection. Overrides allow bypassing certain Power Delivery protocol behaviors for testing or special applications.

Override Options

Bit

Name

Description

0

CableCurrent

overrides the cable current limiting to 3A unless it’s an emarked cable

1

PortPower

Overrides the port power budgetting and just allows full power always

2

AutoDiscovery

Overrides the auto discovery feature. With override true the hub will only establish a basic power connection and wont ask for additional vendor information.

3

DataPathDisable

Override normal disabling of the data path when the PD Data Role and port configured data role differ

Attach Time Elapsed (Get)

pd[x] . getAttachTimeElapsed => (unsigned int [2]) elapsed

Returns how long the port has been attached, as two unsigned integers: seconds, then microseconds.

Power Role Capabilities (Get)

pd[x] . getPowerRoleCapabilities => (unsigned char) capabilities

Returns the power roles that the local partner may advertise (for example from CC strapping).

Data Role Capabilities (Get)

pd[x] . getDataRoleCapabilities => (unsigned char) capabilities

Returns the data roles that the local partner may advertise.

Protocol Revision Maximum (Get/Set)

pd[x] . getProtocolRevisionMax => (unsigned int) revision
pd[x] . setProtocolRevisionMax <= (unsigned int) revision

Gets or sets the maximum USB Power Delivery protocol revision used as a negotiation ceiling (for example Rev 2 vs Rev 3 constants such as pdProtocolRevision2 and pdProtocolRevision3 in protocol headers). This value constrains how the stack advertises protocol revision during negotiation; it is not the product hardware revision or firmware build number. Only valid API revision values for your release should be written; invalid values may be rejected or clamped by firmware.

Peak Current Configuration (Get/Set)

pd[x] . getPeakCurrentConfiguration => (unsigned char) configuration
pd[x] . setPeakCurrentConfiguration <= (unsigned char) configuration

Gets or sets the peak current configuration for the local source partner. Peak current configuration describes allowable overload tolerance relative to the advertised maximum current.

Fast Role Swap Current (Get/Set)

pd[x] . getFastRoleSwapCurrent => (unsigned char) current
pd[x] . setFastRoleSwapCurrent <= (unsigned char) current

Gets or sets the fast-role-swap current parameter for the local sink: the current the sink needs available to complete a successful fast role swap.