Data Structures
struct	IotBatteryInfo_t
	Battery information. More...

Macros
#define	IOT_BATTERY_SUCCESS ( 0 )
	Return values used by BATTERY driver. More...

#define	IOT_BATTERY_INVALID_VALUE ( 1 )

#define	IOT_BATTERY_NOT_EXIST ( 2 )

#define	IOT_BATTERY_READ_FAILED ( 3 )

#define	IOT_BATTERY_FUNCTION_NOT_SUPPORTED ( 4 )

Typedefs
typedef struct IotBatteryDescriptor_t *	IotBatteryHandle_t
	IotBatteryHandle_t type is the Battery handle returned by calling iot_battery_open() this is initialized in open and returned to caller. Caller must pass this pointer to the rest of the APIs.

typedef void(*	IotBatteryCallback_t) (IotBatteryStatus_t xStatus, void *pvUserContext)
	Battery notification callback type. This callback is passed to the driver by using iot_battery_set_callback API. The callback is used to get the notifications about battery status changes for ex: when charging starts, or when critical threshold is reached or when battery is full etc... The callback is only used if the driver supports the asynchronous notifications. The caller must get the batteryInfo to find if the asynchronous notifications are supported. On simiple underlying batteries, the caller/application must manage the battery conditions by periodically probing the battery using read APIs, and for sophisticated battery management service modules, these can be managed in the HW hence asyncrhonous notifications can be sent (using registered callback) More...

Enumerations
enum	IotBatteryType_t { eBatteryChargeable, eBatteryNotChargeable }
	Battery Type. More...

enum	IotBatteryChargeSource_t { eBatteryChargeNone, eBatteryChargeUSB, eBatteryChargePowerSupply, erBatteryChargeWireless }
	Charger type. More...

enum	IotBatteryStatus_t { eBatteryCharging, eBatteryDischarging, eBatteryNotCharging, eBatteryChargeFull, eBatteryChargeLow, eBatteryOverVoltage, eBatteryUnderVoltage, eBatteryOverTemp, eBatteryUnderTemp, eBatteryOverChargingTemp, eBatteryUnderhargingTemp, eBatteryChargeTimeExpired, eBatteryUnknown }
	Battery status. More...

enum	IotBatteryIoctlRequest_t { eSetBatteryMinVoltageThreshold, eSetBatteryMaxVoltageThreshold, eSetBatteryMinBatteryTempThreshold, eSetBatteryMaxBatteryTempThreshold, eSetBatteryMinChargeTempThreshold, eSetBatteryMaxChargeTempThreshold, eSetBatteryMaxOutputCurrent, eSetBatteryMaxInputChargeCurrent, eSetBatteryChargeTimer, eGetBatteryMinVoltageThreshold, eGetBatteryMaxVoltageThreshold, eGetBatteryOCV, eGetBatteryBootVoltage, eGetBatteryMinBatteryTempThreshold, eGetBatteryMaxBatteryTempThreshold, eGetBatteryMinChargeTempThreshold, eGetBatteryMaxChargeTempThreshold, eGetBatteryMaxOutputCurrent, eGetBatteryMaxInputChargeCurrent, eGetBatteryChargeTimer, eGetBatteryChargeSource, eGetBatteryStatus }
	Ioctl request types. More...

Functions
IotBatteryHandle_t	iot_battery_open (int32_t lBatteryInstance)
	iot_battery_open is used to initialize the Battery and Charging driver. More...

void	iot_battery_set_callback (IotBatteryHandle_t const pxBatteryHandle, IotBatteryCallback_t xCallback, void *pvUserContext)
	iot_battery_set_callback is used to set the callback to be called when a notification needs to be sent to the caller. THe callback is only called if the battery supports async notifications. Caller must check isAsyncNotificationSupported value before registering for callbacks, if async is not supported, registering for callback has no affect, and the callback will never be called. More...

IotBatteryInfo_t *	iot_battery_getInfo (IotBatteryHandle_t const pxBatteryHandle)
	iot_battery_getInfo is used to get the battery info More...

