WLAN Standby features

Detailed Description

The standby mode allows the system to power off or put the host processor in a deep sleep mode while the Morse chip takes over certain functionality to keep the connection alive with the provision to wake up the host processor when certain conditions are met.

When in Standby mode, the chip will:

• Not try to communicate with the host in any way.
• Use normal Power Save mechanisms to wake for DTIM beacons and to receive data frames when a DTIM beacon indicates pending data.
• Directly respond to ARP requests if ARP offload is enabled, handle DHCP lease expiry/renewal if DHCP offload is enabled, and drop all other traffic other than a wake request packet from the access point.
• Monitor access point reach-ability and provide status by periodically transmitting encrypted keep-alive frames to the access point.
• If access point is no longer reachable, then the chip will enter a snooze mode where it stops listening for beacons, waking up only occasionally to see if the access point is reachable again. This allows the chip to conserve power when the access point is not reachable.

The chip will wake the host only if one of the following occurs.

• An encrypted Standby wake packet is received.
• Association has been lost (indicated via a deauth response to a keep-alive frame from the access point).
• The access point was not reachable and beacons are now detected indicating the access point is available again.
• The input trigger GPIO pin on the chip was toggled indicating some on board hardware requires attention.
• A TCP connection maintained by the TCP keep-alive offload feature was lost.

The host will be powered on by toggling a GPIO pin, the BUSY pin is also toggled to interrupt the host. By offloading features like ARP response, ARP refresh, TCP keep-alive, and DHCP lease updates while in standby mode allows the host processor to sleep for longer resulting in better power savings.

Warning

BETA NOTICE: This is beta API that is under development; breaking changes may be introduced in future releases.

Data Structures
struct	mmwlan_standby_enter_args
	Arguments for mmwlan_standby_enter More...
struct	mmwlan_standby_set_status_payload_args
	Arguments for mmwlan_standby_set_status_payload. More...
struct	mmwlan_standby_set_wake_filter_args
	Arguments for mmwlan_standby_set_wake_filter More...
struct	mmwlan_standby_config
	Standby mode configuration parameters. More...

Typedefs
typedef void(*	mmwlan_standby_exit_cb_t) (uint8_t reason, void *arg)
	Standby mode callback whenever an event requiring an exit from standby mode occurs. More...

Enumerations
enum	mmwlan_standby_exit_reason {   MMWLAN_STANDBY_EXIT_REASON_NONE , MMWLAN_STANDBY_EXIT_REASON_WAKEUP_FRAME , MMWLAN_STANDBY_EXIT_REASON_ASSOCIATE , MMWLAN_STANDBY_EXIT_REASON_EXT_INPUT ,   MMWLAN_STANDBY_EXIT_REASON_WHITELIST_PKT , MMWLAN_STANDBY_EXIT_REASON_TCP_CONNECTION_LOST , MMWLAN_STANDBY_EXIT_REASON_HW_SCAN_NOT_ENABLED , MMWLAN_STANDBY_EXIT_REASON_HW_SCAN_FAILED_TO_START }
	Reasons we can exit standby mode. More...

Functions
enum mmwlan_status	mmwlan_standby_enter (const struct mmwlan_standby_enter_args *args)
	This function puts the Morse chip into standby mode allowing the host processor to go to sleep. More...
enum mmwlan_status	mmwlan_standby_exit (void)
	Forces the Morse chip to exit standby mode. More...
enum mmwlan_status	mmwlan_standby_set_status_payload (const struct mmwlan_standby_set_status_payload_args *args)
	Sets the user payload in the standby status packet. More...
enum mmwlan_status	mmwlan_standby_set_wake_filter (const struct mmwlan_standby_set_wake_filter_args *args)
	Configures the standby mode UDP wake packet filter. More...
enum mmwlan_status	mmwlan_standby_set_config (const struct mmwlan_standby_config *config)
	Sets the configuration for standby mode. More...

Typedef Documentation

mmwlan_standby_exit_cb_t

typedef void(* mmwlan_standby_exit_cb_t) (uint8_t reason, void *arg)

Standby mode callback whenever an event requiring an exit from standby mode occurs.

Parameters

reason	The reason we exited standby mode. See enum mmwlan_standby_exit_reason.
arg	An opaque pointer passed from mmwlan_standby_enter()

Warning

BETA NOTICE: This is beta API that is under development; breaking changes may be introduced in future releases.

Definition at line 1822 of file mmwlan.h.

Enumeration Type Documentation

mmwlan_standby_exit_reason

enum mmwlan_standby_exit_reason

Reasons we can exit standby mode.

