1.. _usb_bc12_api:
2
3BC1.2 Devices (Experimental)
4#######################################
5
6The Battery Charging specification, currently at revision 1.2, is commonly
7referred to as just BC1.2. BC1.2 defines limits and detection mechanisms for USB
8devices to draw current exceeding the USB 2.0 specification limit of 0.5A, 2.5W.
9
10The BC1.2 specification uses the term Charging Port for the device that supplies
11VBUS on the USB connection and the term Portable Device for the device that
12sinks current from the USB connection.
13
14Note that the `BC1.2 Specification`_ uses the acronym PD for Portable Device. This
15should not be confused with the USB-C Power Delivery, which also uses the
16acronym PD.
17
18On many devices, BC1.2 is the fallback mechanism to determine the connected
19charger capability on USB type C ports when the attached type-C partner does not
20support Power Delivery.
21
22Key parameters from the `BC1.2 Specification`_ include:
23
24============================================================  ========  ===========
25Parameter                                                     Symbol    Range
26============================================================  ========  ===========
27Allowed PD (portable device) Current Draw from Charging Port  IDEV_CHG  1.5 A
28Charging Downstream Port Rated Current                        ICDP      1.5 - 5.0 A
29Maximum Configured Current when connected to a SDP            ICFG_MAX  500 mA
30Dedicated Charging Port Rated Current                         IDCP      1.5 - 5.0 A
31Suspend current                                               ISUSP     2.5 mA
32Unit load current                                             IUNIT     100 mA
33============================================================  ========  ===========
34
35While the ICDP and IDCP rated currents go up to 5.0 A, the BC1.2 current is
36limited by the IDEV_CHG parameter. So the BC1.2 support is capped at 1.5 A in
37the Zephyr implementation when using portable-device mode.
38
39.. _BC1.2 Specification: https://www.usb.org/document-library/battery-charging-v12-spec-and-adopters-agreement
40
41Basic Operation
42***************
43
44The BC1.2 device driver provides only two APIs, ``bc12_set_role()`` and
45``bc12_set_result_cb()``.
46
47The application calls ``bc12_set_role()`` to transition the BC1.2 device to
48either a disconnected, portable-device, or charging port mode.
49
50For the disconnected state, the BC1.2 driver powers down the detection chip.
51The power down operation is vendor specific.
52
53The application calls ``bc12_set_role()`` with the type set to
54BC12_PORTABLE_DEVICE when both the following conditions are true:
55
56* The application configured the port as an upstream facing port, i.e. a USB
57  device port.
58* The application detects VBUS on the USB connection.
59
60For portable-device mode, the BC1.2 driver powers up the detection chip and
61starts charger detection. At completion of the charger detection, the BC1.2
62driver notifies the callback registered with ``bc12_set_result_cb()``. By
63default, the BC1.2 driver clamps the current to 1.5A to comply with the BC1.2
64specification.
65
66To comply with the USB 2.0 specification, when the driver detects a SDP
67(Standard Downstream Port) charging partner or if BC1.2 detection fails, the
68driver reports the available current as ISUSP (2.5 mA). The application may
69increase the current draw to IUNIT (100 mA) when the connected USB host resumes
70the USB bus and may increase the current draw to ICFG_MAX (500 mA) when the USB
71host configures the USB device.
72
73Charging port mode is used by the application when the USB port is configured as
74a downstream facing port, i.e. a USB host port. For charging port mode, the
75BC1.2 driver powers up the detection chip and configures the charger type
76specified by a devicetree property. If the driver supports detection of plug and
77and unplug events, the BC1.2 driver notifies the callback registered with
78``bc12_set_result_cb()`` to indicate the current connection state of the
79portable device partner.
80
81Configuration Options
82*********************
83
84Related configuration options:
85
86* :kconfig:option:`CONFIG_USB_BC12`
87
88.. _bc12_api_reference:
89
90API Reference
91*************
92
93.. doxygengroup:: b12_interface
94.. doxygengroup:: b12_emulator_backend
95