dult_battery_level_set()

int dult_battery_level_set	(	const struct dult_user *	user,
		uint8_t	percentage_level )

#include <include/dult/dult.h>

Set the current battery level.

This function sets the current battery level. The battery level is an optional feature in the DULT specification and this API must not be used when the

CONFIG_DULT_BATTERY 

Kconfig is disabled.

If the

CONFIG_DULT_BATTERY 

Kconfig is enabled, call this function after registering the DULT user with dult_user_register. With the v1 API (

CONFIG_DULT_API_VARIANT_V1 

) the battery level is mandatory and must be set before the first dult_enable that follows registration. With the v2 API (

CONFIG_DULT_API_VARIANT_V2 

) setting it is optional; until it is set, the ANOS Get_Battery_Level operation is answered as invalid. Subsequent calls to update the battery level are allowed in the enabled mode.

To keep the battery level information accurate, the user should set the battery level to the new value with the help of this API as soon as the device battery level changes.

The battery level is stored per registered user, so it can be set during the pre-association window and each locator network keeps its own value. The accessory reports the currently associated user's value. With the v1 API (

CONFIG_DULT_API_VARIANT_V1 

) it is cleared by dult_reset, which is the terminal teardown for that variant. With the v2 API (

CONFIG_DULT_API_VARIANT_V2 

) it is preserved across dult_reset so it does not have to be set again before each subsequent dult_enable, and it is cleared by dult_user_unregister.

The exact mapping of the battery percentage to the battery level as defined by the DULT specification in the ANOS is implementation-specific. The mapping configuration is controlled by the following Kconfig options:

CONFIG_DULT_BATTERY_LEVEL_CRITICAL_THR 

,

CONFIG_DULT_BATTERY_LEVEL_LOW_THR 

and

CONFIG_DULT_BATTERY_LEVEL_MEDIUM_THR 

.

Parameters

user	User structure used to authenticate the user.
percentage_level	Battery level as a percentage [0-100%]

Returns

0 if the operation was successful. Otherwise, a (negative) error code is returned.