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#

enum
zpal_pm_type_t {
ZPAL_PM_TYPE_USE_RADIO
ZPAL_PM_TYPE_DEEP_SLEEP
}
enum
zpal_pm_mode_t {
ZPAL_PM_MODE_RUNNING
ZPAL_PM_MODE_SLEEP
ZPAL_PM_MODE_DEEP_SLEEP
ZPAL_PM_MODE_SHUTOFF
}
enum
zpal_pm_device_t {
ZPAL_PM_DEVICE_ALWAYS_LISTENING
ZPAL_PM_DEVICE_FREQUENTLY_LISTENING
ZPAL_PM_DEVICE_NOT_LISTENING
}

Typedefs#

typedef void *
zpal_pm_handle_t

Power lock handle.

Functions#

void
zpal_pm_set_device_type(zpal_pm_device_t device_type)
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.

zpal_pm_handle_t
zpal_pm_register(zpal_pm_type_t type)

Registers a power lock of a given type.

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.

void
zpal_pm_cancel(zpal_pm_handle_t handle)

Cancels an active power lock.

void
zpal_pm_cancel_all(void)

Cancels all active 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.


Definition at line 51 of file /mnt/raid/workspaces/ws.H9QSi59DS/overlay/gsdk/protocol/z-wave/PAL/inc/zpal_power_manager.h

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


Definition at line 57 of file /mnt/raid/workspaces/ws.H9QSi59DS/overlay/gsdk/protocol/z-wave/PAL/inc/zpal_power_manager.h

zpal_pm_device_t#

zpal_pm_device_t
Enumerator
ZPAL_PM_DEVICE_ALWAYS_LISTENING
ZPAL_PM_DEVICE_FREQUENTLY_LISTENING
ZPAL_PM_DEVICE_NOT_LISTENING

Definition at line 65 of file /mnt/raid/workspaces/ws.H9QSi59DS/overlay/gsdk/protocol/z-wave/PAL/inc/zpal_power_manager.h

Typedef Documentation#

zpal_pm_handle_t#

typedef void* zpal_pm_handle_t

Power lock handle.


Definition at line 84 of file /mnt/raid/workspaces/ws.H9QSi59DS/overlay/gsdk/protocol/z-wave/PAL/inc/zpal_power_manager.h

Function Documentation#

zpal_pm_set_device_type#

void zpal_pm_set_device_type (zpal_pm_device_t device_type)
Parameters
N/Adevice_type

Definition at line 72 of file /mnt/raid/workspaces/ws.H9QSi59DS/overlay/gsdk/protocol/z-wave/PAL/inc/zpal_power_manager.h

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

Parameters
N/Afrom
N/Ato

This function is implemented by Z-Wave.


Definition at line 79 of file /mnt/raid/workspaces/ws.H9QSi59DS/overlay/gsdk/protocol/z-wave/PAL/inc/zpal_power_manager.h

zpal_pm_register#

zpal_pm_handle_t zpal_pm_register (zpal_pm_type_t type)

Registers a power lock of a given type.

Parameters
[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

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

Returns

  • A handle if successfully registered, NULL otherwise.


Definition at line 95 of file /mnt/raid/workspaces/ws.H9QSi59DS/overlay/gsdk/protocol/z-wave/PAL/inc/zpal_power_manager.h

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.

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.

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.


Definition at line 106 of file /mnt/raid/workspaces/ws.H9QSi59DS/overlay/gsdk/protocol/z-wave/PAL/inc/zpal_power_manager.h

zpal_pm_cancel#

void zpal_pm_cancel (zpal_pm_handle_t handle)

Cancels an active power lock.

Parameters
[in]handle

Power lock handle registered by zpal_pm_register().

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


Definition at line 114 of file /mnt/raid/workspaces/ws.H9QSi59DS/overlay/gsdk/protocol/z-wave/PAL/inc/zpal_power_manager.h

zpal_pm_cancel_all#

void zpal_pm_cancel_all (void )

Cancels all active power locks.

Parameters
N/A

Note

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


Definition at line 120 of file /mnt/raid/workspaces/ws.H9QSi59DS/overlay/gsdk/protocol/z-wave/PAL/inc/zpal_power_manager.h