summaryrefslogtreecommitdiffstats
path: root/Documentation/devicetree/bindings/power/supply/battery.yaml
blob: 491488e7b970397b409c248fb0c2a524301686a9 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
%YAML 1.2
---
$id: http://devicetree.org/schemas/power/supply/battery.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#

title: Battery Characteristics

maintainers:
  - Sebastian Reichel <sre@kernel.org>

description: |
  The devicetree battery node provides static battery characteristics.
  In smart batteries, these are typically stored in non-volatile memory
  on a fuel gauge chip. The battery node should be used where there is
  no appropriate non-volatile memory, or it is unprogrammed/incorrect.

  Upstream dts files should not include battery nodes, unless the battery
  represented cannot easily be replaced in the system by one of a
  different type. This prevents unpredictable, potentially harmful,
  behavior should a replacement that changes the battery type occur
  without a corresponding update to the dtb.

  Battery properties are named, where possible, for the corresponding elements
  in enum power_supply_property, defined in include/linux/power_supply.h

  Batteries must be referenced by chargers and/or fuel-gauges using a phandle.
  The phandle's property should be named "monitored-battery".

properties:
  compatible:
    const: simple-battery

  device-chemistry:
    description: This describes the chemical technology of the battery.
    oneOf:
      - const: nickel-cadmium
      - const: nickel-metal-hydride
      - const: lithium-ion
        description: This is a blanket type for all lithium-ion batteries,
          including those below. If possible, a precise compatible string
          from below should be used, but sometimes it is unknown which specific
          lithium ion battery is employed and this wide compatible can be used.
      - const: lithium-ion-polymer
      - const: lithium-ion-iron-phosphate
      - const: lithium-ion-manganese-oxide

  over-voltage-threshold-microvolt:
    description: battery over-voltage limit

  re-charge-voltage-microvolt:
    description: limit to automatically start charging again

  voltage-min-design-microvolt:
    description: drained battery voltage

  voltage-max-design-microvolt:
    description: fully charged battery voltage

  energy-full-design-microwatt-hours:
    description: battery design energy

  charge-full-design-microamp-hours:
    description: battery design capacity

  trickle-charge-current-microamp:
    description: current for trickle-charge phase

  precharge-current-microamp:
    description: current for pre-charge phase

  precharge-upper-limit-microvolt:
    description: limit when to change to constant charging

  charge-term-current-microamp:
    description: current for charge termination phase

  constant-charge-current-max-microamp:
    description: maximum constant input current

  constant-charge-voltage-max-microvolt:
    description: maximum constant input voltage

  factory-internal-resistance-micro-ohms:
    description: battery factory internal resistance

  resistance-temp-table:
    $ref: /schemas/types.yaml#/definitions/uint32-matrix
    items:
      items:
        - description: the temperature in degree Celsius
        - description: battery internal resistance percent
    description: |
      A table providing the temperature in degree Celsius
      and corresponding battery internal resistance percent, which is used to
      look up the resistance percent according to current temperature to get an
      accurate batterty internal resistance in different temperatures.

  ocv-capacity-celsius:
    description: |
      An array containing the temperature in degree Celsius,
      for each of the battery capacity lookup table.

  operating-range-celsius:
    description: operating temperature range of a battery
    items:
      - description: minimum temperature at which battery can operate
      - description: maximum temperature at which battery can operate

  ambient-celsius:
    description: safe range of ambient temperature
    items:
      - description: alert when ambient temperature is lower than this value
      - description: alert when ambient temperature is higher than this value

  alert-celsius:
    description: safe range of battery temperature
    items:
      - description: alert when battery temperature is lower than this value
      - description: alert when battery temperature is higher than this value

required:
  - compatible

patternProperties:
  '^ocv-capacity-table-[0-9]+$':
    $ref: /schemas/types.yaml#/definitions/uint32-matrix
    description: |
      An array providing the open circuit voltage (OCV)
      of the battery and corresponding battery capacity percent, which is used
      to look up battery capacity according to current OCV value. And the open
      circuit voltage unit is microvolt.
    maxItems: 100
    items:
      items:
        - description: open circuit voltage (OCV) in microvolts
        - description: battery capacity percent
          maximum: 100

additionalProperties: false

examples:
  - |
    power {
      #address-cells = <1>;
      #size-cells = <0>;

      battery: battery {
        compatible = "simple-battery";
        over-voltage-threshold-microvolt = <4500000>;
        re-charge-voltage-microvolt = <250000>;
        voltage-min-design-microvolt = <3200000>;
        voltage-max-design-microvolt = <4200000>;
        energy-full-design-microwatt-hours = <5290000>;
        charge-full-design-microamp-hours = <1430000>;
        precharge-current-microamp = <256000>;
        precharge-upper-limit-microvolt = <2500000>;
        charge-term-current-microamp = <128000>;
        constant-charge-current-max-microamp = <900000>;
        constant-charge-voltage-max-microvolt = <4200000>;
        factory-internal-resistance-micro-ohms = <250000>;
        ocv-capacity-celsius = <(-10) 0 10>;
        /* table for -10 degree Celsius */
        ocv-capacity-table-0 = <4185000 100>, <4113000 95>, <4066000 90>;
        /* table for 0 degree Celsius */
        ocv-capacity-table-1 = <4200000 100>, <4185000 95>, <4113000 90>;
        /* table for 10 degree Celsius */
        ocv-capacity-table-2 = <4250000 100>, <4200000 95>, <4185000 90>;
        resistance-temp-table = <20 100>, <10 90>, <0 80>, <(-10) 60>;
        operating-range-celsius = <(-30) 50>;
        ambient-celsius = <(-5) 50>;
        alert-celsius = <0 40>;
      };

      charger@11 {
        reg = <0x11>;
        monitored-battery = <&battery>;
      };

      fuel-gauge@22 {
        reg = <0x22>;
        monitored-battery = <&battery>;
      };
    };