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
7 title: Battery Characteristics
8
9 maintainers:
10 - Sebastian Reichel <sre@kernel.org>
11
12 description: |
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
30 properties:
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
122 required:
123 - compatible
124
125 patternProperties:
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
140 additionalProperties: false
141
142 examples:
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 };
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.