Battery Service

[中文]

The battery service exposes the Battery Level and other information for a battery in the context of the battery’s electrical connection to a device.

Examples

bluetooth/ble_services/ble_bas.

API Reference

Header File

Functions

esp_err_t esp_ble_bas_get_battery_level(uint8_t *level)

Get the current battery level of the device.

Parameters

level – [in] The pointer to store the current battery level

Returns

  • ESP_OK on successful

  • ESP_ERR_INVALID_ARG on wrong battery level

esp_err_t esp_ble_bas_set_battery_level(uint8_t *level)

Set the current battery level of the device.

Parameters

level – [in] The pointer to store the current battery level

Returns

  • ESP_OK on successful

  • ESP_ERR_INVALID_ARG on wrong battery level

esp_err_t esp_ble_bas_get_level_status(esp_ble_bas_level_status_t *status)

Get the summary information related to the battery status of the device.

Parameters

status – [in] The pointer to store the the summary information related to the battery status

Returns

  • ESP_OK on successful

  • ESP_ERR_INVALID_ARG on wrong battery status

esp_err_t esp_ble_bas_set_level_status(esp_ble_bas_level_status_t *status)

Set the summary information related to the battery status of the device.

Parameters

status – [in] The pointer to store the the summary information related to the battery status

Returns

  • ESP_OK on successful

  • ESP_ERR_INVALID_ARG on wrong battery status

esp_err_t esp_ble_bas_get_estimated_date(uint32_t *estimated_date)

Get the current estimated date when the battery is likely to require service or replacement.

Parameters

estimated_date – [in] The pointer to store the current estimated date

Returns

  • ESP_OK on successful

  • ESP_ERR_INVALID_ARG on wrong battery estimated date

esp_err_t esp_ble_bas_set_estimated_date(uint32_t *estimated_date)

Set the current estimated date when the battery is likely to require service or replacement.

Parameters

estimated_date – [in] The pointer to store the current estimated date

Returns

  • ESP_OK on successful

  • ESP_ERR_INVALID_ARG on wrong battery estimated date

esp_err_t esp_ble_bas_get_critical_status(esp_ble_bas_critical_status_t *status)

Get the status bits related to potential battery malfunction.

Parameters

status – [in] The pointer to store the status bits related to potential battery malfunction

Returns

  • ESP_OK on successful

  • ESP_ERR_INVALID_ARG on wrong battery malfunction

esp_err_t esp_ble_bas_set_critical_status(esp_ble_bas_critical_status_t *status)

Set the status bits related to potential battery malfunction.

Parameters

status – [in] The pointer to store the status bits related to potential battery malfunction

Returns

  • ESP_OK on successful

  • ESP_ERR_INVALID_ARG on wrong battery malfunction

esp_err_t esp_ble_bas_get_energy_status(esp_ble_bas_energy_status_t *status)

Get the current energy status details of the battery.

Parameters

status – [in] The pointer to store the status bits related to potential battery energy

Returns

  • ESP_OK on successful

  • ESP_ERR_INVALID_ARG on wrong battery energy

esp_err_t esp_ble_bas_set_energy_status(esp_ble_bas_energy_status_t *status)

Set the current energy status details of the battery.

Parameters

status – [in] The pointer to store the status bits related to potential battery energy

Returns

  • ESP_OK on successful

  • ESP_ERR_INVALID_ARG on wrong battery energy

esp_err_t esp_ble_bas_get_time_status(esp_ble_bas_time_status_t *status)

Get the current estimates on times for discharging and charging.

Parameters

status – [in] The pointer to store the current estimates on times

Returns

  • ESP_OK on successful

  • ESP_ERR_INVALID_ARG on wrong battery estimates

esp_err_t esp_ble_bas_set_time_status(esp_ble_bas_time_status_t *status)

Set the current estimates on times for discharging and charging.

Parameters

status – [in] The pointer to store the current estimates on times

Returns

  • ESP_OK on successful

  • ESP_ERR_INVALID_ARG on wrong battery estimates

esp_err_t esp_ble_bas_get_health_status(esp_ble_bas_health_status_t *status)

Get the aspects of battery health.

Parameters

status – [in] The pointer to store the aspects of battery health

Returns

  • ESP_OK on successful

  • ESP_ERR_INVALID_ARG on wrong battery health

esp_err_t esp_ble_bas_set_health_status(esp_ble_bas_health_status_t *status)

Set the aspects of battery health.

Parameters

status – [in] The pointer to store the aspects of battery health

