Zpal-power-manager#
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.
Enumerations#
Functions#
The ZPAL implementation must invoke this function whenever a transition happens between one of the power modes defined in zpal_pm_mode_t.
Registers a power lock of a given type.
Makes the chip stay awake for a given time in a power mode defined by handle.
Checks if a lock is active or not.
Cancels an active power lock.
Unregister previously registered power lock.
Cancels all active power locks.
Unallocate all power locks.
Enumeration Documentation#
zpal_pm_type_t#
zpal_pm_type_t
| 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. |
51 of file /mnt/raid/workspaces/ws.6QOxxjIBR/overlay/gsdk/protocol/z-wave/PAL/inc/zpal_power_manager.hzpal_pm_mode_t#
zpal_pm_mode_t
| 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. |
57 of file /mnt/raid/workspaces/ws.6QOxxjIBR/overlay/gsdk/protocol/z-wave/PAL/inc/zpal_power_manager.hzpal_pm_device_t#
zpal_pm_device_t
| Enumerator | |
|---|---|
| ZPAL_PM_DEVICE_ALWAYS_LISTENING | |
| ZPAL_PM_DEVICE_FREQUENTLY_LISTENING | |
| ZPAL_PM_DEVICE_NOT_LISTENING | |
65 of file /mnt/raid/workspaces/ws.6QOxxjIBR/overlay/gsdk/protocol/z-wave/PAL/inc/zpal_power_manager.hTypedef Documentation#
zpal_pm_context_t#
typedef struct zpal_pm_context zpal_pm_context_t
72 of file /mnt/raid/workspaces/ws.6QOxxjIBR/overlay/gsdk/protocol/z-wave/PAL/inc/zpal_power_manager.hzpal_pm_handle_t#
typedef void* zpal_pm_handle_t
Power lock handle.
86 of file /mnt/raid/workspaces/ws.6QOxxjIBR/overlay/gsdk/protocol/z-wave/PAL/inc/zpal_power_manager.hFunction Documentation#
zpal_pm_set_device_type#
void zpal_pm_set_device_type (zpal_pm_device_t device_type)
| N/A | device_type |
74 of file /mnt/raid/workspaces/ws.6QOxxjIBR/overlay/gsdk/protocol/z-wave/PAL/inc/zpal_power_manager.hzpal_zw_pm_event_handler#
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.
| N/A | from | |
| N/A | to |
This function is implemented by Z-Wave.
81 of file /mnt/raid/workspaces/ws.6QOxxjIBR/overlay/gsdk/protocol/z-wave/PAL/inc/zpal_power_manager.hzpal_pm_register#
zpal_pm_handle_t zpal_pm_register (zpal_pm_type_t type)
Registers a power lock of a given type.
| [in] | type | Power lock type. |
This function must be invoked once to allocate power lock before any other API calls are made on that lock. Note
To unregister (destroy) locks already created using zpal_pm_register() use zpal_pm_unregister().
Returns
A handle if successfully registered, NULL otherwise.
97 of file /mnt/raid/workspaces/ws.6QOxxjIBR/overlay/gsdk/protocol/z-wave/PAL/inc/zpal_power_manager.hzpal_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.
| [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. |
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.
108 of file /mnt/raid/workspaces/ws.6QOxxjIBR/overlay/gsdk/protocol/z-wave/PAL/inc/zpal_power_manager.hzpal_pm_is_active#
bool zpal_pm_is_active (zpal_pm_handle_t handle)
Checks if a lock is active or not.
| [in] | handle | Power lock handle registered by zpal_pm_register(). |
If handle points to NULL, returns false.
Returns
true if PowerLock is active, false otherwise.
118 of file /mnt/raid/workspaces/ws.6QOxxjIBR/overlay/gsdk/protocol/z-wave/PAL/inc/zpal_power_manager.hzpal_pm_cancel#
void zpal_pm_cancel (zpal_pm_handle_t handle)
Cancels an active power lock.
| [in] | handle | Power lock handle registered by zpal_pm_register(). |
If handle points to NULL or inactive power lock, nothing happens.
126 of file /mnt/raid/workspaces/ws.6QOxxjIBR/overlay/gsdk/protocol/z-wave/PAL/inc/zpal_power_manager.hzpal_pm_unregister#
void zpal_pm_unregister (zpal_pm_handle_t handle)
Unregister previously registered power lock.
| [in] | handle | Power lock handle registered by zpal_pm_register(). |
If the power lock is active, it will be cancelled. It removes the power lock from context and updates pm context accordingly. If handle points to NULL, nothing happens.
136 of file /mnt/raid/workspaces/ws.6QOxxjIBR/overlay/gsdk/protocol/z-wave/PAL/inc/zpal_power_manager.hzpal_pm_cancel_all#
void zpal_pm_cancel_all (void )
Cancels all active power locks.
| N/A |
Note
It cancels all power locks created during runtime, hence it can be used ONLY as a part of power down routine.
142 of file /mnt/raid/workspaces/ws.6QOxxjIBR/overlay/gsdk/protocol/z-wave/PAL/inc/zpal_power_manager.hzpal_pm_unregister_all#
void zpal_pm_unregister_all (void )
Unallocate all power locks.
| N/A |
Note
Used only in unit tests to avoid valgrind to detect leakage
148 of file /mnt/raid/workspaces/ws.6QOxxjIBR/overlay/gsdk/protocol/z-wave/PAL/inc/zpal_power_manager.h