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    $ref: /schemas/types.yaml#/definitions/uint32-matrix
89    items:
90      items:
91        - description: the temperature in degree Celsius
92        - description: battery internal resistance percent
93    description: |
94      A table providing the temperature in degree Celsius
95      and corresponding battery internal resistance percent, which is used to
96      look up the resistance percent according to current temperature to get an
97      accurate batterty internal resistance in different temperatures.
98
99  ocv-capacity-celsius:
100    description: |
101      An array containing the temperature in degree Celsius,
102      for each of the battery capacity lookup table.
103
104  operating-range-celsius:
105    description: operating temperature range of a battery
106    items:
107      - description: minimum temperature at which battery can operate
108      - description: maximum temperature at which battery can operate
109
110  ambient-celsius:
111    description: safe range of ambient temperature
112    items:
113      - description: alert when ambient temperature is lower than this value
114      - description: alert when ambient temperature is higher than this value
115
116  alert-celsius:
117    description: safe range of battery temperature
118    items:
119      - description: alert when battery temperature is lower than this value
120      - description: alert when battery temperature is higher than this value
121
122required:
123  - compatible
124
125patternProperties:
126  '^ocv-capacity-table-[0-9]+$':
127    $ref: /schemas/types.yaml#/definitions/uint32-matrix
128    description: |
129      An array providing the open circuit voltage (OCV)
130      of the battery and corresponding battery capacity percent, which is used
131      to look up battery capacity according to current OCV value. And the open
132      circuit voltage unit is microvolt.
133    maxItems: 100
134    items:
135      items:
136        - description: open circuit voltage (OCV) in microvolts
137        - description: battery capacity percent
138          maximum: 100
139
140additionalProperties: false
141
142examples:
143  - |
144    power {
145      #address-cells = <1>;
146      #size-cells = <0>;
147
148      battery: battery {
149        compatible = "simple-battery";
150        over-voltage-threshold-microvolt = <4500000>;
151        re-charge-voltage-microvolt = <250000>;
152        voltage-min-design-microvolt = <3200000>;
153        voltage-max-design-microvolt = <4200000>;
154        energy-full-design-microwatt-hours = <5290000>;
155        charge-full-design-microamp-hours = <1430000>;
156        precharge-current-microamp = <256000>;
157        precharge-upper-limit-microvolt = <2500000>;
158        charge-term-current-microamp = <128000>;
159        constant-charge-current-max-microamp = <900000>;
160        constant-charge-voltage-max-microvolt = <4200000>;
161        factory-internal-resistance-micro-ohms = <250000>;
162        ocv-capacity-celsius = <(-10) 0 10>;
163        /* table for -10 degree Celsius */
164        ocv-capacity-table-0 = <4185000 100>, <4113000 95>, <4066000 90>;
165        /* table for 0 degree Celsius */
166        ocv-capacity-table-1 = <4200000 100>, <4185000 95>, <4113000 90>;
167        /* table for 10 degree Celsius */
168        ocv-capacity-table-2 = <4250000 100>, <4200000 95>, <4185000 90>;
169        resistance-temp-table = <20 100>, <10 90>, <0 80>, <(-10) 60>;
170        operating-range-celsius = <(-30) 50>;
171        ambient-celsius = <(-5) 50>;
172        alert-celsius = <0 40>;
173      };
174
175      charger@11 {
176        reg = <0x11>;
177        monitored-battery = <&battery>;
178      };
179
180      fuel-gauge@22 {
181        reg = <0x22>;
182        monitored-battery = <&battery>;
183      };
184    };
185