// 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.

library fuchsia.power.battery;

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;
};

/// 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_charnging_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;
};

/// Provider interface used to obtain battery status details
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(struct {
        info BatteryInfo;
    }) -> ();
};

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