versions/v1_4_0/mynewt-core/hw/battery/include/battery/battery_prop.h

/*
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership.  The ASF licenses this file
 * to you under the Apache License, Version 2.0 (the
 * "License"); you may not use this file except in compliance
 * with the License.  You may obtain a copy of the License at
 *
 *  http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing,
 * software distributed under the License is distributed on an
 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 * KIND, either express or implied.  See the License for the
 * specific language governing permissions and limitations
 * under the License.
 */

/**
 * @file battery.h
 * @brief Battery property
 *
 * The Batter property provides software view to data provided by fuel gauge
 * ADC or charge controllers.
 */

#ifndef __BATTERY_PROP_H__
#define __BATTERY_PROP_H__

#include "os/mynewt.h"

#ifdef __cplusplus
extern "C" {
#endif

#if MYNEWT_VAL(BATTERY_MAX_PROPERTY_COUNT)
#define BATTERY_MAX_PROPERTY_COUNT MYNEWT_VAL(BATTERY_MAX_PROPERTY_COUNT)
#else
#define BATTERY_MAX_PROPERTY_COUNT 32
#endif

#define BATTERY_PROPERTY_MASK_SIZE (((BATTERY_MAX_PROPERTY_COUNT) + 31) / 32)

/* Forward declaration of battery structure. */
struct battery;
struct battery_property;
struct battery_prop_listener;

/* Comments above intentionally not in Doxygen format */

/* =================================================================
 * ====================== DEFINES/MACROS ===========================
 * =================================================================
 */

/**
 * @{ Battery properties API
 */

// ---------------------- TYPE -------------------------------------

typedef enum {
    BATTERY_STATUS_UNKNOWN = 0,
    /* Charger connected, battery charging */
    BATTERY_STATUS_CHARGING,
    /* Charger not connected, battery discharging */
    BATTERY_STATUS_DISCHARGING,
    /* Charger connected, not charging */
    BATTERY_STATUS_NOT_CHARGING,
    /* Charger connected, not charging - battery full */
    BATTERY_STATUS_FULL,
} battery_status_t;

typedef enum {
    BATTERY_CAPACITY_LEVEL_UNKNOWN = 0,
    BATTERY_CAPACITY_LEVEL_CRITICAL,
    BATTERY_CAPACITY_LEVEL_LOW,
    BATTERY_CAPACITY_LEVEL_NORMAL,
    BATTERY_CAPACITY_LEVEL_HIGH,
    BATTERY_CAPACITY_LEVEL_FULL,
} battery_capacity_level_t;

typedef union battery_property_value {
    float bpv_flt;
    uint32_t bpv_u32;
    int32_t bpv_i32;
    uint16_t bpv_u16;
    int16_t bpv_i16;
    uint8_t bpv_u8;
    int8_t bpv_i8;
    /* in mV */
    int32_t bpv_voltage;
    /* in mA */
    int32_t bpv_current;
    /* in mAh */
    uint32_t bpv_capacity;
    /* SOC in % 0..100 */
    uint8_t bpv_soc;
    /* SOH in % 0..100 */
    uint8_t bpv_soh;
    /* Temperature in deg C */
    float bpv_temperature;
    /* Time in s */
    uint32_t bpv_time_in_s;
    /* Number of charge cycles */
    uint16_t bpv_cycle_count;
    battery_status_t bpv_status;
    battery_capacity_level_t bpv_capacity_level;
    uint8_t bpv_base_prop[4];
} battery_property_value_t;

/**
 * Battery properties.
 * Fuel gauge can exposes subset of those properties.
 */
typedef enum {
    BATTERY_PROP_NONE,
    /* Battery status supported */
    BATTERY_PROP_STATUS,
    /* Battery capacity level supported */
    BATTERY_PROP_CAPACITY_LEVEL,
    /* Battery capacity in mAh */
    BATTERY_PROP_CAPACITY,
    /* Predicted full battery capacity in mAh */
    BATTERY_PROP_CAPACITY_FULL,
    /* Current battery temperature in C */
    BATTERY_PROP_TEMP_NOW,
    /* Ambient temperature in C */
    BATTERY_PROP_TEMP_AMBIENT,
    /* Minimum voltage in V */
    BATTERY_PROP_VOLTAGE_MIN,
    /* Maximum voltage in V */
    BATTERY_PROP_VOLTAGE_MAX,
    /* Minimum designed voltage in V */
    BATTERY_PROP_VOLTAGE_MIN_DESIGN,
    /* Maximum designed voltage in V */
    BATTERY_PROP_VOLTAGE_MAX_DESIGN,
    /* Current voltage in V */
    BATTERY_PROP_VOLTAGE_NOW,
    /* Current average voltage in V */
    BATTERY_PROP_VOLTAGE_AVG,
    /* Maximum current in mAh */
    BATTERY_PROP_CURRENT_MAX,
    /* Current level at this time in mAh */
    BATTERY_PROP_CURRENT_NOW,
    /* Average current level in mAh */
    BATTERY_PROP_CURRENT_AVG,
    /* State-Of-Charge, current capacity 0-100 % */
    BATTERY_PROP_SOC,
    /* State-Of-Health, current battery state of health 0-100 % */
    BATTERY_PROP_SOH,
    /* Predicted time to complete discharge in seconds */
    BATTERY_PROP_TIME_TO_EMPTY_NOW,
    /* Predicted time to full capacity when charging in seconds */
    BATTERY_PROP_TIME_TO_FULL_NOW,
    /* Number of full discharge/charge cycles */
    BATTERY_PROP_CYCLE_COUNT,
} battery_property_type_t;

typedef enum {
    BATTERY_PROPERTY_FLAGS_NONE = 0,
    /* Set or get refers to property value that sets the alarm when
     * property value goes below specified value
     */
    BATTERY_PROPERTY_FLAGS_LOW_ALARM_SET_THRESHOLD      = 0x01,
    /* Set or get refers to property value that sets the alarm when
     * property value goes below specified value
     */
    BATTERY_PROPERTY_FLAGS_LOW_ALARM_CLEAR_THRESHOLD    = 0x02,
    BATTERY_PROPERTY_FLAGS_LOW_ALARM                    = 0x03,
    /* Set or get refers to property value that sets the alarm when
     * property value goes above specified value
     */
    BATTERY_PROPERTY_FLAGS_HIGH_ALARM_SET_THRESHOLD     = 0x04,
    /* Set or get refers to property value that clears the alarm when
     * property value goes below specified value.
     */
    BATTERY_PROPERTY_FLAGS_HIGH_ALARM_CLEAR_THRESHOLD   = 0x08,
    /* Property is not supported by hardware
     * This is specially important for threshold levels,
     * battery manager can create software only threshold levels.
     */
    BATTERY_PROPERTY_FLAGS_HIGH_ALARM                   = 0x0C,
    BATTERY_PROPERTY_FLAGS_ALARM_THREASH                = 0x0F,
    BATTERY_PROPERTY_FLAGS_ALARM                        = 0x10,
    BATTERY_PROPERTY_FLAGS_DERIVED                      = 0x80,
    /* Flag only needed for battery_mgr_get_property() function.
     * When property is requested that is not supported by hardware
     * it can be synthesized as software only and used for alarms
     */
    BATTERY_PROPERTY_FLAGS_CREATE                       = 0x40,
} battery_property_flags_t;

/**
 * Battery driver property declaration struct
 *
 * Driver provides array of those to declare what kind of properties
 * are supported.
 */
struct battery_driver_property
{
    battery_property_type_t   bdp_type;
    battery_property_flags_t  bdp_flags;
    const char *              bdp_name;
};

/**
 * Battery property
 * It has type that specifies property type it can also have
 * BATTERY_PROPERY_NOT_HARDWARE bit set if property was created
 * by battery manager not a driver.
 * It can also have threshold bits set if property is one of
 * the threshold values.
 */
struct battery_property {
    battery_property_type_t   bp_type;
    battery_property_flags_t  bp_flags;
    /* Field managed by battery manager */
    /* Battery property number */
    uint8_t                   bp_prop_num;
    /* Battery property number in driver property array */
    uint8_t                   bp_drv_prop_num;
    /* Driver number, 1 based index */
    uint8_t                   bp_drv_num:2;
    /* Battery number, 0 based index */
    uint8_t                   bp_bat_num:2;
    uint8_t                   bp_comp:1;
    uint8_t                   bp_base:1;
    /* Value of property is valid */
    uint8_t                   bp_valid:1;
    battery_property_value_t  bp_value;
};

static inline int driver_property(const struct battery_property *prop)
{
    return 0 == (prop->bp_flags & BATTERY_PROPERTY_FLAGS_DERIVED);
}

int battery_prop_get_value(struct battery_property *prop);

int battery_prop_get_value_float(struct battery_property *prop, float *value);
int battery_prop_get_value_uint8(struct battery_property *prop, uint8_t *val);
int battery_prop_get_value_int8(struct battery_property *prop, int8_t *val);
int battery_prop_get_value_uint16(struct battery_property *prop, uint16_t *val);
int battery_prop_get_value_int16(struct battery_property *prop, int16_t *val);
int battery_prop_get_value_uint32(struct battery_property *prop, uint32_t *val);
int battery_prop_get_value_int32(struct battery_property *prop, int32_t *val);

int battery_prop_set_value_float(struct battery_property *prop, float value);
int battery_prop_set_value_uint8(struct battery_property *prop, uint8_t val);
int battery_prop_set_value_int8(struct battery_property *prop, int8_t val);
int battery_prop_set_value_uint16(struct battery_property *prop, uint16_t val);
int battery_prop_set_value_int16(struct battery_property *prop, int16_t val);
int battery_prop_set_value_uint32(struct battery_property *prop, uint32_t val);
int battery_prop_set_value_int32(struct battery_property *prop, int32_t val);

/**
 * Register a property change listener. This allows a calling application to
 * receive callbacks when property changes.
 * Same listener can be used for many properties.
 *
 * @param The listener to register
 * @param The battery property to register a listener on
 *
 * @return 0 on success, non-zero error code on failure.
 */
int battery_prop_change_subscribe(struct battery_prop_listener *listener,
        struct battery_property *prop);

/**
 * Unregister a property change listener.
 *
 * @param The listener to unregister
 * @param The battery property to unregister a listener from
 *        if prop is NULL, listener is unregistered from all properties
 *
 * @return 0 on success, non-zero error code on failure.
 */
int battery_prop_change_unsubscribe(struct battery_prop_listener *listener,
        struct battery_property *prop);

/**
 * Register a battery listener. This allows a calling application to
 * receive callbacks when new data was read from fuel gauge.
 *
 * @param The battery property to register a listener on
 * @param The listener to register
 *
 * @return 0 on success, non-zero error code on failure.
 */
int battery_prop_poll_subscribe(struct battery_prop_listener *listener,
        struct battery_property *prop);

/**
 * Unregister a property read listener.
 *
 * @param The listener to unregister
 * @param The battery property to unregister a listener from
 *        if prop is NULL, listener is unregistered from all properties
 *
 * @return 0 on success, non-zero error code on failure.
 */
int battery_prop_poll_unsubscribe(struct battery_prop_listener *listener,
        struct battery_property *prop);

typedef int (*battery_prop_read_t)(struct battery_prop_listener *listener,
        const struct battery_property *prop);

typedef int (*battery_prop_changed_t)(struct battery_prop_listener *listener,
        const struct battery_property *prop);

/**
 * Listener structure which may be registered to battery properties.
 * User bpl_prop_read function will be called for every property that
 * this listener is register for just after data is received.
 */
struct battery_prop_listener {
    /*
     * Battery data handler function, called when data was read.
     */
    battery_prop_read_t bpl_prop_read;
    /*
     * Property changed function
     */
    battery_prop_changed_t bpl_prop_changed;
};

/**
 * }@
 */

/* End Battery Manager API */


/**
 * @}
 */

/* End Battery API */

#ifdef __cplusplus
}
#endif

#endif /* __BATTERY_PROP_H__ */