1# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
2%YAML 1.2
3---
4$id: http://devicetree.org/schemas/power/supply/battery.yaml#
5$schema: http://devicetree.org/meta-schemas/core.yaml#
6
7title: Battery Characteristics
8
9maintainers:
10  - Sebastian Reichel <sre@kernel.org>
11
12description: |
13  The devicetree battery node provides static battery characteristics.
14  In smart batteries, these are typically stored in non-volatile memory
15  on a fuel gauge chip. The battery node should be used where there is
16  no appropriate non-volatile memory, or it is unprogrammed/incorrect.
17
18  Upstream dts files should not include battery nodes, unless the battery
19  represented cannot easily be replaced in the system by one of a
20  different type. This prevents unpredictable, potentially harmful,
21  behavior should a replacement that changes the battery type occur
22  without a corresponding update to the dtb.
23
24  Battery properties are named, where possible, for the corresponding elements
25  in enum power_supply_property, defined in include/linux/power_supply.h
26
27  Batteries must be referenced by chargers and/or fuel-gauges using a phandle.
28  The phandle's property should be named "monitored-battery".
29
30properties:
31  compatible:
32    const: simple-battery
33
34  device-chemistry:
35    description: This describes the chemical technology of the battery.
36    oneOf:
37      - const: nickel-cadmium
38      - const: nickel-metal-hydride
39      - const: lithium-ion
40        description: This is a blanket type for all lithium-ion batteries,
41          including those below. If possible, a precise compatible string
42          from below should be used, but sometimes it is unknown which specific
43          lithium ion battery is employed and this wide compatible can be used.
44      - const: lithium-ion-polymer
45      - const: lithium-ion-iron-phosphate
46      - const: lithium-ion-manganese-oxide
47
48  over-voltage-threshold-microvolt:
49    description: battery over-voltage limit
50
51  re-charge-voltage-microvolt:
52    description: limit to automatically start charging again
53
54  voltage-min-design-microvolt:
55    description: drained battery voltage
56
57  voltage-max-design-microvolt:
58    description: fully charged battery voltage
59
60  energy-full-design-microwatt-hours:
61    description: battery design energy
62
63  charge-full-design-microamp-hours:
64    description: battery design capacity
65
66  trickle-charge-current-microamp:
67    description: current for trickle-charge phase
68
69  precharge-current-microamp:
70    description: current for pre-charge phase
71
72  precharge-upper-limit-microvolt:
73    description: limit when to change to constant charging
74
75  charge-term-current-microamp:
76    description: current for charge termination phase
77
78  constant-charge-current-max-microamp:
79    description: maximum constant input current
80
81  constant-charge-voltage-max-microvolt:
82    description: maximum constant input voltage
83
84  factory-internal-resistance-micro-ohms:
85    description: battery factory internal resistance
86
87  resistance-temp-table:
88    description: |
89      An array providing the temperature in degree Celsius
90      and corresponding battery internal resistance percent, which is used to
91      look up the resistance percent according to current temperature to get an
92      accurate batterty internal resistance in different temperatures.
93
94  ocv-capacity-celsius:
95    description: |
96      An array containing the temperature in degree Celsius,
97      for each of the battery capacity lookup table.
98
99  operating-range-celsius:
100    description: operating temperature range of a battery
101    items:
102      - description: minimum temperature at which battery can operate
103      - description: maximum temperature at which battery can operate
104
105  ambient-celsius:
106    description: safe range of ambient temperature
107    items:
108      - description: alert when ambient temperature is lower than this value
109      - description: alert when ambient temperature is higher than this value
110
111  alert-celsius:
112    description: safe range of battery temperature
113    items:
114      - description: alert when battery temperature is lower than this value
115      - description: alert when battery temperature is higher than this value
116
117required:
118  - compatible
119
120patternProperties:
121  '^ocv-capacity-table-[0-9]+$':
122    $ref: /schemas/types.yaml#/definitions/uint32-matrix
123    description: |
124      An array providing the open circuit voltage (OCV)
125      of the battery and corresponding battery capacity percent, which is used
126      to look up battery capacity according to current OCV value. And the open
127      circuit voltage unit is microvolt.
128    maxItems: 100
129    items:
130      items:
131        - description: open circuit voltage (OCV) in microvolts
132        - description: battery capacity percent
133          maximum: 100
134
135additionalProperties: false
136
137examples:
138  - |
139    power {
140      #address-cells = <1>;
141      #size-cells = <0>;
142
143      battery: battery {
144        compatible = "simple-battery";
145        over-voltage-threshold-microvolt = <4500000>;
146        re-charge-voltage-microvolt = <250000>;
147        voltage-min-design-microvolt = <3200000>;
148        voltage-max-design-microvolt = <4200000>;
149        energy-full-design-microwatt-hours = <5290000>;
150        charge-full-design-microamp-hours = <1430000>;
151        precharge-current-microamp = <256000>;
152        precharge-upper-limit-microvolt = <2500000>;
153        charge-term-current-microamp = <128000>;
154        constant-charge-current-max-microamp = <900000>;
155        constant-charge-voltage-max-microvolt = <4200000>;
156        factory-internal-resistance-micro-ohms = <250000>;
157        ocv-capacity-celsius = <(-10) 0 10>;
158        /* table for -10 degree Celsius */
159        ocv-capacity-table-0 = <4185000 100>, <4113000 95>, <4066000 90>;
160        /* table for 0 degree Celsius */
161        ocv-capacity-table-1 = <4200000 100>, <4185000 95>, <4113000 90>;
162        /* table for 10 degree Celsius */
163        ocv-capacity-table-2 = <4250000 100>, <4200000 95>, <4185000 90>;
164        resistance-temp-table = <20 100>, <10 90>, <0 80>, <(-10) 60>;
165        operating-range-celsius = <(-30) 50>;
166        ambient-celsius = <(-5) 50>;
167        alert-celsius = <0 40>;
168      };
169
170      charger@11 {
171        reg = <0x11>;
172        monitored-battery = <&battery>;
173      };
174
175      fuel-gauge@22 {
176        reg = <0x22>;
177        monitored-battery = <&battery>;
178      };
179    };
180