sdk/fidl/fuchsia.power.battery/battery.fidl

// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
@available(added=HEAD)
library fuchsia.power.battery;

using fuchsia.power.system;
using zx;

/// The overall status of the battery, informing its general availability.
type BatteryStatus = strict enum {
    /// Uninitialized battery status.
    UNKNOWN = 0;
    /// Battery present and available.
    OK = 1;
    /// Battery present, but not available (e.g. disabled).
    NOT_AVAILABLE = 2;
    /// Battery not present (e.g. removed or no battery).
    NOT_PRESENT = 3;
};

/// The status of the battery with respect to charging.
type ChargeStatus = strict enum {
    UNKNOWN = 0;
    NOT_CHARGING = 1;
    CHARGING = 2;
    DISCHARGING = 3;
    FULL = 4;
};

/// The power source for an actively charging battery.
type ChargeSource = strict enum {
    UNKNOWN = 0;
    NONE = 1;
    AC_ADAPTER = 2;
    USB = 3;
    WIRELESS = 4;
};

/// The general status of the battery level.
type LevelStatus = strict enum {
    UNKNOWN = 0;
    OK = 1;
    WARNING = 2; // OEM defined signal for initial notification UI to charge.
    LOW = 3; // OEM defined at around 5% of capacity (sufficient for S1-S4).
    CRITICAL = 4; // no longer capable of supplying power, emergency shutdown.
};

/// The general status related to the overall health of the battery.
type HealthStatus = strict enum {
    UNKNOWN = 0;
    GOOD = 1;
    COLD = 2;
    HOT = 3;
    DEAD = 4;
    OVER_VOLTAGE = 5;
    UNSPECIFIED_FAILURE = 6;
    COOL = 7;
    WARM = 8;
    OVERHEAT = 9;
};

/// The time remaining while actively charging or discharging.
type TimeRemaining = flexible union {
    /// Representation of indeterminate state with zero duration.
    1: indeterminate zx.Duration;

    /// Remaining battery life while discharging.
    2: battery_life zx.Duration;

    /// Remaining time until full while charging.
    3: full_charge zx.Duration;
};

/// Type of data that are determined by manufacturer.
type BatterySpec = table {
    /// Represent the battery's charging current spec in micro amps.
    1: max_charging_current_ua int32;

    /// Represent the battery's charging voltage spec in micro volt.
    2: max_charging_voltage_uv int32;

    /// Battery Full Charge Design Capacity in micro amp hour.
    3: design_capacity_uah int32;
};

/// Current battery state information.
type BatteryInfo = table {
    /// General battery status with respect to presence & availability.
    1: status BatteryStatus;

    /// The current state of the battery with respect to charging.
    2: charge_status ChargeStatus;

    /// The charge source while battery is actively charging.
    /// When not actively charging, this will reflect that the source is
    /// NONE (not charging) or UNKNOWN.
    3: charge_source ChargeSource;

    /// Battery level in percentage. Level percent is only available if
    /// level status is known.
    4: level_percent float32;

    /// Battery level as a general status, including low and critical.
    5: level_status LevelStatus;

    /// Overall battery health.
    6: health HealthStatus;

    /// Time remaining relative to the current charge status.
    7: time_remaining TimeRemaining;

    /// Timestamp to distinguish between latest and stale status.
    8: timestamp zx.Time;

    /// Forward the voltage level in mv.
    9: present_voltage_mv uint32;

    /// Forward the battery capqacity in uAh.
    10: remaining_capacity_uah uint32;

    /// Battery spec.
    11: battery_spec BatterySpec;

    /// Full Charge Capacity in uAh.
    12: full_capacity_uah int32;

    /// Temperature in MilliCelsius.
    13: temperature_mc int32;

    /// Current in MilliAmps.
    14: present_current_ma int32;

    /// Average Current in MilliAmps.
    15: average_current_ma int32;
};

/// Provider interface used to obtain battery status details.
@discoverable
closed protocol BatteryInfoProvider {
    /// Gets battery info.
    strict GetBatteryInfo() -> (struct {
        info BatteryInfo;
    });

    /// Registers a watcher for battery info changes.
    strict Watch(resource struct {
        watcher client_end:BatteryInfoWatcher;
    });
};

/// Watcher on battery info.
closed protocol BatteryInfoWatcher {
    /// Callback triggered when battery info changes.
    strict OnChangeBatteryInfo(resource struct {
        info BatteryInfo;

        /// Optional wake lease for power baton passing.
        wake_lease fuchsia.power.system.LeaseToken:optional;
    }) -> ();
};

/// Charging control
@discoverable
open protocol Charger {
    flexible Enable(struct {
        enable bool;
    }) -> () error zx.Status;
};

/// General manager interface for battery management.
@discoverable
closed protocol BatteryManager {
    // Provides battery status information.
    compose BatteryInfoProvider;
};

service InfoService {
    device client_end:BatteryInfoProvider;
};

service ChargerService {
    device client_end:Charger;
};