Data Structures | Defines | Enumerations | Functions

Library support functions

Data Structures

struct  wlp_network_t

Defines

#define WLP_INVALID_SOCKET_ID   0
#define WLP_INTERFACE_UART   0

Enumerations

enum  wlp_auth_mode { WLP_AUTH_AUTO = 0, WLP_AUTH_WEP, WLP_AUTH_WPA_PSK, WLP_AUTH_WPA2_PSK }

Functions

int wlp_init (int interface, int(*readf)(void *ctx, void *data, int len), int(*writef)(void *ctx, const void *data, int len), void(*selectf)(void *ctx, int select), void *ctx)
 Initialize the wifi device.
void wlp_set_yield_cb (void(*yieldf)(void *ctx), void *ctx)
 Register a callback that will be invoked when wlp_api is idle.
void wlp_irq (void)
 Handler for interrupts from device.
int wlp_set_baudrate (uint32_t baudrate, uint8_t rtscts)
 Change the baudrate of the device.
int wlp_reset (void)
int wlp_fw_upgrade (uint8_t method, struct ip_addr addr, uint16_t port, const char *path)
 Prepare the device for a firmware upgrade operation.
int wlp_get_fw_version (uint32_t *code, char *build, int build_len, char *hw_rev, int hw_rev_len)
 Get the firmware version.
int wlp_get_fw_caps (uint8_t *cap_flags)
 Get WiFi device capabilities.

Detailed Description

These functions manage the library in general.


Define Documentation

#define WLP_INTERFACE_UART   0
#define WLP_INVALID_SOCKET_ID   0

Enumeration Type Documentation


Function Documentation

int wlp_fw_upgrade ( uint8_t  method,
struct ip_addr  addr,
uint16_t  port,
const char *  path 
)

Prepare the device for a firmware upgrade operation.

Parameters:
method Specify how to retrieve the firmware image. The only currently supported method is WLP_UPGRADE_METHOD_HTTP_POST.
addr IP address. This parameter is ignored with method WLP_UPGRADE_METHOD_HTTP_POST.
port Port number. With WLP_UPGRADE_METHOD_HTTP_POST the port parameter specifies the port on which the upgrade web page will be presented.
path Path. This parameter is ignored with method WLP_UPGRADE_METHOD_HTTP_POST.
Returns:
  • 0 on success
  • WLP_ERR_PARAM
int wlp_get_fw_caps ( uint8_t *  cap_flags  ) 

Get WiFi device capabilities.

Some functionality is dependent on the capabilities of the WiFi device that wlp_api interfaces with. wlp_get_fw_caps() retrieves a flag field describing the capabilities of the attached WiFi device.

The following capabilities are supported:

  • WLP_CAP_HA_PIN

The device supports a Host Attention pin. The presence of the Host Attention pin allows the WiFi device to alert the host when there is pending activity and wlp_poll() should be called. This allows the host to enter power save states if it can be woken up when the host attention pin is asserted. It also allows the WiFi device to spend longer times in power save state (since calling wlp_poll() will wake it up). The host attention pin is active low so that a low voltage on the pin means that the host should call wlp_poll() repeatedly until the host attention pin voltage changes to high. If the WLP_CAP_HA_PIN is not present in the cap_flags field then the host attention pin will not be manipulated by the WiFi device and wlp_poll() should be called as often as is practicable. The host cannot sleep for long periods if this is the case. See the Functions to manage power consumption section for a further discussion on how to use this flag.

  • WLP_CAP_WAKEUP_PIN

The device supports a Wakeup pin. The presence of the Wakeup pin allows the WiFi device to enter deeper power save modes where the Wakeup pin is used to wake it up from sleep.

Parameters:
cap_flags Contains a bitmask of the supported capabilities flags on output.
Returns:
  • 0 on success
int wlp_get_fw_version ( uint32_t *  code,
char *  build,
int  build_len,
char *  hw_rev,
int  hw_rev_len 
)

Get the firmware version.

Parameters:
code will contain the fw version code upon successful return. The version can be compared to the driver version (WLP_VERSION_CODE) using the WLP_VERSION(), WLP_MAJOR_VERSION(), WLP_MINOR_VERSION() and the WLP_PATCH_VERSION() macros.
build will hold the build information upon successful return. The build information is a string of information for the particular fw build used on the device. No more than
len characters, including null termination, will be copied to the string pointed to by build. This parameter can be NULL.
build_len is the maximum amount of chars, including null termination, that will be copied to
build. 
hw_rev will hold the hardware revision string upon successful return. The hardware revision string describes the particular PCB revision and model of the pico server device. hw_rev has the format "<rev>:<board>", or is an empty string if the revision information is not available on the current pico device. No more than
len characters, including null termination, will be copied to the string. This parameter can be NULL.
hw_rev_len is the maximum amount of chars, including null termination, that will be copied to
hw_rev. 
Returns:
  • 0 on success
  • WLP_FAILURE if any failure occurs
int wlp_init ( int  interface,
int(*)(void *ctx, void *data, int len)  readf,
int(*)(void *ctx, const void *data, int len)  writef,
void(*)(void *ctx, int select)  selectf,
void *  ctx 
)

Initialize the wifi device.