Returns

  • ESP_OK on successful

  • ESP_ERR_INVALID_ARG on wrong battery health

esp_err_t esp_ble_bas_get_health_info(esp_ble_bas_health_info_t *info)

Get the static aspects of battery health.

Parameters

info – [in] The pointer to store the static aspects of battery health

Returns

  • ESP_OK on successful

  • ESP_ERR_INVALID_ARG on wrong battery health infomation

esp_err_t esp_ble_bas_set_health_info(esp_ble_bas_health_info_t *info)

Set the static aspects of battery health.

Parameters

info – [in] The pointer to store the static aspects of battery health

Returns

  • ESP_OK on successful

  • ESP_ERR_INVALID_ARG on wrong battery health infomation

esp_err_t esp_ble_bas_get_battery_info(esp_ble_bas_battery_info_t *info)

Get the physical characteristics of the battery.

Parameters

info – [in] The pointer to store the physical characteristics of the battery

Returns

  • ESP_OK on successful

  • ESP_ERR_INVALID_ARG on wrong battery infomation

esp_err_t esp_ble_bas_set_battery_info(esp_ble_bas_battery_info_t *info)

Set the physical characteristics of the battery.

Parameters

info – [in] The pointer to store the physical characteristics of the battery

Returns

  • ESP_OK on successful

  • ESP_ERR_INVALID_ARG on wrong battery infomation

esp_err_t esp_ble_bas_init(void)

Initialization Battery Service.

Returns

  • ESP_OK on successful

  • ESP_ERR_INVALID_ARG on wrong initialization

  • ESP_FAIL on error

Structures

struct uint24_t

This structure represents a 24bits data type.

Public Members

uint32_t u24

A 24bits data

struct esp_ble_bas_level_status_t

Battery Level Status Characteristic.

Public Members

uint8_t en_identifier

Identifier Present

uint8_t en_battery_level

Battery Level Present

uint8_t en_additional_status

Additional Status Present

uint8_t flags_reserved

Reserve Feature Used

struct esp_ble_bas_level_status_t::[anonymous] flags

Flags of Battery Level Status

uint16_t battery

Battery Present

uint16_t wired_external_power_source

Wired External Power Source Connected:

uint16_t wireless_external_power_source

Wireless External Power Source Connected:

uint16_t battery_charge_state

Battery Charge State:

uint16_t battery_charge_level

Battery Charge Level:

uint16_t battery_charge_type

Battery Charging Type

uint16_t charging_fault_reason

Charging Fault Reason

uint16_t power_state_reserved

Reserve Feature Used

struct esp_ble_bas_level_status_t::[anonymous] power_state

Power State of Battery Level Status

uint16_t identifier

Used as an identifier for a service instance.

uint8_t battery_level

Refer to the Battery Leve

uint8_t service_required

Service Required

uint8_t battery_fault

Battery Fault:

uint8_t reserved

Reserve Feature Used

struct esp_ble_bas_level_status_t::[anonymous] additional_status

Contains additional status information such as whether or not service is required

struct esp_ble_bas_critical_status_t

Battery Critical Status Characteristic.

Public Members

uint8_t critical_power_state

Critical Power State

uint8_t immediate_service

Immediate Service Required

uint8_t reserved

Reserve Feature Used

struct esp_ble_bas_critical_status_t::[anonymous] status

Battery Critical Status

struct esp_ble_bas_energy_status_t

Battery Energy Status Characteristic.

Public Members

uint8_t en_external_source_power

External Source Power Present

uint8_t en_voltage

Present Voltage Present

uint8_t en_available_energy

Available Energy Present

uint8_t en_available_battery_capacity

Available Battery Capacity Present

uint8_t en_charge_rate

Charge Rate Present

uint8_t en_available_energy_last_charge

Available Energy at Last Charge Present

uint8_t reserved

Reserve Feature Used

struct esp_ble_bas_energy_status_t::[anonymous] flags

Flags of Battery Energy Status

uint16_t external_source_power

The total power being consumed from an external power source

uint16_t voltage

The present terminal voltage of the battery in volts.

uint16_t available_energy

The available energy of the battery in kilowatt-hours in its current charge state

uint16_t available_battery_capacity

The capacity of the battery in kilowatt-hours at full charge in its current condition

uint16_t charge_rate

The energy flowing into the battery in watts

uint16_t available_energy_last_charge

The available energy of the battery in kilowatt-hours in its last charge state

struct esp_ble_bas_time_status_t

Battery Time Status Characteristic.

Public Members