int32_t	iot_battery_current (IotBatteryHandle_t const pxBatteryHandle, uint16_t *pusCurrent)
	iot_battery_current is used to get the battery current in mA. More...

int32_t	iot_battery_voltage (IotBatteryHandle_t const pxBatteryHandle, uint16_t *pusVoltage)
	iot_battery_voltage is used to get the battery voltage in milli-volts. More...

int32_t	iot_battery_chargeLevel (IotBatteryHandle_t const pxBatteryHandle, uint8_t *pucChargeLevel)
	iot_battery_chargeLevel is used to get the battery charging level in percentage (from 1 to 100). More...

int32_t	iot_battery_capacity (IotBatteryHandle_t const pxBatteryHandle, uint16_t *pusCapacity)
	iot_battery_capacity is used to get the current battery capacity value in mAh More...

int32_t	iot_battery_temp (IotBatteryHandle_t const pxBatteryHandle, int16_t *psTemp)
	iot_battery_temp is used to get the battery temperature in milliCelcius More...

int32_t	iot_battery_enable_charging (IotBatteryHandle_t const pxBatteryHandle, uint8_t *pucEnable)
	iot_battery_enable_charging is used to enable battery charging if charging is supported. if battery is already at full charge, enable will not charge battery until the charging level drops below 100, and even if battery is at critical level, and charging is not enabled, battery will not be charging. Charging is always enabled by default unless disabled by using this API. More...

int32_t	iot_battery_is_charging (IotBatteryHandle_t const pxBatteryHandle, uint8_t *pucCharging)
	iot_battery_is_charging is used to query if the battery is currently charging. More...

int32_t	iot_battery_ioctl (IotBatteryHandle_t const pxBatteryHandle, IotBatteryIoctlRequest_t xRequest, void *const pvBuffer)
	iot_battery_ioctl is used to set Battery configuration and Battery properties like battery threshold, temperature threshold, charging max, chargin min etc.. More...

int32_t	iot_battery_close (IotBatteryHandle_t const pxBatteryHandle)
	iot_battery_close is used to de-Initialize Battery driver. More...

Detailed Description

Macro Definition Documentation

◆ IOT_BATTERY_SUCCESS

#define IOT_BATTERY_SUCCESS ( 0 )

Return values used by BATTERY driver.

Battery operation completed successfully.

◆ IOT_BATTERY_INVALID_VALUE

#define IOT_BATTERY_INVALID_VALUE ( 1 )

At least one parameter is invalid.

◆ IOT_BATTERY_NOT_EXIST

#define IOT_BATTERY_NOT_EXIST ( 2 )

No battery exists in this hardware.

◆ IOT_BATTERY_READ_FAILED

#define IOT_BATTERY_READ_FAILED ( 3 )

Battery read operation failed.

◆ IOT_BATTERY_FUNCTION_NOT_SUPPORTED

#define IOT_BATTERY_FUNCTION_NOT_SUPPORTED ( 4 )

Battery operation not supported.

Typedef Documentation

◆ IotBatteryCallback_t

typedef void( * IotBatteryCallback_t) (IotBatteryStatus_t xStatus, void *pvUserContext)

Battery notification callback type. This callback is passed to the driver by using iot_battery_set_callback API. The callback is used to get the notifications about battery status changes for ex: when charging starts, or when critical threshold is reached or when battery is full etc... The callback is only used if the driver supports the asynchronous notifications. The caller must get the batteryInfo to find if the asynchronous notifications are supported. On simiple underlying batteries, the caller/application must manage the battery conditions by periodically probing the battery using read APIs, and for sophisticated battery management service modules, these can be managed in the HW hence asyncrhonous notifications can be sent (using registered callback)

Parameters

[in]	xStatus	battery status from IotBatteryStatus_t
[in]	pvUserContext	User Context passed when setting the callback. This is not used by the driver, but just passed back to the user in the callback.

Enumeration Type Documentation

◆ IotBatteryType_t