Initialize the wlp api and configure the uart settings on the wifi device. Must be called before any other function in the wlp api.

wlp_init() will send a 'w' character, a 'w' will be received once the wifi device is ready. The 'w' chars must be transmitted and received at 115200 8N1.

Note again that the uart which the callback parameters readf and writef uses must be configured for 115200 8N1 before calling wlp_init().

Allow the wifi device up to 200 ms to boot before calling wlp_init() after power up.

The sequence on the host becomes 1) Power on host and wifi device 2) Wait 200 ms 3) Call wlp_init() with host uart configured as 115200 8N1 4) Done, now the wifi device is ready to use.

Parameters:
interface selects the host communication interface. This can be either WLP_INTERFACE_UART or WLP_INTERFACE_SPI.
readf is a pointer to a function which reads chars from the bus which the wifi device is connected to and stores them in the location pointed to by the data paramter. Note that readf should block until the number of bytes specified in the len parameter are read. This function must be able to handle NULL buffer arguments, in which case the read data should be discarded.
writef should read chars from the location pointed to by the data paramter send them to the bus which the wifi device is connected to. Note that writef should block until the number of bytes specified in the len parameter are written.
selectf will be invoked before and after any write-read transaction. For UART interfaces, this function could e.g. disable/enable interrupts on the host to ensure the UART data flow. For SPI interfaces, this could assert/desassert the chip select signal connected to the device. If the select parameter is 1, the transaction will start when this function has returned. If the select parameter is 0, the transaction is completed.
ctx is an opaque context pointer that will be passed back to readf, writef and selectf.
Returns:
  • 0 on success
void wlp_irq ( void   ) 

Handler for interrupts from device.

This function should be called when an interrupt is received from the device.

Since the wlp_api functions generally commuicates with the device and blocks until a reponse is received, the wlp_irq() naturally needs to be called from a different context (e.g. another thread or an interrupt handler) to avoid infinite blocking. However, any calls to wlp_poll() should not be invoked from a different context unless concurrency protection is ensured by e.g. semaphores.

int wlp_reset ( void   ) 

Reset the device. wlp_init() must be called after wlp_reset() to complete the reset. This function is typically used to switch betweeen AP and STA modes after wlp_set_mode() has been used.

NOTE: In this release the baudrate must be 115200 before this function is called. See wlp_set_baudrate() for details on how to change the baudrate.

int wlp_set_baudrate ( uint32_t  baudrate,
uint8_t  rtscts 
)

Change the baudrate of the device.

Send a uart configuration message which will configure the wifi device according to the provided baudrate and rtscts parameters.

Upon successful return, the wifi device will use the new uart configuration. The host must change its uart settings accordingly before any other function in wlp_api is called.

The sequence on the host becomes 1) Call wlp_set_baudrate() to reconfigure the device baudrate. 2) Wait 100 ms afer wlp_set_baudrate() has returned to allow the device to reconfigure its uart. 3) Reconfigure host uart baudrate. 4) Done, now the wifi device is ready to use with the new baudrate setting.

The device supports the following baudrates:

 *
 *    Baudrate | Error (%)
 *    --------------------
 *       9600  | 0
 *      19200  | 0
 *      38400  | 0
 *      57600  | 0.08
 *     115200  | 0.16
 *     230400  | 0.16
 *     460800  | 0.16
 *     921600  | 0.16
 *    1000000  | 0
 *    1500000  | 0
 *    2000000  | 0
 *    3000000  | 0
 *    4000000  | 0
 *
 * 

Note that the actual baudrate used might differ from the desired baudrate. This is due to the fractional baud rate generation. It is recommended to keep the sum of the transmitter and receiver error less than 2.00 %. As shown by the table above, the SPB800 has a very small fractional error on the baudrates.

Parameters:
baudrate is the baudrate which the wifi device should switch to.
rtcts is the hardware handshake configuration which the wifi device should switch to. Set to 1 to enabled hardware handshaking, and 0 to disable hardware handshaking. Any hardware handshake will use the RTS and CTS pins.
readf is a pointer to a function which reads chars from the bus which the wifi device is connected to and stores them in the location pointed to by the data paramter. Note that readf should block until the number of bytes specified in the len parameter are read.
writef should read chars from the location pointed to by the data paramter send them to the bus which the wifi device is connected to. Note that writef should block until the number of bytes specified in the len parameter are written.
ctx is an opaque context pointer that will be passed back to readf and writef.
Returns:
  • 0 on success
  • WLP_ERR_PARAM if invalid baudrate or rtscts parameters.
void wlp_set_yield_cb ( void(*)(void *ctx)  yieldf,
void *  ctx 
)

Register a callback that will be invoked when wlp_api is idle.

The yield callback can be used by the host to perform other tasks while waiting for a response from the device. The yield callback will be invoked when any function in the wlp_api is called that involves communication with the device. The yield callback can also be used to e.g. put the host in sleep mode until the response from the device is ready.

The yield callback will only be used in case the WLP_INTERFACE_SPI was used in the call to wlp_init().

Parameters:
yieldf is a pointer to a function which will be invoked when any function in the wlp_api is waiting for a response from the device.
ctx is an opaque context pointer that will be passed back to yieldf.