uint8_t en_discharged_standby

Time until Discharged on Standby Present

uint8_t en_recharged

Time until Recharged Present

uint8_t reserved

Reserve Feature Used

struct esp_ble_bas_time_status_t::[anonymous] flags

Flags of Battery Time Status

uint24_t discharged

Estimated time in minutes until discharged

uint24_t discharged_standby

Estimated time in minutes until discharged assuming for the remaining time the device is in standby.

uint24_t recharged

Estimated time in minutes until recharged

struct esp_ble_bas_health_status_t

Battery Health Status Characteristic.

Public Members

uint8_t en_battery_health_summary

Battery Health Summary Present

uint8_t en_cycle_count

Cycle Count Present

uint8_t en_current_temperature

Current Temperature Present

uint8_t en_deep_discharge_count

Deep Discharge Count Present

uint8_t reserved

Reserve Feature Used

struct esp_ble_bas_health_status_t::[anonymous] flags

Flags of Battery Health Status

uint8_t battery_health_summary

Represents aggregation of the overall health of the battery

uint16_t cycle_count

Represents the count value of charge cycles

int8_t current_temperature

Represents the current temperature of the battery

uint16_t deep_discharge_count

Represents the number of times the battery was completely discharged

struct esp_ble_bas_health_info_t

Battery Health Infomation Characteristic.

Public Members

uint8_t en_cycle_count_designed_lifetime

Cycle Count Designed Lifetime Present

uint8_t min_max_designed_operating_temperature

Min and Max Designed Operating Temperature Present

uint8_t reserved

Reserve Feature Used

struct esp_ble_bas_health_info_t::[anonymous] flags

Flags of Battery Health Infomation

uint16_t cycle_count_designed_lifetime

Represents the designed number of charge cycles supported by the device

int8_t min_designed_operating_temperature

Represents the minimum designed operating temperature of the battery

int8_t max_designed_operating_temperature

Represents the maximum designed operating temperature of the battery

struct esp_ble_bas_battery_info_t

Battery Infomation Characteristic.

Public Members

uint16_t en_manufacture_date

Battery Manufacture Date Present

uint16_t en_expiration_date

Battery Expiration Date Present

uint16_t en_designed_capacity

Battery Designed Capacity Present

uint16_t en_low_energy

Battery Low Energy Present

uint16_t en_critical_energy

Battery Critical Energy Present

uint16_t en_chemistry

Battery Chemistry Present

uint16_t en_nominalvoltage

Nominal Voltage Present

uint16_t en_aggregation_group

Battery Aggregation Group Present

uint16_t flags_reserved

Reserve Feature Used

struct esp_ble_bas_battery_info_t::[anonymous] flags

Flags of Battery Infomation

uint8_t replace_able

Battery Replaceable

uint8_t recharge_able

Battery Rechargeable

uint8_t reserved

Reserve Feature Used

struct esp_ble_bas_battery_info_t::[anonymous] features

Features of Battery Infomation

uint24_t manufacture_date

Battery date of manufacture specified as days

uint24_t expiration_date

Battery expiration date specified as days

uint16_t designed_capacity

The capacity of the battery in kilowatt-hours at full charge in original (new) condition.

uint16_t low_energy

The battery energy value in kilowatt-hours when the battery is low

uint16_t critical_energy

The battery energy value in kilowatt-hours when the battery is critical.

uint8_t chemistry

The value of battery chemistry

uint16_t nominalvoltage

Nominal voltage of the battery in units of volts

uint8_t aggregation_group

Indicates the Battery Aggregation Group to which this instance of the battery service is associated

struct esp_ble_bas_data_t

Battery Service.

Public Members

uint8_t battery_level

The charge level of a battery

esp_ble_bas_level_status_t level_status

The power state of a battery

uint24_t estimated_service_date

The estimated date when replacement or servicing is required.

esp_ble_bas_critical_status_t critical_status

The device will possibly not function as expected due to low energy or service required

esp_ble_bas_energy_status_t energy_status

Details about the energy status of the battery

esp_ble_bas_time_status_t time_status

Time estimates for discharging and charging

esp_ble_bas_health_status_t health_status

Several aspects of battery health

esp_ble_bas_health_info_t health_info

The health of a battery

esp_ble_bas_battery_info_t battery_info

The physical characteristics of a battery in the context of the battery’s connection in a device

Macros

