docs/zephyr/zephyr_charger.md - chromiumos/platform/ec - Git at Google

 # Zephyr EC Charger

 [TOC]

 ## Overview

 The charger chip enables an external power supply to provide power to the
 board's components.

 The charger depends on having a battery, so both the charging subsystem and
 battery must be configured together in the same change.

 ## Kconfig Options

 `CONFIG_PLATFORM_EC_CHARGER` enables charging support in the EC
 application. Refer to [Kconfig.charger] for all sub-options controlling charging
 behavior.

 Note: At least one charger IC must be enabled.

 Note: The charger chip configuration serves a different role than the USB
 charging configuration found in [Kconfig.usb_charger].

 ### Example of enabled configs

 Enable and disable charger configs in either the [`program.conf`] or
 [`project.conf`] file for your project.


 ```
 # Charger
 CONFIG_PLATFORM_EC_CHARGER=y
 CONFIG_EC_CHARGER_ISL9237=y
 # Charger sub-options
 CONFIG_PLATFORM_EC_CHARGE_RAMP_HW=y
 CONFIG_PLATFORM_EC_CHARGER_DISCHARGE_ON_AC=y
 CONFIG_PLATFORM_EC_CHARGER_DISCHARGE_ON_AC_CHARGER=y
 CONFIG_PLATFORM_EC_CHARGER_MIN_BAT_PCT_FOR_POWER_ON=2
 CONFIG_PLATFORM_EC_CHARGER_MIN_POWER_MW_FOR_POWER_ON=10000
 CONFIG_PLATFORM_EC_CHARGER_PROFILE_OVERRIDE=y
 CONFIG_PLATFORM_EC_CHARGER_PSYS=y
 CONFIG_PLATFORM_EC_CHARGER_PSYS_READ=y
 CONFIG_PLATFORM_EC_CHARGER_SENSE_RESISTOR=10
 CONFIG_PLATFORM_EC_CHARGER_SENSE_RESISTOR_AC=20
 CONFIG_PLATFORM_EC_CONSOLE_CMD_CHARGER_ADC_AMON_BMON=y
 ```

 ## Devicetree Nodes
 ### How to add a charger devicetree node

 #### Add charger node as child of `named-i2c-port`

 Example:

 ```
 named-i2c-ports {
    	compatible = "named-i2c-ports";
    	charger {
    		i2c-port = {ASSOCIATED PHANDLE};
 		/* Could be any name, but must correlate to "Board Specific Code" */
 		/* TODO(b/228237412): Update this comment once charger chg_chips[] is
 		 * created by a shim driver.
 		 */
    		enum-names = "I2C_PORT_CHARGER";
    	};
 };
 ```

 See the I2C doc on [mapping legacy I2C port numbers to Zephyr devicetree nodes]
 for more information on configuring the `named-i2c-port` node.

 ### How to create a new charger

 Add `vendor,part.yaml` to the [charger bindings directory]:

 Example Template:

 ```
 description: Vendor Part Charger IC

 compatible: "vendor,part"

 include: i2c-device.yaml

 ```
 See the [I2C doc](./zephyr_i2c.md) for more information on configuring I2C
 device bindings.

 ## Board Specific Code

 ### Define or append to the charger\_config\_t global array

 Example configuring an ISL923x charger chip:

 ```c
 const struct charger_config_t chg_chips[] = {
 	{
 		/* .i2c_port must match corresponding named-i2c-port child */
 		.i2c_port = I2C_PORT_CHARGER,

 		/* these may vary by vendor and part */
 		.i2c_addr_flags = ISL923X_ADDR_FLAGS,
 		.drv = &isl923x_drv,
 	},
 };
 ```

 <!-- TODO(b/228237412) - charger chips should be defined in code via DT
 macros. -->

 ## Threads

 Enabling `CONFIG_PLATFORM_EC_CHARGER` also enables the [charger thread]
 described by [Kconfig.tasks].

 ## Testing and Debugging a Flashed Board

 ### EC Console Commands

 Use the `charger` [EC console command] to inspect the the chip's details and
 status.

 Example output of `uart:~$ charger`:

 ```
 charger
   Name:   ISL9241
   Option: 10100000110000000000000100 (0x2830004)
   Man id: 0x0049
   Dev id: 0x000e
   V_batt: 13152 (  64 - 18304,   8)
   I_batt:  2364 (   4 -  6140,   4)
   I_in:    3000 (   4 -  6140,   4)
   I_dptf: disabled
 ```

 #### taskinfo

 Use the `taskinfo` [EC console command] to inspect if the charging task was
 enabled.

 Example output of `uart:~$ taskinfo`:

 ```
  Task Ready Name         Events      Time (s)  StkUsed
  0 R << idle >>       00000000 2055.869084   80/672
  1   HOOKS            00000000    5.215864  560/800
  2   CHG_RAMP         00000000    0.108705  424/672
  3   USB_CHG_P0       00000000    0.002139  368/672
  4   USB_CHG_P1       00000000    0.002132  368/672
  5   CHARGER          00000000   17.692626  488/928
  6 R MOTIONSENSE      80000002   50.203370  632/928
  7   KEYPROTO         00000000    0.008531  312/672
  8   CHIPSET          00000000    0.026394  528/800
  9   HOSTCMD          00000000    1.483327  600/800
 10 R CONSOLE          00000000    0.101999  448/928
 11   POWERBTN         00000000    0.001535  464/800
 12   KEYSCAN          00000000    1.144058  328/672
 13   PD_C0            00000000  176.510938  632/928
 14   PD_C1            00000000   73.909944  624/928
 15   PD_INT_C0        00000000    0.003969  472/672
 16   PD_INT_C1        00000000    0.025180  512/672
 ```

 #### pwr_avg

 Use the [pwr_avg] [EC console command] to see battery charging rates.

 #### chgstate

 Use the [chgstate] [EC console command] to debug and manipulate machine charging
 state.

 #### chgoverride

 Use the `chgoverride` [EC console command] to disable or force charging from a
 specific charging enabled port.
 See [Kconfig.charger] for configuring multiple charging ports.

 Use the [chgsup] command to view changes.

 #### chglim

 Use the `chglim` [EC console command] to set a max charger IC current and
 voltage charging limit.

 Use the [chgstate] command to view changes.

 #### chgsup

 Use the `chgsup` [EC console command] to get the status of the port that is the
 chosen charge supplier.

 Example output of `uart:~$ chgsup`:

 ```
 port=1, type=0, cur=3000mA, vtg=15000mV, lsm=1
 ```

 ### AP Console Commands (ectool)

 #### chargecurrentlimit

 Use the `chargecurrentlimit` [ectool] command to set the charge limit in
 milliamps.

 Usage output of `uart: # ectool chargecurrentlimit`:

 ```
 Usage: chargecurrentlimit <max_current_mA>
 ```

 Use the [chargestate] [ectool] command to view changes.

 #### chargecontrol

 Use the `chargecontrol` [ectool] command to set whether the board is idle,
 discharging, or resume normal operation.

 Usage output of `uart: # ectool chargecontrol`:

 ```
 Usage: chargecontrol <normal | idle | discharge>
 ```

 Use the [chargestate] [ectool] command to view changes.

 #### chargeoverride

 Use the `chargeoverride` [ectool] command to disable or force charging from a
 specific charging enabled port.
 See [Kconfig.charger] for configuring multiple charging ports.

 Usage output of `uart: # ectool chargeoverride`:

 ```
 Usage: chargeoverride <port# | dontcharge | off>
 ```

 Use the `power_supply_info` [developer console] command to view which port is
 acting as the charge supplier.

 Example:

 Usage output of `uart: # power_supply_info`:

 ```
 power_supply_info
 Device: Line Power
   path:                    /sys/class/power_supply/CROS_USBPD_CHARGER1
   online:                  yes
   type:                    USB
   enum type:               USB
   voltage (V):             4.512
   current (A):             Not available
   max voltage (V):         5
   max current (A):         3
   active source:           CROS_USBPD_CHARGER1 /* Port 1 is the charge supplier*/
   available sources:       CROS_USBPD_CHARGER0* [0/0], CROS_USBPD_CHARGER1* [0/0]
   supports dual-role:      yes
 Device: Battery
   path:                    /sys/class/power_supply/BAT0
   vendor:                  AS3GXAE
   model name:              C536-49
   state:                   Fully charged
   voltage (V):             13
   energy (Wh):             52.771
   energy rate (W):         0
   current (A):             0
   charge (Ah):             4.442
   full charge (Ah):        4.442
   full charge design (Ah): 4.8
   percentage:              100
   display percentage:      100
   technology:              Li-ion

 ```

 #### chargestate

 The [chargestate] command may also be invoked.

 <!-- Reference Links -->
 [EC console command]: https://chromium.googlesource.com/chromiumos/platform/ec/+/HEAD/README.md#useful-ec-console-commands
 [Kconfig.charger]: https://crsrc.org/o/src/platform/ec/zephyr/Kconfig.charger
 [Kconfig.tasks]: https://crsrc.org/o/src/platform/ec/zephyr/Kconfig.tasks?q=%22config%20HAS_TASK_CHARGER%22&ss=chromiumos
 [Kconfig.usb_charger]: https://crsrc.org/o/src/platform/ec/zephyr/Kconfig.usb_charger?q=%22config%20PLATFORM_EC_USB_CHARGER%22&ss=chromiumos
 [charger bindings directory]: https://crsrc.org/o/src/platform/ec/zephyr/dts/bindings/charger/
 [charger thread]: https://crsrc.org/o/src/platform/ec/common/charge_state.c?q=%22void%20charger_task%22&ss=chromiumos
 [chargestate]: ./zephyr_battery.md#chargestate
 [chgstate]: ./zephyr_battery.md#chgstate
 [chgsup]: #chgsup
 [developer console]: https://chromium.googlesource.com/chromiumos/platform2/+/HEAD/crosh#crosh-the-chromium-os-shell
 [ectool]: ../docs/ap-ec-comm.md
 [mapping legacy I2C port numbers to Zephyr devicetree nodes]: ./zephyr_i2c.md#mapping-legacy-i2c-port-numbers-to-zephyr-devicetree-nodes
 [pwr_avg]: ./zephyr_battery.md#pwr_avg
 [`program.conf`]: ./project_config.md#program_conf
 [`project.conf`]: ./project_config.md#project_conf
	# Zephyr EC Charger

	[TOC]

	## Overview

	The charger chip enables an external power supply to provide power to the
	board's components.

	The charger depends on having a battery, so both the charging subsystem and
	battery must be configured together in the same change.

	## Kconfig Options

	`CONFIG_PLATFORM_EC_CHARGER` enables charging support in the EC
	application. Refer to [Kconfig.charger] for all sub-options controlling charging
	behavior.

	Note: At least one charger IC must be enabled.

	Note: The charger chip configuration serves a different role than the USB
	charging configuration found in [Kconfig.usb_charger].

	### Example of enabled configs

	Enable and disable charger configs in either the [`program.conf`] or
	[`project.conf`] file for your project.


	```
	# Charger
	CONFIG_PLATFORM_EC_CHARGER=y
	CONFIG_EC_CHARGER_ISL9237=y
	# Charger sub-options
	CONFIG_PLATFORM_EC_CHARGE_RAMP_HW=y
	CONFIG_PLATFORM_EC_CHARGER_DISCHARGE_ON_AC=y
	CONFIG_PLATFORM_EC_CHARGER_DISCHARGE_ON_AC_CHARGER=y
	CONFIG_PLATFORM_EC_CHARGER_MIN_BAT_PCT_FOR_POWER_ON=2
	CONFIG_PLATFORM_EC_CHARGER_MIN_POWER_MW_FOR_POWER_ON=10000
	CONFIG_PLATFORM_EC_CHARGER_PROFILE_OVERRIDE=y
	CONFIG_PLATFORM_EC_CHARGER_PSYS=y
	CONFIG_PLATFORM_EC_CHARGER_PSYS_READ=y
	CONFIG_PLATFORM_EC_CHARGER_SENSE_RESISTOR=10
	CONFIG_PLATFORM_EC_CHARGER_SENSE_RESISTOR_AC=20
	CONFIG_PLATFORM_EC_CONSOLE_CMD_CHARGER_ADC_AMON_BMON=y
	```

	## Devicetree Nodes
	### How to add a charger devicetree node

	#### Add charger node as child of `named-i2c-port`

	Example:

	```
	named-i2c-ports {
	compatible = "named-i2c-ports";
	charger {
	i2c-port = {ASSOCIATED PHANDLE};
	/* Could be any name, but must correlate to "Board Specific Code" */
	/* TODO(b/228237412): Update this comment once charger chg_chips[] is
	* created by a shim driver.
	*/
	enum-names = "I2C_PORT_CHARGER";
	};
	};
	```

	See the I2C doc on [mapping legacy I2C port numbers to Zephyr devicetree nodes]
	for more information on configuring the `named-i2c-port` node.

	### How to create a new charger

	Add `vendor,part.yaml` to the [charger bindings directory]:

	Example Template:

	```
	description: Vendor Part Charger IC

	compatible: "vendor,part"

	include: i2c-device.yaml

	```
	See the [I2C doc](./zephyr_i2c.md) for more information on configuring I2C
	device bindings.

	## Board Specific Code

	### Define or append to the charger\_config\_t global array

	Example configuring an ISL923x charger chip:

	```c
	const struct charger_config_t chg_chips[] = {
	{
	/* .i2c_port must match corresponding named-i2c-port child */
	.i2c_port = I2C_PORT_CHARGER,

	/* these may vary by vendor and part */
	.i2c_addr_flags = ISL923X_ADDR_FLAGS,
	.drv = &isl923x_drv,
	},
	};
	```

	<!-- TODO(b/228237412) - charger chips should be defined in code via DT
	macros. -->

	## Threads

	Enabling `CONFIG_PLATFORM_EC_CHARGER` also enables the [charger thread]
	described by [Kconfig.tasks].

	## Testing and Debugging a Flashed Board

	### EC Console Commands

	Use the `charger` [EC console command] to inspect the the chip's details and
	status.

	Example output of `uart:~$ charger`:

	```
	charger
	Name: ISL9241
	Option: 10100000110000000000000100 (0x2830004)
	Man id: 0x0049
	Dev id: 0x000e
	V_batt: 13152 ( 64 - 18304, 8)
	I_batt: 2364 ( 4 - 6140, 4)
	I_in: 3000 ( 4 - 6140, 4)
	I_dptf: disabled
	```

	#### taskinfo

	Use the `taskinfo` [EC console command] to inspect if the charging task was
	enabled.

	Example output of `uart:~$ taskinfo`:

	```
	Task Ready Name Events Time (s) StkUsed
	0 R << idle >> 00000000 2055.869084 80/672
	1 HOOKS 00000000 5.215864 560/800
	2 CHG_RAMP 00000000 0.108705 424/672
	3 USB_CHG_P0 00000000 0.002139 368/672
	4 USB_CHG_P1 00000000 0.002132 368/672
	5 CHARGER 00000000 17.692626 488/928
	6 R MOTIONSENSE 80000002 50.203370 632/928
	7 KEYPROTO 00000000 0.008531 312/672
	8 CHIPSET 00000000 0.026394 528/800
	9 HOSTCMD 00000000 1.483327 600/800
	10 R CONSOLE 00000000 0.101999 448/928
	11 POWERBTN 00000000 0.001535 464/800
	12 KEYSCAN 00000000 1.144058 328/672
	13 PD_C0 00000000 176.510938 632/928
	14 PD_C1 00000000 73.909944 624/928
	15 PD_INT_C0 00000000 0.003969 472/672
	16 PD_INT_C1 00000000 0.025180 512/672
	```

	#### pwr_avg

	Use the [pwr_avg] [EC console command] to see battery charging rates.

	#### chgstate

	Use the [chgstate] [EC console command] to debug and manipulate machine charging
	state.

	#### chgoverride

	Use the `chgoverride` [EC console command] to disable or force charging from a
	specific charging enabled port.
	See [Kconfig.charger] for configuring multiple charging ports.

	Use the [chgsup] command to view changes.

	#### chglim

	Use the `chglim` [EC console command] to set a max charger IC current and
	voltage charging limit.

	Use the [chgstate] command to view changes.

	#### chgsup

	Use the `chgsup` [EC console command] to get the status of the port that is the
	chosen charge supplier.

	Example output of `uart:~$ chgsup`:

	```
	port=1, type=0, cur=3000mA, vtg=15000mV, lsm=1
	```

	### AP Console Commands (ectool)

	#### chargecurrentlimit

	Use the `chargecurrentlimit` [ectool] command to set the charge limit in
	milliamps.

	Usage output of `uart: # ectool chargecurrentlimit`:

	```
	Usage: chargecurrentlimit <max_current_mA>
	```

	Use the [chargestate] [ectool] command to view changes.

	#### chargecontrol

	Use the `chargecontrol` [ectool] command to set whether the board is idle,
	discharging, or resume normal operation.

	Usage output of `uart: # ectool chargecontrol`:

	```
	Usage: chargecontrol <normal \| idle \| discharge>
	```

	Use the [chargestate] [ectool] command to view changes.

	#### chargeoverride

	Use the `chargeoverride` [ectool] command to disable or force charging from a
	specific charging enabled port.
	See [Kconfig.charger] for configuring multiple charging ports.

	Usage output of `uart: # ectool chargeoverride`:

	```
	Usage: chargeoverride <port# \| dontcharge \| off>
	```

	Use the `power_supply_info` [developer console] command to view which port is
	acting as the charge supplier.

	Example:

	Usage output of `uart: # power_supply_info`:

	```
	power_supply_info
	Device: Line Power
	path: /sys/class/power_supply/CROS_USBPD_CHARGER1
	online: yes
	type: USB
	enum type: USB
	voltage (V): 4.512
	current (A): Not available
	max voltage (V): 5
	max current (A): 3
	active source: CROS_USBPD_CHARGER1 /* Port 1 is the charge supplier*/
	available sources: CROS_USBPD_CHARGER0* [0/0], CROS_USBPD_CHARGER1* [0/0]
	supports dual-role: yes
	Device: Battery
	path: /sys/class/power_supply/BAT0
	vendor: AS3GXAE
	model name: C536-49
	state: Fully charged
	voltage (V): 13
	energy (Wh): 52.771
	energy rate (W): 0
	current (A): 0
	charge (Ah): 4.442
	full charge (Ah): 4.442
	full charge design (Ah): 4.8
	percentage: 100
	display percentage: 100
	technology: Li-ion

	```

	#### chargestate

	The [chargestate] command may also be invoked.

	<!-- Reference Links -->
	[EC console command]: https://chromium.googlesource.com/chromiumos/platform/ec/+/HEAD/README.md#useful-ec-console-commands
	[Kconfig.charger]: https://crsrc.org/o/src/platform/ec/zephyr/Kconfig.charger
	[Kconfig.tasks]: https://crsrc.org/o/src/platform/ec/zephyr/Kconfig.tasks?q=%22config%20HAS_TASK_CHARGER%22&ss=chromiumos
	[Kconfig.usb_charger]: https://crsrc.org/o/src/platform/ec/zephyr/Kconfig.usb_charger?q=%22config%20PLATFORM_EC_USB_CHARGER%22&ss=chromiumos
	[charger bindings directory]: https://crsrc.org/o/src/platform/ec/zephyr/dts/bindings/charger/
	[charger thread]: https://crsrc.org/o/src/platform/ec/common/charge_state.c?q=%22void%20charger_task%22&ss=chromiumos
	[chargestate]: ./zephyr_battery.md#chargestate
	[chgstate]: ./zephyr_battery.md#chgstate
	[chgsup]: #chgsup
	[developer console]: https://chromium.googlesource.com/chromiumos/platform2/+/HEAD/crosh#crosh-the-chromium-os-shell
	[ectool]: ../docs/ap-ec-comm.md
	[mapping legacy I2C port numbers to Zephyr devicetree nodes]: ./zephyr_i2c.md#mapping-legacy-i2c-port-numbers-to-zephyr-devicetree-nodes
	[pwr_avg]: ./zephyr_battery.md#pwr_avg
	[`program.conf`]: ./project_config.md#program_conf
	[`project.conf`]: ./project_config.md#project_conf