电池服务

[English]

电池服务在电池与设备的电气连接上下文中公开电池的电量和其他信息。

示例

bluetooth/ble_services/ble_bas.

API 参考

Header File

Functions

esp_err_t esp_ble_bas_get_battery_level(uint8_t *level)

Get the current battery level of the device.

参数

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

返回

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

参数

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

返回

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

参数

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

返回

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

参数

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

返回

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

参数

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

返回

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

参数

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

返回

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

参数

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

返回

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

参数

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

返回

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

参数

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

返回

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

参数

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

返回

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

参数

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

返回

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

参数

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

返回

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

参数

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

返回

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

参数

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

返回

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

参数

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

返回

  • ESP_OK on successful

  • ESP_ERR_INVALID_ARG on wrong battery health information

esp_err_t esp_ble_bas_set_health_info(esp_ble_bas_health_info_t *info)

Set the static aspects of battery health.

参数

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

返回

  • ESP_OK on successful

  • ESP_ERR_INVALID_ARG on wrong battery health information

esp_err_t esp_ble_bas_get_battery_info(esp_ble_bas_battery_info_t *info)

Get the physical characteristics of the battery.

参数

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

返回

  • ESP_OK on successful

  • ESP_ERR_INVALID_ARG on wrong battery information

esp_err_t esp_ble_bas_set_battery_info(esp_ble_bas_battery_info_t *info)

Set the physical characteristics of the battery.

参数

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

返回

  • ESP_OK on successful

  • ESP_ERR_INVALID_ARG on wrong battery information

esp_err_t esp_ble_bas_init(void)

Initialization Battery Service.

返回

  • 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 Level

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 Information 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 Information

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 Information 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 Information

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 Information

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