BLE_BAS_UUID16
BLE_BAS_CHR_UUID16_LEVEL
BLE_BAS_CHR_UUID16_LEVEL_STATUS
BLE_BAS_CHR_UUID16_ESTIMATED_SERVICE_DATE
BLE_BAS_CHR_UUID16_CRITICAL_STATUS
BLE_BAS_CHR_UUID16_ENERGY_STATUS
BLE_BAS_CHR_UUID16_TIME_STATUS
BLE_BAS_CHR_UUID16_HEALTH_STATUS
BLE_BAS_CHR_UUID16_HEALTH_INFO
BLE_BAS_CHR_UUID16_BATTERY_INFO
BAS_CHR_LEVEL_STATUS_FLAGS_BM_NONE
BAS_CHR_LEVEL_STATUS_FLAGS_BM_IDENTIFY
BAS_CHR_LEVEL_STATUS_FLAGS_BM_BATTERY_LEVEL
BAS_CHR_LEVEL_STATUS_FLAGS_BM_ADDITIONAL_STATUS
BAS_CHR_LEVEL_STATUS_FLAGS_BM_RFU
BAS_CHR_LEVEL_STATUS_POWER_STATE_BATTERY_NOT
BAS_CHR_LEVEL_STATUS_POWER_STATE_BATTERY_SET
BAS_CHR_LEVEL_STATUS_POWER_STATE_WIRED_EXTERNAL_POWER_SOURCE_NOTCONNECT
BAS_CHR_LEVEL_STATUS_POWER_STATE_WIRED_EXTERNAL_POWER_SOURCE_CONNECTED
BAS_CHR_LEVEL_STATUS_POWER_STATE_WIRED_EXTERNAL_POWER_SOURCE_UNKNOWN
BAS_CHR_LEVEL_STATUS_POWER_STATE_WIRED_EXTERNAL_POWER_SOURCE_RFU
BAS_CHR_LEVEL_STATUS_POWER_STATE_WIRELESS_EXTERNAL_POWER_SOURCE_NOTCONNECT
BAS_CHR_LEVEL_STATUS_POWER_STATE_WIRELESS_EXTERNAL_POWER_SOURCE_CONNECTED
BAS_CHR_LEVEL_STATUS_POWER_STATE_WIRELESS_EXTERNAL_POWER_SOURCE_UNKNOWN
BAS_CHR_LEVEL_STATUS_POWER_STATE_WIRELESS_EXTERNAL_POWER_SOURCE_RFU
BAS_CHR_LEVEL_STATUS_POWER_STATE_BATTERY_CHARGE_STATE_UNKNOWN
BAS_CHR_LEVEL_STATUS_POWER_STATE_BATTERY_CHARGE_STATE_CHARGING
BAS_CHR_LEVEL_STATUS_POWER_STATE_BATTERY_CHARGE_STATE_DISCHARGING_ACTIVE
BAS_CHR_LEVEL_STATUS_POWER_STATE_BATTERY_CHARGE_STATE_DISCHARGING_INACTIVE
BAS_CHR_LEVEL_STATUS_POWER_STATE_BATTERY_CHARGE_LEVEL_UNKNOWN
BAS_CHR_LEVEL_STATUS_POWER_STATE_BATTERY_CHARGE_LEVEL_GOOD
BAS_CHR_LEVEL_STATUS_POWER_STATE_BATTERY_CHARGE_LEVEL_LOW
BAS_CHR_LEVEL_STATUS_POWER_STATE_BATTERY_CHARGE_LEVEL_CRITICAL
BAS_CHR_LEVEL_STATUS_POWER_STATE_CHARGE_TYPE_UNKNOWN
BAS_CHR_LEVEL_STATUS_POWER_STATE_CHARGE_TYPE_CURRENT
BAS_CHR_LEVEL_STATUS_POWER_STATE_CHARGE_TYPE_VOLTAGE
BAS_CHR_LEVEL_STATUS_POWER_STATE_CHARGE_TYPE_TRICKLE
BAS_CHR_LEVEL_STATUS_POWER_STATE_CHARGE_TYPE_FLOAT
BAS_CHR_LEVEL_STATUS_POWER_STATE_CHARGE_TYPE_RFU
BAS_CHR_LEVEL_STATUS_POWER_STATE_CHARGE_FAULT_NONE
BAS_CHR_LEVEL_STATUS_POWER_STATE_CHARGE_FAULT_BATTERY
BAS_CHR_LEVEL_STATUS_POWER_STATE_CHARGE_FAULT_EXTERNAL_POWER_SOURCE
BAS_CHR_LEVEL_STATUS_POWER_STATE_CHARGE_FAULT_OTHER
BAS_CHR_LEVEL_STATUS_ASSITIONAL_STATUS_SERVICE_FALSE
BAS_CHR_LEVEL_STATUS_ASSITIONAL_STATUS_SERVICE_TRUE
BAS_CHR_LEVEL_STATUS_ASSITIONAL_STATUS_SERVICE_UNKNOWN
BAS_CHR_LEVEL_STATUS_ASSITIONAL_STATUS_SERVICE_RFU
BAS_CHR_LEVEL_STATUS_ASSITIONAL_STATUS_BATTERY_FAULT_UNKNOWN
BAS_CHR_LEVEL_STATUS_ASSITIONAL_STATUS_BATTERY_FAULT_TRUE
BAS_CHR_CRITICAL_STATUS_FLAGS_BM_NONE
BAS_CHR_CRITICAL_STATUS_FLAGS_BM_CRITICAL_POWER_STATE
BAS_CHR_CRITICAL_STATUS_FLAGS_BM_IMMEDIATE_SERVICE
BAS_CHR_ENERGY_STATUS_FLAGS_BM_NONE
BAS_CHR_ENERGY_STATUS_FLAGS_BM_EXTERNAL_SOURCE_POWER
BAS_CHR_ENERGY_STATUS_FLAGS_BM_VOLTAGE
BAS_CHR_ENERGY_STATUS_FLAGS_BM_AVAILALBE_ENERGY
BAS_CHR_ENERGY_STATUS_FLAGS_BM_AVAILALBE_BATTERY_CAPACITY
BAS_CHR_ENERGY_STATUS_FLAGS_BM_CHARGE_RATE
BAS_CHR_ENERGY_STATUS_FLAGS_BM_AVAILALBE_ENERGY_LAST_CHARGE
BAS_CHR_ENERGY_STATUS_FLAGS_BM_RFU
BAS_CHR_TIME_STATUS_FLAGS_BM_NONE
BAS_CHR_TIME_STATUS_FLAGS_BM_DISCHARGED_STANDBY
BAS_CHR_TIME_STATUS_FLAGS_BM_RECHARGE
BAS_CHR_TIME_STATUS_FLAGS_BM_RFU
BAS_CHR_HEALTH_STATUS_FLAGS_BM_NONE
BAS_CHR_HEALTH_STATUS_FLAGS_BM_BATTERY_HEALTH_SUMMARY
BAS_CHR_HEALTH_STATUS_FLAGS_BM_RCYCLE_COUNT
BAS_CHR_HEALTH_STATUS_FLAGS_BM_CURRENT_TEMPERATURE
BAS_CHR_HEALTH_STATUS_FLAGS_BM_DEEP_DISCHARGE_COUNT
BAS_CHR_HEALTH_STATUS_FLAGS_BM_RFU
BAS_CHR_HEALTH_INFO_FLAGS_BM_NONE
BAS_CHR_HEALTH_INFO_FLAGS_BM_CYCLE_COUNT_DESIGNED_LIFETIME
BAS_CHR_HEALTH_INFO_FLAGS_BM_DESIGNED_OPERATING_TEMPERATURE
BAS_CHR_HEALTH_INFO_FLAGS_BM_RFU
BAS_CHR_BATTERY_INFO_FLAGS_BM_NONE
BAS_CHR_BATTERY_INFO_FLAGS_BM_MANUFACTURE_DATE
BAS_CHR_BATTERY_INFO_FLAGS_BM_EXPIRATION_DATE
BAS_CHR_BATTERY_INFO_FLAGS_BM_DESIGNED_CAPACITY
BAS_CHR_BATTERY_INFO_FLAGS_BM_LOW_ENERGY
BAS_CHR_BATTERY_INFO_FLAGS_BM_CRITICAL_ENERGY
BAS_CHR_BATTERY_INFO_FLAGS_BM_CHEMISTRY
BAS_CHR_BATTERY_INFO_FLAGS_BM_NOMINAL_VOLTAGE
BAS_CHR_BATTERY_INFO_FLAGS_BM_AGGREGATION_GROUP
BAS_CHR_BATTERY_INFO_FLAGS_BM_RFU
BAS_CHR_BATTERY_INFO_FEATURE_BM_NONE
BAS_CHR_BATTERY_INFO_FEATURE_BM_REPLACE
BAS_CHR_BATTERY_INFO_FEATURE_BM_RECHARGE
BAS_CHR_BATTERY_INFO_FEATURE_BM_RFU

Provide feedback about this document