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