API Reference Manual
r8305
|
Functions | |
int | wlp_set_wakeup_cb (void(*wakeupf)(void *ctx, int enable), void *ctx) |
Register a callback that will be called to wakeup the wifi device. | |
int | wlp_set_ps (int enable) |
Enable or disable WiFi power save. | |
int | wlp_conf_ps (uint8_t use_ps_poll, uint32_t ps_traffic_timeout, uint32_t ps_delay, uint8_t rx_all_dtim, uint16_t listen_interval) |
Configure WiFi power save parameters. | |
int | wlp_set_heartbeat (uint32_t ms_period) |
Configure the link heartbeat. | |
int | wlp_set_led (int enable) |
Enable/disable LEDs on the device. | |
int | wlp_set_poll_period (uint32_t ms_period) |
Configure the device IP-stack poll frequency. |
These functions configure features that affect power consumption. Achieving low power operation is always a tradeoff between some aspect of performance (or an entire feature) and the power consumption of the device. Beware that these functions can make the device difficult to reach. It is recommended that you verify the functionality of your application before attempting to reduce the power consumption with these functions.
In order to reduce the power consumption of the whole system there are three different domains to consider.
The WiFi radio power save modes are controlled by wlp_conf_ps() and wlp_set_ps(). The WiFi will, if so commanded by wlp_set_ps(), sleep whenever possible and will only wake up and turn on its receiver and transmitter when necessary.
Performance impact : Turning on WiFi power save will increase the average receive latency since the WiFi only gets notifications of pending packets at most once every beacon interval (which is usually 100ms).
Example : Enabling the WiFi power save mode
if (wlp_conf_ps(0, // use_ps_poll 200, // ps_traffic_timeout 2000, // ps_delay 1, // rx_all_dtim 1 // listen_interval ) < 0) { handle_error(); return; } // Enable WiFi power save wlp_set_ps(1);
The WiFi device can only sleep if it can be woken up by the host when the host wants to send a command or poll events. A requirement for the WiFi device to enter sleep mode is the presence of the WAKEUP pin which is used to wake the device whenever the host wants to communicate with it. The WAKEUP pin is not necessary for correct operation but the presence of the pin will cause the device to consume significantly less power.
Performance impact : A slight delay is introduced in the communication with the device.
Pin usage
1. Connect the WAKEUP pin on the WiFi device to a pin on the host that the application can control. The WAKEUP pin is an output pin on the host, active low, and has a pull-up resistor on the WiFi device.
2. Write a function wakeup_cb(void *ctx, int enable) that sets the WAKEUP pin if enable is 0 and clears the WAKEUP pin if enable is 1. The pin is active low which is why the logic may seem inverted.
3. Register the wakeup_cb() function with the wlp_api library using wlp_set_wakeup_cb(). The library will then automatically use the wakeup_cb() function to wake up the WiFi device whenever necessary.
Example : Supporting the WAKEUP pin
static void wakeup_cb(void *ctx, int enable) { if (enable) { // Signal wakeup (active low) owlgpio_clr(OWL_BOARD_SPB800P_WAKEUP_PIN); // Wait for the device to wake up owlboard_mdelay(30); } else { // Reset wakeup (active low) owlgpio_set(OWL_BOARD_SPB800P_WAKEUP_PIN); } } // Register a WAKEUP pin control callback. wlp_set_wakeup_cb(wakeup_cb, sh);
If the WiFi device has LEDs those can be disabled to conserve power.
Performance impact : None.
Example : Disable LEDs
wlp_set_led(0);
The IP stack on the WiFi device must be polled periodically. For TCP compliance the stack must be polled at least once every 250ms. In situations where minimum power consumption is desired and TCP is not used the polling interval can be increased.
Performance impact : DHCP and ARP timeouts are adversely affected. TCP functionality may be impaired. The poll period should not be increased beyond 250ms unless the traffic patterns are well known and known to work with the decreased timer resolution.
Example : Set the polling interval to 5s
wlp_set_poll_period(5000);
The host must normally poll the WiFi device to get notifications of asynchronous events (such as traffic pending from the WiFi). This requires the host to wake up periodically for the polling operation. To allow the host to sleep longer a HOST_ATTENTION pin is supported on some hardware revisions. If the WiFi device supports the HOST_ATTENTION pin it will signal on this pin whenever events are pending. The host only has to poll the WiFi device when the HOST_ATTENTION pin is signalled. This allows the host to sleep whenever the pin is not signalled.
Performance impact : None.
1. Connect the HOST_ATTENTION pin on the WiFi device to a pin on the host that the application can control. The HOST_ATTENTION pin is an input pin on the host, active low, and should have a pull-up resistor on the host.
2. Check if the WiFi device supports the HOST_ATTENTION pin by calling wlp_get_fw_caps(&caps) and checking if the flag WLP_CAP_HA_PIN is set in caps.
3. Make the application check the status of the HOST_ATTENTION pin as frequently as possible. Whenever the HOST_ATTENTION pin is low then wlp_poll() should be called until the HOST_ATTENTION pin goes high. This is different from the case when the HOST_ATTENTION pin is unavailable/unused (such as in legacy code, or when the WLP_CAP_HA_PIN is not set in the fw capabilities flag field), when the wlp_poll() function should be called unconditionally.
Example : Supporting the HOST_ATTENTION pin
static int ha_pin_is_signalled(void) { if (owlgpio_is_low(OWL_BOARD_SPB800P_HOST_ATTENTION_PIN)) return 1; return 0; } uint8_t fw_caps; wlp_get_fw_caps(&fw_caps); for (;;) { ... if (fw_caps & WLP_CAP_HA_PIN) { // If the host attention pin is present we // only poll if the pin is asserted (active low). // When the pin is asserted there's an event // pending from the SPB800 module. if (ha_pin_is_signalled()) wlp_poll(); } else { // Without the host attention pin we need to // poll the SPB800 periodically. This method will // prevent the SPB800 from using power save // level 1. wlp_poll(); } ... }
int wlp_conf_ps | ( | uint8_t | use_ps_poll, |
uint32_t | ps_traffic_timeout, | ||
uint32_t | ps_delay, | ||
uint8_t | rx_all_dtim, | ||
uint16_t | listen_interval | ||
) |
Configure WiFi power save parameters.
This call is not necessary to enable WiFi power save. If wlp_set_ps(1) is called before calling wlp_conf_ps() then default power save parameters are used.
Beware that setting rx_all_dtim to 0 and listen_interval to a large value (> 10) can make the device very difficult to reach. When rx_all_dtim is 0 you risk loosing multicast data because that data is transferred after a DTIM beacon. This will be particularly noticable when another entitity on the same network segment tries to reach the device and does not know which MAC address the device has. In this case an ARP packet is normally sent to the broadcast address and this will be unlikely to be heard by the device.
use_ps_poll | Use PS-Poll frames to retrieve buffered data. Any changes to this parameter will take effect upon next connect or when power save is enabled through wlp_set_ps(). Note: To retrieve one buffered packet, the ps poll scheme needs one ps poll packet to the AP instead of two null packets in the power management bit scheme. Ps poll avoids the overhead of traffic monitoring time in active mode as well. But since each ps poll request can make the AP release only one buffered packet, it is not the optimal scheme for applications with heavy downlink traffic. |
ps_traffic_timeout | Timeout in [ms] to wait for more buffered data from AP. This setting has no effect if use_ps_poll is 1. Any changes to this parameter will take effect immediately. |
ps_delay | Power save will de delayed ps_delay [ms] after connecting to an AP. |
rx_all_dtim | If set to 1, then STA will wake up to listen to every beacon containing DTIM (delivery traffic indication messages) when connected. The actual DTIM interval is configured in the AP. If the DTIM interval, as configured in the AP, is larger than listen_interval, the STA will wakeup according to the listen_interval parameter. Note that if rx_all_dtim is set to 0 and listen_interval is set to something larger than 1 you risk missing reception of broadcast/multicast data because the AP will transmit that in conjunction with a DTIM beacon. |
listen_interval | The Listen Interval field is used to indicate to the AP how often a STA in power save mode wakes to listen to beacon frames. The value of this parameter is expressed in units of Beacon Interval. An AP may use the Listen Interval information in determining the lifetime of frames that it buffers for a STA. Any changes to this parameter will take effect upon next association. |
int wlp_set_heartbeat | ( | uint32_t | ms_period | ) |
Configure the link heartbeat.
Some access points disconnects stations that have been idle (that have not sent any data) for some period of time. They may disconnect the station explicitly or they may silently drop the connection. This can cause problems if the device is a passive listener (waiting for data that may never come because the connection has been silently dropped). The link heartbeat can be used to work around this limitation.
If the heartbeat period is > 0 then a NULL data frame will be sent to the access point at the specified period whenever a WiFi connection has been established.
Bear in mind that a low value for period will increase the power consumption of the device. A reasonable value is 60000 or 120000 (sending heartbeats every 1 or 2 minutes).
This function does not do anything in the AP-mode.
The default heartbeat period is 60s.
period | The heartbeat period in milliseconds. 0 will disable the heartbeat functionality. |
int wlp_set_led | ( | int | enable | ) |
Enable/disable LEDs on the device.
DEPRECATED
The 2 LEDs that light when the WiFi link and the IP link is up can be disabled to conserve power.
This function does not control the state of the LEDs (it cannot be used to light the LEDs). If called with enable set to 0 it will disable the LEDs completely. If called with enable set to 1 the LEDs will be controlled by the internal link control logic (which is the default behaviour).
enable | 1 to turn on the LED link indicator function. 0 to turn LEDs completely off. |
int wlp_set_poll_period | ( | uint32_t | ms_period | ) |
Configure the device IP-stack poll frequency.
DEPRECATED
The device must wake up periodically to run timers required by the IP stack. The wake up frequency affects power consumption. To provide a IETF-compliant TCP connection the poll period must be 250ms or less. If no TCP connection is active, or if only UDP/RAW data is handled, then it may be possible to increase the poll period to a couple of seconds to reduce power consumption.
Be aware that long polling periods can have large and hard-to-predict consequences on network connectivity at the IP layer and above.
This function only controls the polling frequency of the IP stack in the device itself. It is unrelated to the wlp_poll() function which is running on the host, not on the device.
Note that when the wakeup-pin is supported (see wlp_set_wakeup_cb()) and asserted then the device is kept awake (and continuously checking pending timers) irrespective of the poll period. The poll period is only used when the device actually sleeps.
ms_period | Poll period in ms. |
int wlp_set_ps | ( | int | enable | ) |
Enable or disable WiFi power save.
Enable/disable legacy power save mode (as opposed to WMM power save which is not supported in the current driver). In legacy power save mode, the device will power down when idle. When connected, the device will wake up to receive beacon frames and any buffered data from the AP. The response time when legacy power save is enabled might therefore be as long as the AP beacon interval (commonly 100 ms). However, the throughput should not be affected.
enable | determines if WiFi power save should be enabled or disabled. |
int wlp_set_wakeup_cb | ( | void(*)(void *ctx, int enable) | wakeupf, |
void * | ctx | ||
) |
Register a callback that will be called to wakeup the wifi device.
The callback will be invoked to control a wakeup-pin if one is present on the current host platform. The wakeup-pin, if present, is connected to the wifi device and is required if the wifi device should be able to operate in the lowest power mode (power save level 1). If the wakeupf() function is called with enable set to 1 the wakeup-pin must be pulled low and if enable is set to 0 the wakeup-pin must be pulled high. If the wakeupf() callback is not provided then the wifi device can only operate in power save level 2.
wakeupf | Wakeup-pin control function. |
ctx | is an opaque context pointer that will be passed back to readf, writef and selectf. |