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     description: |
  89       An array providing the temperature in degree Celsius
  90       and corresponding battery internal resistance percent, which is used to
  91       look up the resistance percent according to current temperature to get an
  92       accurate batterty internal resistance in different temperatures.
  93
  94   ocv-capacity-celsius:
  95     description: |
  96       An array containing the temperature in degree Celsius,
  97       for each of the battery capacity lookup table.
  98
  99   operating-range-celsius:
 100     description: operating temperature range of a battery
 101     items:
 102       - description: minimum temperature at which battery can operate
 103       - description: maximum temperature at which battery can operate
 104
 105   ambient-celsius:
 106     description: safe range of ambient temperature
 107     items:
 108       - description: alert when ambient temperature is lower than this value
 109       - description: alert when ambient temperature is higher than this value
 110
 111   alert-celsius:
 112     description: safe range of battery temperature
 113     items:
 114       - description: alert when battery temperature is lower than this value
 115       - description: alert when battery temperature is higher than this value
 116
 117 required:
 118   - compatible
 119
 120 patternProperties:
 121   '^ocv-capacity-table-[0-9]+$':
 122     $ref: /schemas/types.yaml#/definitions/uint32-matrix
 123     description: |
 124       An array providing the open circuit voltage (OCV)
 125       of the battery and corresponding battery capacity percent, which is used
 126       to look up battery capacity according to current OCV value. And the open
 127       circuit voltage unit is microvolt.
 128     maxItems: 100
 129     items:
 130       items:
 131         - description: open circuit voltage (OCV) in microvolts
 132         - description: battery capacity percent
 133           maximum: 100
 134
 135 additionalProperties: false
 136
 137 examples:
 138   - |
 139     power {
 140       #address-cells = <1>;
 141       #size-cells = <0>;
 142
 143       battery: battery {
 144         compatible = "simple-battery";
 145         over-voltage-threshold-microvolt = <4500000>;
 146         re-charge-voltage-microvolt = <250000>;
 147         voltage-min-design-microvolt = <3200000>;
 148         voltage-max-design-microvolt = <4200000>;
 149         energy-full-design-microwatt-hours = <5290000>;
 150         charge-full-design-microamp-hours = <1430000>;
 151         precharge-current-microamp = <256000>;
 152         precharge-upper-limit-microvolt = <2500000>;
 153         charge-term-current-microamp = <128000>;
 154         constant-charge-current-max-microamp = <900000>;
 155         constant-charge-voltage-max-microvolt = <4200000>;
 156         factory-internal-resistance-micro-ohms = <250000>;
 157         ocv-capacity-celsius = <(-10) 0 10>;
 158         /* table for -10 degree Celsius */
 159         ocv-capacity-table-0 = <4185000 100>, <4113000 95>, <4066000 90>;
 160         /* table for 0 degree Celsius */
 161         ocv-capacity-table-1 = <4200000 100>, <4185000 95>, <4113000 90>;
 162         /* table for 10 degree Celsius */
 163         ocv-capacity-table-2 = <4250000 100>, <4200000 95>, <4185000 90>;
 164         resistance-temp-table = <20 100>, <10 90>, <0 80>, <(-10) 60>;
 165         operating-range-celsius = <(-30) 50>;
 166         ambient-celsius = <(-5) 50>;
 167         alert-celsius = <0 40>;
 168       };
 169
 170       charger@11 {
 171         reg = <0x11>;
 172         monitored-battery = <&battery>;
 173       };
 174
 175       fuel-gauge@22 {
 176         reg = <0x22>;
 177         monitored-battery = <&battery>;
 178       };
 179     };