enum IotBatteryType_t

Battery Type.

Enumerator
eBatteryChargeable	Re-chargeable batteries with charging enabled
eBatteryNotChargeable	Not chargeable batteries

◆ IotBatteryChargeSource_t

enum IotBatteryChargeSource_t

Charger type.

Enumerator
eBatteryChargeNone	No Charge source, or non-chargeable battery
eBatteryChargeUSB	USB battery source
eBatteryChargePowerSupply	AC power supply source
erBatteryChargeWireless	Wireless charging source

◆ IotBatteryStatus_t

enum IotBatteryStatus_t

Battery status.

Enumerator
eBatteryCharging	Battery is Charging. Applicable only if the battery is chargeable
eBatteryDischarging	Battery is Discharging. This is the normal status of battery is no charger is connected
eBatteryNotCharging	Battery is not charging. This is set when charger is connected, but battery is not charging - usually an error condition
eBatteryChargeFull	Battery is fully charged. This status will be set only when the charger is connected and battery is fully charged
eBatteryChargeLow	Battery is low on charging and no charger connected. This status is set when battery is discharging and reaches a low cahrge value. Low charge value is defined by implementation
eBatteryOverVoltage	Battery maximum voltage limit reached.
eBatteryUnderVoltage	Battery low voltage limit reached.
eBatteryOverTemp	Battery maximum temperature limit reached.
eBatteryUnderTemp	Battery minimum temperature limit reached.
eBatteryOverChargingTemp	Battery maximum charging temperature limit reached.
eBatteryUnderhargingTemp	Battery minimum charging temperature limit reached.
eBatteryChargeTimeExpired	Battery charge timer expired. Charge timer can be set if the underlying hardware supports it using eSetBatteryChargeTimer IOCTL, and once the chargeTimer expires registered callback is called with this status set
eBatteryUnknown	Unknown status. Default status if no battery is present

◆ IotBatteryIoctlRequest_t

enum IotBatteryIoctlRequest_t

Ioctl request types.

Enumerator
eSetBatteryMinVoltageThreshold	Set the battery minimum voltage threshold. When the voltage goes below this threshold value, the registered callback will be called with the status set to "eBatteryUnderVoltage". If battery management HW does not have a way to monitor voltage, this IOCTL will not be supported. Parameter is uint16_t value in milliVolt units.
eSetBatteryMaxVoltageThreshold	Set the battery mimimum voltage threshold. When the voltage goes below this threshold value, the registered callback will be called with the status set to "eBatteryOverVoltage". If battery management HW does not have a way to monitor voltage, this IOCTL will not be supported. Parameter is uint16_t value in milliVolt units.
eSetBatteryMinBatteryTempThreshold	Set the minimum battery temperature threshold. When the battery temperature goes below this value, the registered callback will be called with the status value "eBatteryUnderTemp". This IOCTL takes int16_t value as input in milliCelcius units.
eSetBatteryMaxBatteryTempThreshold	Set the maximum battery temperature threshold. When the battery temperature goes above this value, the registered callback will be called with the status value "eBatteryUnderTemp". This IOCTL takes int16_t value as input in milliCelcius units.
eSetBatteryMinChargeTempThreshold	Set the minimum charge temperature threshold. When the charging temperature goes below this value, the registered callback will be called with the status value "eBatteryUnderChargingTemp". This IOCTL takes int16_t value as input in milliCelcius units.
eSetBatteryMaxChargeTempThreshold	Set the maximum charge temperature threshold. When the charging temperature goes above this value, the registered callback will be called with the status value "eBatteryOverChargingTemp". This IOCTL takes int16_t value as input in milliCelcius units.
eSetBatteryMaxOutputCurrent	Set the maximum output current limit from the battery. This IOCTL takes uint16_t value as input in milliAmp units.
eSetBatteryMaxInputChargeCurrent	Set the maximum input charging current limit to the battery. This IOCTL takes uint16_t value as input in milliAmp units.
eSetBatteryChargeTimer	Set the battery charging timer limit. AFter the timer expires charging will stop. This IOCTL takes uint16_t value as input in milliSec units.
eGetBatteryMinVoltageThreshold	Get the battery minimum thresold. This IOCTL returns uint16_t value in milliVolt units.
eGetBatteryMaxVoltageThreshold	Get the battery maximum thresold. This IOCTL returns uint16_t value in milliVolt units.
eGetBatteryOCV	Get the battery OCV (open circuit voltage) This IOCTL returns uint16_t value in milliVolt units.
eGetBatteryBootVoltage	Get the battery boot-up voltage This IOCTL returns uint16_t value in milliVolt units.
eGetBatteryMinBatteryTempThreshold	Get the minimum battery temperature thresholde This IOCTL returns int16_t value in milliCelcius units.
eGetBatteryMaxBatteryTempThreshold	Get the maximum battery temperature threshold. This IOCTL returns int16_t value in milliCelcius units.
eGetBatteryMinChargeTempThreshold	Get the minimum charging temperature threshold. This IOCTL returns int16_t value in milliCelcius units.
eGetBatteryMaxChargeTempThreshold	Get the maximum charging temperature threshold. This IOCTL returns int16_t value in milliCelcius units.
eGetBatteryMaxOutputCurrent	Get the battery output current limit. This IOCTL returns uint16_t value in milliAmp units.
eGetBatteryMaxInputChargeCurrent	Get the battery input charge current limit. This IOCTL returns uint16_t value in milliAmp units.
eGetBatteryChargeTimer	Get the current battery charge time limit. This IOCTL returns uint16_t value in milliSec units.
eGetBatteryChargeSource	Get the current battery charge source. This IOCTL returns a IotBatteryChargeSource_t as it's parameter.
eGetBatteryStatus	Get the battery status. Returns one of the IotBatteryStatus_t values as it's parameter.