Enumerator
MMWLAN_STANDBY_EXIT_REASON_NONE	No specific reason for exiting standby mode.
MMWLAN_STANDBY_EXIT_REASON_WAKEUP_FRAME	The STA has received the wake-up frame.
MMWLAN_STANDBY_EXIT_REASON_ASSOCIATE	The STA needs to (re)associate.
MMWLAN_STANDBY_EXIT_REASON_EXT_INPUT	The external input pin has fired.
MMWLAN_STANDBY_EXIT_REASON_WHITELIST_PKT	Whitelisted packet received.
MMWLAN_STANDBY_EXIT_REASON_TCP_CONNECTION_LOST	TCP connection lost.
MMWLAN_STANDBY_EXIT_REASON_HW_SCAN_NOT_ENABLED	HW scan is not enabled.
MMWLAN_STANDBY_EXIT_REASON_HW_SCAN_FAILED_TO_START	HW scan failed to start.

Definition at line 1793 of file mmwlan.h.

Function Documentation

mmwlan_standby_enter()

enum mmwlan_status mmwlan_standby_enter

(

const struct mmwlan_standby_enter_args *

args

)

This function puts the Morse chip into standby mode allowing the host processor to go to sleep.

When in standby mode the Morse chip takes over certain functionality to keep the connection alive with the provision to wake up the host processor when certain conditions are met. Exit from standby mode can be triggered by the Morse chip under certain conditions or by the host by invoking mmwlan_standby_exit(). Before invoking this function, standby mode parameters can be configured by calling mmwlan_standby_set_config(), mmwlan_standby_set_status_payload() and/or mmwlan_standby_set_wake_filter()

Parameters

args	A pointer to the arguments for this function.

Returns

MMWLAN_SUCCESS on success or MMWLAN_ERROR on failure.

Warning

BETA NOTICE: This is beta API that is under development; breaking changes may be introduced in future releases.

mmwlan_standby_exit()

enum mmwlan_status mmwlan_standby_exit

(

void

)

Forces the Morse chip to exit standby mode.

here may be certain instances such as a timer expiry, which cause the host chip to wake up independent of the Morse chip. In such situations, the host calls this function to instruct the Morse chip to exit standby mode and return to normal operating mode.

Triggers mmwlan_standby_exit_cb_t with reason MMWLAN_STANDBY_EXIT_REASON_NONE.

Returns

MMWLAN_SUCCESS on success or MMWLAN_ERROR on failure.

Warning

BETA NOTICE: This is beta API that is under development; breaking changes may be introduced in future releases.

mmwlan_standby_set_config()

enum mmwlan_status mmwlan_standby_set_config

(

const struct mmwlan_standby_config *

config

)

Sets the configuration for standby mode.

Parameters

config

A pointer to the configuration structure. See mmwlan_standby_config.

Returns

MMWLAN_SUCCESS on success or MMWLAN_ERROR on failure.

Warning

BETA NOTICE: This is beta API that is under development; breaking changes may be introduced in future releases.

mmwlan_standby_set_status_payload()

enum mmwlan_status mmwlan_standby_set_status_payload

(

const struct mmwlan_standby_set_status_payload_args *

args

)

Sets the user payload in the standby status packet.

Once standby mode is enabled, the Morse chip will periodically emit a UDP packet of the following format regardless of whether it is in standby or not. The UDP packet will also be sent immediately upon entering or exiting Standby mode.

+----------------------+----------------------+--------------------------------+---------+
| Morse OUI (0c:bf:74) | Type: Standby (0x01) | Awake (0x00) or Standby (0x01) | Payload |
+----------------------+----------------------+--------------------------------+---------+

Note

The payload is optional and is not present if this function is not called.

Parameters

args	A pointer to the arguments for this function.

Returns

MMWLAN_SUCCESS on success or MMWLAN_ERROR on failure.

Warning

BETA NOTICE: This is beta API that is under development; breaking changes may be introduced in future releases.

mmwlan_standby_set_wake_filter()

enum mmwlan_status mmwlan_standby_set_wake_filter

(

const struct mmwlan_standby_set_wake_filter_args *

args

)

Configures the standby mode UDP wake packet filter.

The system can be woken up from standby mode by sending it a UDP wake packet of the following format. If a wake filter is set using this function then the wake packet will only wake up the system if the specified filter pattern matches the payload at the specified offset within the payload.

The wake packet has the following format:

+----------------------+----------------------+----------------+--------------------+
| Morse OUI (0c:bf:74) | Type: Standby (0x01) | Wake up (0x02) | Payload (optional) |
+----------------------+----------------------+----------------+--------------------+

Note

If a wake filter is not configured then the system will wake on any wake packet and the payload (if any) is ignored.

Parameters

args	A pointer to the arguments for this function.

Returns

MMWLAN_SUCCESS on success or MMWLAN_ERROR on failure.

Warning

BETA NOTICE: This is beta API that is under development; breaking changes may be introduced in future releases.