Zpal-power-manager

Defines a platform abstraction layer for the Z-Wave power manager. More...

Collaboration diagram for Zpal-power-manager:

Typedefs
typedef void *	zpal_pm_handle_t
	Power lock handle.

Enumerations
enum	zpal_pm_type_t {   ZPAL_PM_TYPE_USE_RADIO ,   ZPAL_PM_TYPE_DEEP_SLEEP }
	Defines the different power types that can be requested. More...
enum	zpal_pm_mode_t {   ZPAL_PM_MODE_RUNNING ,   ZPAL_PM_MODE_SLEEP ,   ZPAL_PM_MODE_DEEP_SLEEP ,   ZPAL_PM_MODE_SHUTOFF }
	Defines the power modes the underlying platform can enter or leave. More...

Functions
void	zpal_zw_pm_event_handler (zpal_pm_mode_t from, zpal_pm_mode_t to)
	The ZPAL implementation must invoke this function whenever a transition happens between one of the power modes defined in zpal_pm_mode_t. This function is implemented by Z-Wave.
zpal_pm_handle_t	zpal_pm_register (zpal_pm_type_t type)
	Registers a power lock of a given type. This function must be invoked once to allocate power lock before any other API calls are made on that lock.
void	zpal_pm_stay_awake (zpal_pm_handle_t handle, uint32_t timeout_milliseconds)
	Makes the chip stay awake for a given time in a power mode defined by handle. The power lock must be registered with zpal_pm_register() prior to invoking this function. If invoked on an already active power lock, the timeout will be reset.
void	zpal_pm_cancel (zpal_pm_handle_t handle)
	Cancels an active power lock. If handle points to NULL or inactive power lock, nothing happens.
void	zpal_pm_cancel_all (void)
	Cancels all active power locks.

Detailed Description

Defines a platform abstraction layer for the Z-Wave power manager.

The ZPAL power manager offers an API for registering power locks and for receiving events on power mode transitions. Power lock forces the chip to stay awake in a given power mode for a given time. An event handler is invoked every time the transition between power modes occurs.

Infinite lock example:

zpal_pm_handle_t handle = zpal_pm_register(ZPAL_PM_TYPE_USE_RADIO);  // Register the power lock that keeps radio active
zpal_pm_stay_awake(handle, 0);                                       // Keep the radio active forever
                                                                     // Other stuff
zpal_pm_cancel(handle);                                              // The chip may go to sleep now

Lock with timeout example:

zpal_pm_handle_t handle = zpal_pm_register(ZPAL_PM_TYPE_USE_RADIO);  // Register the power lock that keeps radio active
zpal_pm_stay_awake(handle, 2000);                                    // Keep the radio active for 2000 ms from now

Requirements:

• The storage for power locks should be able to hold at least 20 items. Note that this number may change in the future.

Typedef Documentation

zpal_pm_handle_t

typedef void* zpal_pm_handle_t

Power lock handle.

Enumeration Type Documentation

zpal_pm_mode_t

enum zpal_pm_mode_t

Defines the power modes the underlying platform can enter or leave.

For instance, the platform might go from ZPAL_PM_MODE_RUNNING to ZPAL_PM_MODE_SHUTOFF if no power locks are requested.

Enumerator
ZPAL_PM_MODE_RUNNING	Processor is active.
ZPAL_PM_MODE_SLEEP	Processor is sleeping, but all peripherals are enabled.
ZPAL_PM_MODE_DEEP_SLEEP	Most peripherals are disabled, but the radio is in FLiRS mode.
ZPAL_PM_MODE_SHUTOFF	Chip is off and will boot from reset. Hence, no transition from this power mode will ever happen.

zpal_pm_type_t

enum zpal_pm_type_t

Defines the different power types that can be requested.

For instance, if the Z-Wave stack or the application wants the radio available, ZPAL_PM_TYPE_USE_RADIO must be requested.

Enumerator
ZPAL_PM_TYPE_USE_RADIO	Prevents the system from entering a sleep mode where radio is unavailable.
ZPAL_PM_TYPE_DEEP_SLEEP	Prevents the system from going to a sleep mode that requires wake up from reset state.

Function Documentation

zpal_pm_cancel()

void zpal_pm_cancel

(

zpal_pm_handle_t

handle

)

Cancels an active power lock. If handle points to NULL or inactive power lock, nothing happens.

Parameters

[in]

handle

Power lock handle registered by zpal_pm_register().

zpal_pm_cancel_all()

void zpal_pm_cancel_all

(

void

)

Cancels all active power locks.

Note

It cancels all power locks created during runtime, hence it can be used ONLY as a part of power down routine.

zpal_pm_register()

zpal_pm_handle_t zpal_pm_register

(

zpal_pm_type_t

type

)

Registers a power lock of a given type. This function must be invoked once to allocate power lock before any other API calls are made on that lock.

Note

Keep in mind that it's not possible to unregister (destroy) locks already created using zpal_pm_register().

Parameters

[in]

type

Power lock type.

Returns

A handle if successfully registered, NULL otherwise.

zpal_pm_stay_awake()

void zpal_pm_stay_awake	(	zpal_pm_handle_t	handle,
		uint32_t	timeout_milliseconds )

Makes the chip stay awake for a given time in a power mode defined by handle. The power lock must be registered with zpal_pm_register() prior to invoking this function. If invoked on an already active power lock, the timeout will be reset.

Parameters

[in]	handle	Power lock handle registered by zpal_pm_register().
[in]	timeout_milliseconds	Timeout value. If zero is given, the power lock will stay active until manually cancelled.

zpal_zw_pm_event_handler()

void zpal_zw_pm_event_handler ( zpal_pm_mode_t from, zpal_pm_mode_t to )

extern

The ZPAL implementation must invoke this function whenever a transition happens between one of the power modes defined in zpal_pm_mode_t. This function is implemented by Z-Wave.

Parameters

[in]	from	The power mode from which the platform is coming.
[in]	to	The power mode to which the platform is going.