Function Documentation

◆ iot_battery_open()

IotBatteryHandle_t iot_battery_open ( int32_t lBatteryInstance )

iot_battery_open is used to initialize the Battery and Charging driver.

Parameters

[in] lBatteryInstance The instance of the battery interface to initialize. Usually, there is only one battery interface.

Returns

handle to the Battery controller on success
NULL, if
- invalid instance
- open same instance more than once before closing it.
- on failure.

◆ iot_battery_set_callback()

void iot_battery_set_callback	(	IotBatteryHandle_t const	pxBatteryHandle,
		IotBatteryCallback_t	xCallback,
		void *	pvUserContext
	)

iot_battery_set_callback is used to set the callback to be called when a notification needs to be sent to the caller. THe callback is only called if the battery supports async notifications. Caller must check isAsyncNotificationSupported value before registering for callbacks, if async is not supported, registering for callback has no affect, and the callback will never be called.

Note

Single callback is used for all features that support callback

eBatteryChargeTimeExpired,
eSetBatteryMinVoltageThreshold, eSetBatteryMaxVoltageThreshold,
eSetBatteryMinBatteryTempThreshold, eSetBatteryMaxBatteryTempThreshold,
eSetBatteryMinChargeTempThreshold, eSetBatteryMaxChargeTempThreshold,

Newly set callback overrides the one previously set

This callback is per handle. Each instance has its own callback.

Warning: If input handle or if callback function is NULL, this function silently takes no action.

Parameters

[in]	pxBatteryHandle	handle to Battery driver returned in iot_battery_open()
[in]	xCallback	callback function to be called.
[in]	pvUserContext	user context to be passed when callback is called.

◆ iot_battery_getInfo()

IotBatteryInfo_t* iot_battery_getInfo ( IotBatteryHandle_t const pxBatteryHandle )

iot_battery_getInfo is used to get the battery info

Parameters

[in] pxBatteryHandle handle to Battery driver returned in iot_battery_open()

Returns

returns a pointer to the IotBatteryInfo structure on success
NULL on error

◆ iot_battery_current()

int32_t iot_battery_current	(	IotBatteryHandle_t const	pxBatteryHandle,
		uint16_t *	pusCurrent
	)

