battery.yaml

  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    };