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  over-voltage-threshold-microvolt:
35    description: battery over-voltage limit
36
37  re-charge-voltage-microvolt:
38    description: limit to automatically start charging again
39
40  voltage-min-design-microvolt:
41    description: drained battery voltage
42
43  voltage-max-design-microvolt:
44    description: fully charged battery voltage
45
46  energy-full-design-microwatt-hours:
47    description: battery design energy
48
49  charge-full-design-microamp-hours:
50    description: battery design capacity
51
52  trickle-charge-current-microamp:
53    description: current for trickle-charge phase
54
55  precharge-current-microamp:
56    description: current for pre-charge phase
57
58  precharge-upper-limit-microvolt:
59    description: limit when to change to constant charging
60
61  charge-term-current-microamp:
62    description: current for charge termination phase
63
64  constant-charge-current-max-microamp:
65    description: maximum constant input current
66
67  constant-charge-voltage-max-microvolt:
68    description: maximum constant input voltage
69
70  factory-internal-resistance-micro-ohms:
71    description: battery factory internal resistance
72
73  resistance-temp-table:
74    description: |
75      An array providing the temperature in degree Celsius
76      and corresponding battery internal resistance percent, which is used to
77      look up the resistance percent according to current temperature to get an
78      accurate batterty internal resistance in different temperatures.
79
80  ocv-capacity-celsius:
81    description: |
82      An array containing the temperature in degree Celsius,
83      for each of the battery capacity lookup table.
84
85  operating-range-celsius:
86    $ref: /schemas/types.yaml#/definitions/uint32-array
87    description: operating temperature range of a battery
88    items:
89      - description: minimum temperature at which battery can operate
90      - description: maximum temperature at which battery can operate
91
92  ambient-celsius:
93    $ref: /schemas/types.yaml#/definitions/uint32-array
94    description: safe range of ambient temperature
95    items:
96      - description: alert when ambient temperature is lower than this value
97      - description: alert when ambient temperature is higher than this value
98
99  alert-celsius:
100    $ref: /schemas/types.yaml#/definitions/uint32-array
101    description: safe range of battery temperature
102    items:
103      - description: alert when battery temperature is lower than this value
104      - description: alert when battery temperature is higher than this value
105
106required:
107  - compatible
108
109patternProperties:
110  '^ocv-capacity-table-[0-9]+$':
111    $ref: /schemas/types.yaml#/definitions/uint32-matrix
112    description: |
113      An array providing the open circuit voltage (OCV)
114      of the battery and corresponding battery capacity percent, which is used
115      to look up battery capacity according to current OCV value. And the open
116      circuit voltage unit is microvolt.
117    maxItems: 100
118    items:
119      items:
120        - description: open circuit voltage (OCV) in microvolts
121        - description: battery capacity percent
122          maximum: 100
123
124additionalProperties: false
125
126examples:
127  - |
128    power {
129      #address-cells = <1>;
130      #size-cells = <0>;
131
132      battery: battery {
133        compatible = "simple-battery";
134        over-voltage-threshold-microvolt = <4500000>;
135        re-charge-voltage-microvolt = <250000>;
136        voltage-min-design-microvolt = <3200000>;
137        voltage-max-design-microvolt = <4200000>;
138        energy-full-design-microwatt-hours = <5290000>;
139        charge-full-design-microamp-hours = <1430000>;
140        precharge-current-microamp = <256000>;
141        precharge-upper-limit-microvolt = <2500000>;
142        charge-term-current-microamp = <128000>;
143        constant-charge-current-max-microamp = <900000>;
144        constant-charge-voltage-max-microvolt = <4200000>;
145        factory-internal-resistance-micro-ohms = <250000>;
146        ocv-capacity-celsius = <(-10) 0 10>;
147        /* table for -10 degree Celsius */
148        ocv-capacity-table-0 = <4185000 100>, <4113000 95>, <4066000 90>;
149        /* table for 0 degree Celsius */
150        ocv-capacity-table-1 = <4200000 100>, <4185000 95>, <4113000 90>;
151        /* table for 10 degree Celsius */
152        ocv-capacity-table-2 = <4250000 100>, <4200000 95>, <4185000 90>;
153        resistance-temp-table = <20 100>, <10 90>, <0 80>, <(-10) 60>;
154        operating-range-celsius = <(-30) 50>;
155        ambient-celsius = <(-5) 50>;
156        alert-celsius = <0 40>;
157      };
158
159      charger@11 {
160        reg = <0x11>;
161        monitored-battery = <&battery>;
162      };
163
164      fuel-gauge@22 {
165        reg = <0x22>;
166        monitored-battery = <&battery>;
167      };
168    };
169