iot_battery_current is used to get the battery current in mA.

Parameters

[in]	pxBatteryHandle	handle to Battery driver returned in iot_battery_open()
[out]	pusCurrent	battery current value.

Returns

IOT_BATTERY_SUCCESS on success
IOT_BATTERY_INVALID_VALUE if pxBatteryHandle == NULL or pusCurrent == NULL
IOT_BATTERY_NOT_EXIST if no battery present.
IOT_BATTERY_READ_FAILED on error obtaining valid reading
IOT_BATTERY_FUNCTION_NOT_SUPPORTED if its not supported by the hardware.

◆ iot_battery_voltage()

int32_t iot_battery_voltage	(	IotBatteryHandle_t const	pxBatteryHandle,
		uint16_t *	pusVoltage
	)

iot_battery_voltage is used to get the battery voltage in milli-volts.

Parameters

[in]	pxBatteryHandle	handle to Battery driver returned in iot_battery_open()
[out]	pusVoltage	battery voltage value.

Returns

IOT_BATTERY_SUCCESS on success
IOT_BATTERY_INVALID_VALUE if pxBatteryHandle == NULL or pusVoltage == NULL
IOT_BATTERY_NOT_EXIST if no battery in this hardware
IOT_BATTERY_READ_FAILED on error
IOT_BATTERY_FUNCTION_NOT_SUPPORTED if its not supported by the hardware.

◆ iot_battery_chargeLevel()

int32_t iot_battery_chargeLevel	(	IotBatteryHandle_t const	pxBatteryHandle,
		uint8_t *	pucChargeLevel
	)

iot_battery_chargeLevel is used to get the battery charging level in percentage (from 1 to 100).

Parameters

[in]	pxBatteryHandle	handle to Battery driver returned in iot_battery_open()
[out]	pucChargeLevel	battery charging value.

Returns

IOT_BATTERY_SUCCESS on success
IOT_BATTERY_INVALID_VALUE if pxBatteryHandle == NULL or pusChargeLevel == NULL
IOT_BATTERY_NOT_EXIST if no battery in this hardware
IOT_BATTERY_READ_FAILED on error
IOT_BATTERY_FUNCTION_NOT_SUPPORTED if its not supported by the hardware.

◆ iot_battery_capacity()

int32_t iot_battery_capacity	(	IotBatteryHandle_t const	pxBatteryHandle,
		uint16_t *	pusCapacity
	)

iot_battery_capacity is used to get the current battery capacity value in mAh

Parameters

[in]	pxBatteryHandle	handle to Battery driver returned in iot_battery_open()
[out]	pusCapacity	battery capacity value.

Returns

IOT_BATTERY_SUCCESS on success
IOT_BATTERY_INVALID_VALUE if pxBatteryHandle == NULL or pusCapacity == NULL
IOT_BATTERY_NOT_EXIST if no battery in this hardware
IOT_BATTERY_READ_FAILED on error
IOT_BATTERY_FUNCTION_NOT_SUPPORTED if its not supported by the hardware.

◆ iot_battery_temp()

int32_t iot_battery_temp	(	IotBatteryHandle_t const	pxBatteryHandle,
		int16_t *	psTemp
	)

iot_battery_temp is used to get the battery temperature in milliCelcius

Parameters

[in]	pxBatteryHandle	handle to Battery driver returned in iot_battery_open()
[out]	psTemp	battery temperature in milliCelcius

Returns

IOT_BATTERY_SUCCESS on success
IOT_BATTERY_INVALID_VALUE if pxBatteryHandle == NULL or psTemp == NULL
IOT_BATTERY_NOT_EXIST if no battery in this hardware
IOT_BATTERY_READ_FAILED on error
IOT_BATTERY_FUNCTION_NOT_SUPPORTED if its not supported by the hardware.

◆ iot_battery_enable_charging()

int32_t iot_battery_enable_charging	(	IotBatteryHandle_t const	pxBatteryHandle,
		uint8_t *	pucEnable
	)

