# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
%YAML 1.2
---
$id: http://devicetree.org/schemas/power/supply/battery.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#

title: Battery Characteristics

maintainers:
  - Sebastian Reichel <sre@kernel.org>

description: |
  The devicetree battery node provides static battery characteristics.
  In smart batteries, these are typically stored in non-volatile memory
  on a fuel gauge chip. The battery node should be used where there is
  no appropriate non-volatile memory, or it is unprogrammed/incorrect.
 
  Upstream dts files should not include battery nodes, unless the battery
  represented cannot easily be replaced in the system by one of a
  different type. This prevents unpredictable, potentially harmful,
  behavior should a replacement that changes the battery type occur
  without a corresponding update to the dtb.
 
  Battery properties are named, where possible, for the corresponding elements
  in enum power_supply_property, defined in include/linux/power_supply.h
 
  Batteries must be referenced by chargers and/or fuel-gauges using a phandle.
  The phandle's property should be named "monitored-battery".

properties:
  compatible:
    const: simple-battery

  device-chemistry:
    description: This describes the chemical technology of the battery.
    oneOf:
      - const: nickel-cadmium
      - const: nickel-metal-hydride
      - const: lithium-ion
        description: This is a blanket type for all lithium-ion batteries,
          including those below. If possible, a precise compatible string
          from below should be used, but sometimes it is unknown which specific
          lithium ion battery is employed and this wide compatible can be used.
      - const: lithium-ion-polymer
      - const: lithium-ion-iron-phosphate
      - const: lithium-ion-manganese-oxide

  over-voltage-threshold-microvolt:
    description: battery over-voltage limit

  re-charge-voltage-microvolt:
    description: limit to automatically start charging again

  voltage-min-design-microvolt:
    description: drained battery voltage

  voltage-max-design-microvolt:
    description: fully charged battery voltage

  energy-full-design-microwatt-hours:
    description: battery design energy

  charge-full-design-microamp-hours:
    description: battery design capacity

  trickle-charge-current-microamp:
    description: current for trickle-charge phase.
      Please note that the trickle-charging here, refers "wake-up" or
      "pre-pre" -charging, for very empty batteries. Similar term is also
      used for "maintenance" or "top-off" -charging of batteries (like
      NiMh bq24400) - that is different and not controlled by this
      property.

  tricklecharge-upper-limit-microvolt:
    description: limit when to change to precharge from trickle charge
      Trickle-charging here refers "wake-up" or "pre-pre" -charging.

  precharge-current-microamp:
    description: current for pre-charge phase

  precharge-upper-limit-microvolt:
    description: limit when to change to constant charging

  charge-term-current-microamp:
    description: current for charge termination phase

  constant-charge-current-max-microamp:
    description: maximum constant input current

  constant-charge-voltage-max-microvolt:
    description: maximum constant input voltage

  factory-internal-resistance-micro-ohms:
    description: battery factory internal resistance

  resistance-temp-table:
    $ref: /schemas/types.yaml#/definitions/uint32-matrix
    items:
      items:
        - description: the temperature in degree Celsius
        - description: battery internal resistance percent
    description: |
      A table providing the temperature in degree Celsius
      and corresponding battery internal resistance percent, which is used to
      look up the resistance percent according to current temperature to get an
      accurate batterty internal resistance in different temperatures.

  ocv-capacity-celsius:
    description: |
      An array containing the temperature in degree Celsius,
      for each of the battery capacity lookup table.

  operating-range-celsius:
    description: operating temperature range of a battery
    items:
      - description: minimum temperature at which battery can operate
      - description: maximum temperature at which battery can operate

  ambient-celsius:
    description: safe range of ambient temperature
    items:
      - description: alert when ambient temperature is lower than this value
      - description: alert when ambient temperature is higher than this value

  alert-celsius:
    description: safe range of battery temperature
    items:
      - description: alert when battery temperature is lower than this value
      - description: alert when battery temperature is higher than this value
 
  # The volt-drop* -properties describe voltage-drop for a battery, described
  # as VDROP in:
  # https://patentimages.storage.googleapis.com/6c/f5/17/c1d901c220f6a9/US20150032394A1.pdf
  volt-drop-thresh-microvolt:
    description: Threshold for starting the VDR correction
    maximum: 48000000

  volt-drop-soc-bp:
    description: Table of capacity values matching the values in VDR tables.
      The value should be given as basis points, 1/100 of a percent.

  volt-drop-temperatures-millicelsius:
    description: An array containing the temperature in milli celsius, for each
      of the VDR lookup table.

required:
  - compatible

patternProperties:
  '^ocv-capacity-table-[0-9]+$':
    $ref: /schemas/types.yaml#/definitions/uint32-matrix
    description: |
      An array providing the open circuit voltage (OCV)
      of the battery and corresponding battery capacity percent, which is used
      to look up battery capacity according to current OCV value. And the open
      circuit voltage unit is microvolt.
    maxItems: 100
    items:
      items:
        - description: open circuit voltage (OCV) in microvolts
        - description: battery capacity percent
          maximum: 100
 
  '^volt-drop-[0-9]-microvolt':
    description: Table of the voltage drop rate (VDR) values. Each entry in the
      table should match a capacity value in the volt-drop-soc table.
      Furthermore, the values should be obtained for the temperature given in
      volt-drop-temperatures-millicelsius table at index matching the
      number in this table's name.

additionalProperties: false

examples:
  - |
    power {
      #address-cells = <1>;
      #size-cells = <0>;
 
      battery: battery {
        compatible = "simple-battery";
        over-voltage-threshold-microvolt = <4500000>;
        re-charge-voltage-microvolt = <250000>;
        voltage-min-design-microvolt = <3200000>;
        voltage-max-design-microvolt = <4200000>;
        energy-full-design-microwatt-hours = <5290000>;
        charge-full-design-microamp-hours = <1430000>;
        precharge-current-microamp = <256000>;
        precharge-upper-limit-microvolt = <2500000>;
        charge-term-current-microamp = <128000>;
        constant-charge-current-max-microamp = <900000>;
        constant-charge-voltage-max-microvolt = <4200000>;
        factory-internal-resistance-micro-ohms = <250000>;
        ocv-capacity-celsius = <(-10) 0 10>;
        /* table for -10 degree Celsius */
        ocv-capacity-table-0 = <4185000 100>, <4113000 95>, <4066000 90>;
        /* table for 0 degree Celsius */
        ocv-capacity-table-1 = <4200000 100>, <4185000 95>, <4113000 90>;
        /* table for 10 degree Celsius */
        ocv-capacity-table-2 = <4250000 100>, <4200000 95>, <4185000 90>;
        resistance-temp-table = <20 100>, <10 90>, <0 80>, <(-10) 60>;
        operating-range-celsius = <(-30) 50>;
        ambient-celsius = <(-5) 50>;
        alert-celsius = <0 40>;
      };
 
      charger@11 {
        reg = <0x11>;
        monitored-battery = <&battery>;
      };
 
      fuel-gauge@22 {
        reg = <0x22>;
        monitored-battery = <&battery>;
      };
    };