Documentation/devicetree/bindings/power/supply/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
   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     };