iot_battery_enable_charging is used to enable battery charging if charging is supported. if battery is already at full charge, enable will not charge battery until the charging level drops below 100, and even if battery is at critical level, and charging is not enabled, battery will not be charging. Charging is always enabled by default unless disabled by using this API.

Parameters

[in]	pxBatteryHandle	handle to Battery driver returned in iot_battery_open()
[in]	pucEnable	Enable or Disable the charging of battery. set to 1 to enable, or 0 to disable.

Returns

IOT_BATTERY_SUCCESS on success
IOT_BATTERY_INVALID_VALUE if NULL handle or NULL voltage pointer
IOT_BATTERY_NOT_EXIST if no battery in this hardware
IOT_BATTERY_FUNCTION_NOT_SUPPORTED if its not supported by the hardware.

◆ iot_battery_is_charging()

int32_t iot_battery_is_charging	(	IotBatteryHandle_t const	pxBatteryHandle,
		uint8_t *	pucCharging
	)

iot_battery_is_charging is used to query if the battery is currently charging.

Parameters

[in]	pxBatteryHandle	handle to Battery driver returned in iot_battery_open()
[out]	pucCharging	If charging this will contain value of 1 otherwise 0.

Returns

IOT_BATTERY_SUCCESS on success
IOT_BATTERY_INVALID_VALUE if pxBatteryHandle == NULL or pusCharging == NULL
IOT_BATTERY_NOT_EXIST if no battery in this hardware
IOT_BATTERY_FUNCTION_NOT_SUPPORTED if its not supported by the hardware.

◆ iot_battery_ioctl()

int32_t iot_battery_ioctl	(	IotBatteryHandle_t const	pxBatteryHandle,
		IotBatteryIoctlRequest_t	xRequest,
		void *const	pvBuffer
	)

iot_battery_ioctl is used to set Battery configuration and Battery properties like battery threshold, temperature threshold, charging max, chargin min etc..

Parameters

[in]	pxBatteryHandle	handle to Battery driver returned in iot_battery_open()
[in]	xRequest	configuration request of type IotBatteryIoctlRequest_t
[in,out]	pvBuffer	buffer holding Battery set and get values.

Returns

IOT_BATTERY_SUCCESS on success
IOT_BATTERY_INVALID_VALUE if
- pxBatteryHandle == NULL
- invalid xRequest
- pvBuffer == NULL when required
IOT_BATTERY_NOT_EXIST if no battery in this hardware
IOT_BATTERY_FUNCTION_NOT_SUPPORTED valid for any ioctl if its not supported by the hardware.

◆ iot_battery_close()

int32_t iot_battery_close ( IotBatteryHandle_t const pxBatteryHandle )

iot_battery_close is used to de-Initialize Battery driver.

Parameters

[in] pxBatteryHandle handle to Battery interface.

Returns

IOT_BATTERY_SUCCESS on success
IOT_BATTERY_INVALID_VALUE if
- pxBatteryHandle == NULL
- if is not in open state (already closed).

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ IOT_BATTERY_SUCCESS

◆ IOT_BATTERY_INVALID_VALUE

◆ IOT_BATTERY_NOT_EXIST

◆ IOT_BATTERY_READ_FAILED

◆ IOT_BATTERY_FUNCTION_NOT_SUPPORTED

Typedef Documentation

◆ IotBatteryCallback_t

Enumeration Type Documentation

◆ IotBatteryType_t

◆ IotBatteryChargeSource_t

◆ IotBatteryStatus_t

◆ IotBatteryIoctlRequest_t

Function Documentation

◆ iot_battery_open()

◆ iot_battery_set_callback()

◆ iot_battery_getInfo()

◆ iot_battery_current()

◆ iot_battery_voltage()

◆ iot_battery_chargeLevel()

◆ iot_battery_capacity()

◆ iot_battery_temp()

◆ iot_battery_enable_charging()

◆ iot_battery_is_charging()

◆ iot_battery_ioctl()

◆ iot_battery_close()