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