Skip to main content

Battery Service

The battery service is responsible for managing battery status, including battery level, voltage, current, charging status and other information. The service receives raw data from the battery hardware device, processes it, and provides it to upper-layer applications.

Battery Data Structures​

Raw Battery Data​

Raw measurement data reported by the battery hardware device:

typedef struct {
    int8_t percent;                   // Battery percentage (0-100), -1 if unavailable
    int16_t voltage_mv;              // Battery voltage in millivolts, -1 if unavailable
    int16_t current_ma;              // Battery current in milliamps, positive for discharge, negative for charge
    bool charging;                   // true if charging
} eos_battery_raw_t;

Battery State Data​

Processed battery state with timestamp:

typedef struct {
    int8_t percent;                   // Battery percentage (0-100)
    int16_t voltage_mv;               // Battery voltage in millivolts
    int16_t current_ma;               // Battery current in milliamps
    bool charging;                    // true if charging
    uint32_t ts;                      // Timestamp when this state was recorded
    bool valid;                       // Validity flag
} eos_battery_state_t;

Battery Modes​

The battery service supports multiple operating modes, each with different polling strategies:

typedef enum {
    EOS_BATTERY_MODE_NORMAL = 0,    // Normal mode
    EOS_BATTERY_MODE_LOW_POWER,     // Low power mode
    EOS_BATTERY_MODE_CHARGING,     // Charging mode
    EOS_BATTERY_MODE_ACTIVE,        // Active mode
    EOS_BATTERY_MODE_COUNT,
} eos_battery_mode_t;

Battery Policy​

Each mode has a corresponding policy:

typedef struct {
    uint32_t interval_ms;            // Polling interval in milliseconds
    uint8_t threshold_percent;      // Battery threshold
} eos_battery_policy_t;

Service Initialization​

Initialize the battery service and register battery update events:

eos_result_t eos_service_battery_init(void);

Get Battery Information​

Get Battery Percentage​

int8_t eos_battery_get_percent(void);

Returns battery percentage (0-100), or -1 if unavailable.

Get Battery Voltage​

int16_t eos_battery_get_voltage_mv(void);

Returns battery voltage in millivolts, or -1 if unavailable.

Get Charging Status​

bool eos_battery_is_charging(void);

Returns true if charging.

Get Complete Battery State​

bool eos_battery_get_state(eos_battery_state_t *state);

Returns true on success, false if service not initialized or state invalid.

Get Battery Capacity Information​

uint32_t eos_battery_get_design_capacity(void);     // Design capacity in mAh
uint32_t eos_battery_get_current_capacity(void);     // Current estimated capacity in mAh
uint32_t eos_battery_get_cycle_count(void);         // Battery cycle count

Battery Events​

Use the event ID to register for battery state change notifications. When battery percentage or charging state changes, the event is broadcast:

eos_event_id_t eos_battery_get_event_id(void);

Custom Battery Calculation​

By default, a linear interpolation algorithm converts voltage to percentage. To use a custom algorithm:

void eos_battery_set_calc_fn(eos_battery_calc_fn_t fn);

Callback function type:

typedef int (*eos_battery_calc_fn_t)(int voltage_mv);

Pass in voltage (millivolts), return calculated percentage (0-100), or negative on error. Pass NULL to use the default algorithm.

Policy Management​

Set Mode Policy​

eos_result_t eos_battery_set_policy(eos_battery_mode_t mode, const eos_battery_policy_t *policy);

Get Mode Policy​

eos_result_t eos_battery_get_policy(eos_battery_mode_t mode, eos_battery_policy_t *policy);

State Persistence Keys​

State persistence keys used by the battery service:

#define EOS_STATE_KEY_CAPACITY             "battery_capacity"      // Battery capacity
#define EOS_STATE_KEY_CYCLE_COUNT          "cycle_count"           // Cycle count