v2.0.0
Modules | Macros | Functions
pico_cyw43_arch
Networking Libraries

Architecture for integrating the CYW43 driver (for the wireless on Pico W) and lwIP (for TCP/IP stack) into the SDK. It is also necessary for accessing the on-board LED on Pico W. More...

## Modules
| cyw43_driver
| Driver used for Pico W wireless.

## Macros
#define | cyw43_arch_lwip_check() cyw43_thread_lock_check()
| Checks the caller has any locks required for calling into lwIP. More...

## Functions
int | cyw43_arch_init (void)
| Initialize the CYW43 architecture. More...
int | cyw43_arch_init_with_country (uint32_t country)
| Initialize the CYW43 architecture for use in a specific country. More...
void | cyw43_arch_deinit (void)
| De-initialize the CYW43 architecture. More...
async_context_t * | cyw43_arch_async_context (void)
| Return the current async_context currently in use by the cyw43_arch code. More...
void | cyw43_arch_set_async_context (async_context_t *context)
| Set the async_context to be used by the cyw43_arch_init. More...
async_context_t * | cyw43_arch_init_default_async_context (void)
| Initialize the default async_context for the current cyw43_arch type. More...
void | cyw43_arch_poll (void)
| Perform any processing required by the `cyw43_driver` or the TCP/IP stack. More...
void | cyw43_arch_wait_for_work_until (absolute_time_t until)
| Sleep until there is cyw43_driver work to be done. More...
uint32_t | cyw43_arch_get_country_code (void)
| Return the country code used to initialize cyw43_arch. More...
void | cyw43_arch_enable_sta_mode (void)
| Enables Wi-Fi STA (Station) mode. More...
void | cyw43_arch_disable_sta_mode (void)
| Disables Wi-Fi STA (Station) mode. More...
void | cyw43_arch_enable_ap_mode (const char *ssid, const char *password, uint32_t auth)
| Enables Wi-Fi AP (Access point) mode. More...
void | cyw43_arch_disable_ap_mode (void)
| Disables Wi-Fi AP (Access point) mode. More...
int | cyw43_arch_wifi_connect_blocking (const char *ssid, const char *pw, uint32_t auth)
| Attempt to connect to a wireless access point, blocking until the network is joined or a failure is detected. More...
int | cyw43_arch_wifi_connect_bssid_blocking (const char *ssid, const uint8_t *bssid, const char *pw, uint32_t auth)
| Attempt to connect to a wireless access point specified by SSID and BSSID, blocking until the network is joined or a failure is detected. More...
int | cyw43_arch_wifi_connect_timeout_ms (const char *ssid, const char *pw, uint32_t auth, uint32_t timeout)
| Attempt to connect to a wireless access point, blocking until the network is joined, a failure is detected or a timeout occurs. More...
int | cyw43_arch_wifi_connect_bssid_timeout_ms (const char *ssid, const uint8_t *bssid, const char *pw, uint32_t auth, uint32_t timeout)
| Attempt to connect to a wireless access point specified by SSID and BSSID, blocking until the network is joined, a failure is detected or a timeout occurs. More...
int | cyw43_arch_wifi_connect_async (const char *ssid, const char *pw, uint32_t auth)
| Start attempting to connect to a wireless access point. More...
int | cyw43_arch_wifi_connect_bssid_async (const char *ssid, const uint8_t *bssid, const char *pw, uint32_t auth)
| Start attempting to connect to a wireless access point specified by SSID and BSSID. More...
void | cyw43_arch_gpio_put (uint wl_gpio, bool value)
| Set a GPIO pin on the wireless chip to a given value. More...
bool | cyw43_arch_gpio_get (uint wl_gpio)
| Read the value of a GPIO pin on the wireless chip. More...
static void | cyw43_arch_lwip_begin (void)
| Acquire any locks required to call into lwIP. More...
static void | cyw43_arch_lwip_end (void)
| Release any locks required for calling into lwIP. More...
static int | cyw43_arch_lwip_protect (int(*func)(void *param), void *param)
| sad Release any locks required for calling into lwIP More...

## Detailed Description

Architecture for integrating the CYW43 driver (for the wireless on Pico W) and lwIP (for TCP/IP stack) into the SDK. It is also necessary for accessing the on-board LED on Pico W.

Both the low level `cyw43_driver` and the lwIP stack require periodic servicing, and have limitations on whether they can be called from multiple cores/threads.

`pico_cyw43_arch` attempts to abstract these complications into several behavioral groups:

- 'poll' - This not multi-core/IRQ safe, and requires the user to call cyw43_arch_poll periodically from their main loop
- 'thread_safe_background' - This is multi-core/thread/task safe, and maintenance of the driver and TCP/IP stack is handled automatically in the background
- 'freertos' - This is multi-core/thread/task safe, and uses a separate FreeRTOS task to handle lwIP and and driver work.

As of right now, lwIP is the only supported TCP/IP stack, however the use of `pico_cyw43_arch` is intended to be independent of the particular TCP/IP stack used (and possibly Bluetooth stack used) in the future. For this reason, the integration of lwIP is handled in the base (`pico_cyw43_arch`) library based on the #define CYW43_LWIP used by the `cyw43_driver`.

Note
  As of version 1.5.0 of the Raspberry Pi Pico SDK, the `pico_cyw43_arch` library no longer directly implements the distinct behavioral abstractions. This is now handled by the more general pico_async_context library. The user facing behavior of pico_cyw43_arch has not changed as a result of this implementation detail, however pico_cyw43_arch is now just a thin wrapper which creates an appropriate async_context and makes a simple call to add lwIP or cyw43_driver support as appropriate. You are free to perform this context creation and adding of lwIP, cyw43_driver or indeed any other additional future protocol/driver support to your async_context, however for now pico_cyw43_arch does still provide a few cyw43_ specific (i.e. Pico W) APIs for connection management, locking and GPIO interaction.
  The connection management APIs at least may be moved to a more generic library in a future release. The locking methods are now backed by their pico_async_context equivalents, and those methods may be used interchangeably (see cyw43_arch_lwip_begin, cyw43_arch_lwip_end and cyw43_arch_lwip_check for more details).
  For examples of creating of your own async_context and addition of `cyw43_driver` and `lwIP` support, please refer to the specific source files `cyw43_arch_poll.c`, `cyw43_arch_threadsafe_background.c` and `cyw43_arch_freertos.c`.

Whilst you can use the `pico_cyw43_arch` library directly and specify CYW43_LWIP (and other defines) yourself, several other libraries are made available to the build which aggregate the defines and other dependencies for you:

- pico_cyw43_arch_lwip_poll - For using the RAW lwIP API (in `NO_SYS=1` mode) without any background processing or multi-core/thread safety.

  The user must call cyw43_arch_poll periodically from their main loop.

  This wrapper library:

  - Sets `CYW43_LWIP=1` to enable lwIP support in `pico_cyw43_arch` and `cyw43_driver`.
  - Sets `PICO_CYW43_ARCH_POLL=1` to select the polling behavior.
  - Adds the `pico_lwip` as a dependency to pull in lwIP.

- pico_cyw43_arch_lwip_threadsafe_background - For using the RAW lwIP API (in `NO_SYS=1` mode) with multi-core/thread safety, and automatic servicing of the `cyw43_driver` and lwIP in background.

  Calls into the `cyw43_driver` high level API (cyw43.h) may be made from either core or from lwIP callbacks, however calls into lwIP (which is not thread-safe) other than those made from lwIP callbacks, must be bracketed with cyw43_arch_lwip_begin and cyw43_arch_lwip_end. It is fine to bracket calls made from within lwIP callbacks too; you just don't have to.

  Note
    lwIP callbacks happen in a (low priority) IRQ context (similar to an alarm callback), so care should be taken when interacting with other code.

  This wrapper library:

  - Sets `CYW43_LWIP=1` to enable lwIP support in `pico_cyw43_arch` and `cyw43_driver`
  - Sets `PICO_CYW43_ARCH_THREADSAFE_BACKGROUND=1` to select the thread-safe/non-polling behavior.
  - Adds the pico_lwip as a dependency to pull in lwIP.

  This library can also be used under the RP2040 port of FreeRTOS with lwIP in `NO_SYS=1` mode (allowing you to call `cyw43_driver` APIs from any task, and to call lwIP from lwIP callbacks, or from any task if you bracket the calls with cyw43_arch_lwip_begin and cyw43_arch_lwip_end. Again, you should be careful about what you do in lwIP callbacks, as you cannot call most FreeRTOS APIs from within an IRQ context. Unless you have good reason, you should probably use the full FreeRTOS integration (with `NO_SYS=0`) provided by `pico_cyw43_arch_lwip_sys_freertos`.

- pico_cyw43_arch_lwip_sys_freertos - For using the full lwIP API including blocking sockets in OS (`NO_SYS=0`) mode, along with with multi-core/task/thread safety, and automatic servicing of the `cyw43_driver` and the lwIP stack.

  This wrapper library:

  - Sets `CYW43_LWIP=1` to enable lwIP support in `pico_cyw43_arch` and `cyw43_driver`.
  - Sets `PICO_CYW43_ARCH_FREERTOS=1` to select the NO_SYS=0 lwip/FreeRTOS integration
  - Sets `LWIP_PROVIDE_ERRNO=1` to provide error numbers needed for compilation without an OS
  - Adds the `pico_lwip` as a dependency to pull in lwIP.
  - Adds the lwIP/FreeRTOS code from lwip-contrib (in the contrib directory of lwIP)

  Calls into the `cyw43_driver` high level API (cyw43.h) may be made from any task or from lwIP callbacks, but not from IRQs. Calls into the lwIP RAW API (which is not thread safe) must be bracketed with cyw43_arch_lwip_begin and cyw43_arch_lwip_end. It is fine to bracket calls made from within lwIP callbacks too; you just don't have to.

  Note
    this wrapper library requires you to link FreeRTOS functionality with your application yourself.

- pico_cyw43_arch_none - If you do not need the TCP/IP stack but wish to use the on-board LED.

  This wrapper library:

  - Sets `CYW43_LWIP=0` to disable lwIP support in `pico_cyw43_arch` and `cyw43_driver`

## Macro Definition Documentation

## ◆ cyw43_arch_lwip_check

void cyw43_arch_lwip_check | ( |  | void | ) | cyw43_thread_lock_check()

Checks the caller has any locks required for calling into lwIP.

The lwIP API is not thread safe. You should surround calls into the lwIP API with calls to cyw43_arch_lwip_begin and this method. Note these calls are not necessary (but harmless) when you are calling back into the lwIP API from an lwIP callback.

This method will assert in debug mode, if the above conditions are not met (i.e. it is not safe to call into the lwIP API)

Note
  as of SDK release 1.5.0, this is now equivalent to calling async_context_lock_check on the async_context associated with cyw43_arch and lwIP.

See also
  cyw43_arch_lwip_begin
  cyw43_arch_lwip_protect
  async_context_lock_check
  cyw43_arch_async_context

## Function Documentation

## ◆ cyw43_arch_async_context()

async_context_t * cyw43_arch_async_context | ( | void |  | ) |

Return the current async_context currently in use by the cyw43_arch code.

Returns
  the async_context.

## ◆ cyw43_arch_deinit()

void cyw43_arch_deinit | ( | void |  | ) |

De-initialize the CYW43 architecture.

This method de-initializes the `cyw43_driver` code and de-initializes the lwIP stack (if it was enabled at build time). Note this method should always be called from the same core (or RTOS task, depending on the environment) as cyw43_arch_init.

Additionally if the cyw43_arch is using its own async_context instance, then that instance is de-initialized.

## ◆ cyw43_arch_disable_ap_mode()

void cyw43_arch_disable_ap_mode | ( | void |  | ) |

Disables Wi-Fi AP (Access point) mode.

This Disbles the Wi-Fi in Access Point mode.

## ◆ cyw43_arch_disable_sta_mode()

void cyw43_arch_disable_sta_mode | ( | void |  | ) |

Disables Wi-Fi STA (Station) mode.

This disables the Wi-Fi in Station mode, disconnecting any active connection. You should subsequently check the status by calling cyw43_wifi_link_status.

## ◆ cyw43_arch_enable_ap_mode()

void cyw43_arch_enable_ap_mode | ( | const char * | ssid,
|  | const char * | password,
|  | uint32_t | auth
| ) |  |

Enables Wi-Fi AP (Access point) mode.

This enables the Wi-Fi in Access Point mode such that connections can be made to the device by other Wi-Fi clients

Parameters

  ssid | the name for the access point
  password | the password to use or NULL for no password.
  auth | the authorization type to use when the password is enabled. Values are CYW43_AUTH_WPA_TKIP_PSK, CYW43_AUTH_WPA2_AES_PSK, or CYW43_AUTH_WPA2_MIXED_PSK (see CYW43_AUTH_)

## ◆ cyw43_arch_enable_sta_mode()

void cyw43_arch_enable_sta_mode | ( | void |  | ) |

Enables Wi-Fi STA (Station) mode.

This enables the Wi-Fi in Station mode such that connections can be made to other Wi-Fi Access Points

## ◆ cyw43_arch_get_country_code()

uint32_t cyw43_arch_get_country_code | ( | void |  | ) |

Return the country code used to initialize cyw43_arch.

Returns
  the country code (see CYW43_COUNTRY_)

## ◆ cyw43_arch_gpio_get()

bool cyw43_arch_gpio_get | ( | uint | wl_gpio | ) |

Read the value of a GPIO pin on the wireless chip.

Note
  this method does not check for errors setting the GPIO. You can use the lower level cyw43_gpio_get instead if you wish to check for errors.

Parameters

  wl_gpio | the GPIO number on the wireless chip

Returns
  true if the GPIO is high, false otherwise

## ◆ cyw43_arch_gpio_put()

void cyw43_arch_gpio_put | ( | uint | wl_gpio,
|  | bool | value
| ) |  |

Set a GPIO pin on the wireless chip to a given value.

Note
  this method does not check for errors setting the GPIO. You can use the lower level cyw43_gpio_set instead if you wish to check for errors.

Parameters

  wl_gpio | the GPIO number on the wireless chip
  value | true to set the GPIO, false to clear it.

## ◆ cyw43_arch_init()

int cyw43_arch_init | ( | void |  | ) |

Initialize the CYW43 architecture.

This method initializes the `cyw43_driver` code and initializes the lwIP stack (if it was enabled at build time). This method must be called prior to using any other `pico_cyw43_arch`, `cyw43_driver` or lwIP functions.

Note
  this method initializes wireless with a country code of `PICO_CYW43_ARCH_DEFAULT_COUNTRY_CODE` which defaults to `CYW43_COUNTRY_WORLDWIDE`. Worldwide settings may not give the best performance; consider setting PICO_CYW43_ARCH_DEFAULT_COUNTRY_CODE to a different value or calling cyw43_arch_init_with_country

By default this method initializes the cyw43_arch code's own async_context by calling cyw43_arch_init_default_async_context, however the user can specify use of their own async_context by calling cyw43_arch_set_async_context() before calling this method

Returns
  0 if the initialization is successful, an error code otherwise

See also
  pico_error_codes

## ◆ cyw43_arch_init_default_async_context()

async_context_t * cyw43_arch_init_default_async_context | ( | void |  | ) |

Initialize the default async_context for the current cyw43_arch type.

This method initializes and returns a pointer to the static async_context associated with cyw43_arch. This method is called by cyw43_arch_init automatically if a different async_context has not been set by cyw43_arch_set_async_context

Returns
  the context or NULL if initialization failed.

## ◆ cyw43_arch_init_with_country()

int cyw43_arch_init_with_country | ( | uint32_t | country | ) |

Initialize the CYW43 architecture for use in a specific country.

This method initializes the `cyw43_driver` code and initializes the lwIP stack (if it was enabled at build time). This method must be called prior to using any other `pico_cyw43_arch`, `cyw43_driver` or lwIP functions.

By default this method initializes the cyw43_arch code's own async_context by calling cyw43_arch_init_default_async_context, however the user can specify use of their own async_context by calling cyw43_arch_set_async_context() before calling this method

Parameters

  country | the country code to use (see CYW43_COUNTRY_)

Returns
  0 if the initialization is successful, an error code otherwise

See also
  pico_error_codes

## ◆ cyw43_arch_lwip_begin()

cyw43_arch_lwip_begin | ( | void |  | ) |
| inlinestatic

Acquire any locks required to call into lwIP.

The lwIP API is not thread safe. You should surround calls into the lwIP API with calls to this method and cyw43_arch_lwip_end. Note these calls are not necessary (but harmless) when you are calling back into the lwIP API from an lwIP callback. If you are using single-core polling only (pico_cyw43_arch_poll) then these calls are no-ops anyway it is good practice to call them anyway where they are necessary.

Note
  as of SDK release 1.5.0, this is now equivalent to calling async_context_acquire_lock_blocking on the async_context associated with cyw43_arch and lwIP.

See also
  cyw43_arch_lwip_end
  cyw43_arch_lwip_protect
  async_context_acquire_lock_blocking
  cyw43_arch_async_context

## ◆ cyw43_arch_lwip_end()

void cyw43_arch_lwip_end | ( | void |  | ) |
| inlinestatic

Release any locks required for calling into lwIP.

The lwIP API is not thread safe. You should surround calls into the lwIP API with calls to cyw43_arch_lwip_begin and this method. Note these calls are not necessary (but harmless) when you are calling back into the lwIP API from an lwIP callback. If you are using single-core polling only (pico_cyw43_arch_poll) then these calls are no-ops anyway it is good practice to call them anyway where they are necessary.

Note
  as of SDK release 1.5.0, this is now equivalent to calling async_context_release_lock on the async_context associated with cyw43_arch and lwIP.

See also
  cyw43_arch_lwip_begin
  cyw43_arch_lwip_protect
  async_context_release_lock
  cyw43_arch_async_context

## ◆ cyw43_arch_lwip_protect()

int cyw43_arch_lwip_protect | ( | int(*)(void *param) | func,
|  | void * | param
| ) |  |
| inlinestatic

sad Release any locks required for calling into lwIP

The lwIP API is not thread safe. You can use this method to wrap a function with any locking required to call into the lwIP API. If you are using single-core polling only (pico_cyw43_arch_poll) then there are no locks to required, but it is still good practice to use this function.

Parameters

  func | the function ta call with any required locks held
  param | parameter to pass to `func`

Returns
  the return value from `func`

See also
  cyw43_arch_lwip_begin
  cyw43_arch_lwip_end

## ◆ cyw43_arch_poll()

void cyw43_arch_poll | ( | void |  | ) |

Perform any processing required by the `cyw43_driver` or the TCP/IP stack.

This method must be called periodically from the main loop when using a polling style `pico_cyw43_arch` (e.g. `pico_cyw43_arch_lwip_poll` ). It may be called in other styles, but it is unnecessary to do so.

## ◆ cyw43_arch_set_async_context()

void cyw43_arch_set_async_context | ( | async_context_t * | context | ) |

Set the async_context to be used by the cyw43_arch_init.

Note
  This method must be called before calling cyw43_arch_init or cyw43_arch_init_with_country if you wish to use a custom async_context instance.

Parameters

  context | the async_context to be used

## ◆ cyw43_arch_wait_for_work_until()

void cyw43_arch_wait_for_work_until | ( | absolute_time_t | until | ) |

Sleep until there is cyw43_driver work to be done.

This method may be called by code that is waiting for an event to come from the cyw43_driver, and has no work to do, but would like to sleep without blocking any background work associated with the cyw43_driver.

Parameters

  until | the time to wait until if there is no work to do.

## ◆ cyw43_arch_wifi_connect_async()

int cyw43_arch_wifi_connect_async | ( | const char * | ssid,
|  | const char * | pw,
|  | uint32_t | auth
| ) |  |

Start attempting to connect to a wireless access point.

This method tells the CYW43 driver to start connecting to an access point. You should subsequently check the status by calling cyw43_wifi_link_status.

Parameters

  ssid | the network name to connect to
  pw | the network password or NULL if there is no password required
  auth | the authorization type to use when the password is enabled. Values are CYW43_AUTH_WPA_TKIP_PSK, CYW43_AUTH_WPA2_AES_PSK, or CYW43_AUTH_WPA2_MIXED_PSK (see CYW43_AUTH_)

Returns
  0 if the scan was started successfully, an error code otherwise

See also
  pico_error_codes

## ◆ cyw43_arch_wifi_connect_blocking()

int cyw43_arch_wifi_connect_blocking | ( | const char * | ssid,
|  | const char * | pw,
|  | uint32_t | auth
| ) |  |

Attempt to connect to a wireless access point, blocking until the network is joined or a failure is detected.

Parameters

  ssid | the network name to connect to
  pw | the network password or NULL if there is no password required
  auth | the authorization type to use when the password is enabled. Values are CYW43_AUTH_WPA_TKIP_PSK, CYW43_AUTH_WPA2_AES_PSK, or CYW43_AUTH_WPA2_MIXED_PSK (see CYW43_AUTH_)

Returns
  0 if the initialization is successful, an error code otherwise

See also
  pico_error_codes

## ◆ cyw43_arch_wifi_connect_bssid_async()

int cyw43_arch_wifi_connect_bssid_async | ( | const char * | ssid,
|  | const uint8_t * | bssid,
|  | const char * | pw,
|  | uint32_t | auth
| ) |  |

Start attempting to connect to a wireless access point specified by SSID and BSSID.

This method tells the CYW43 driver to start connecting to an access point. You should subsequently check the status by calling cyw43_wifi_link_status.

Parameters

  ssid | the network name to connect to
  bssid | the network BSSID to connect to or NULL if ignored
  pw | the network password or NULL if there is no password required
  auth | the authorization type to use when the password is enabled. Values are CYW43_AUTH_WPA_TKIP_PSK, CYW43_AUTH_WPA2_AES_PSK, or CYW43_AUTH_WPA2_MIXED_PSK (see CYW43_AUTH_)

Returns
  0 if the scan was started successfully, an error code otherwise

See also
  pico_error_codes

## ◆ cyw43_arch_wifi_connect_bssid_blocking()

int cyw43_arch_wifi_connect_bssid_blocking | ( | const char * | ssid,
|  | const uint8_t * | bssid,
|  | const char * | pw,
|  | uint32_t | auth
| ) |  |

Attempt to connect to a wireless access point specified by SSID and BSSID, blocking until the network is joined or a failure is detected.

Parameters

  ssid | the network name to connect to
  bssid | the network BSSID to connect to or NULL if ignored
  pw | the network password or NULL if there is no password required
  auth | the authorization type to use when the password is enabled. Values are CYW43_AUTH_WPA_TKIP_PSK, CYW43_AUTH_WPA2_AES_PSK, or CYW43_AUTH_WPA2_MIXED_PSK (see CYW43_AUTH_)

Returns
  0 if the initialization is successful, an error code otherwise

See also
  pico_error_codes

## ◆ cyw43_arch_wifi_connect_bssid_timeout_ms()

int cyw43_arch_wifi_connect_bssid_timeout_ms | ( | const char * | ssid,
|  | const uint8_t * | bssid,
|  | const char * | pw,
|  | uint32_t | auth,
|  | uint32_t | timeout
| ) |  |

Attempt to connect to a wireless access point specified by SSID and BSSID, blocking until the network is joined, a failure is detected or a timeout occurs.

Parameters

  ssid | the network name to connect to
  bssid | the network BSSID to connect to or NULL if ignored
  pw | the network password or NULL if there is no password required
  auth | the authorization type to use when the password is enabled. Values are CYW43_AUTH_WPA_TKIP_PSK, CYW43_AUTH_WPA2_AES_PSK, or CYW43_AUTH_WPA2_MIXED_PSK (see CYW43_AUTH_)
  timeout | how long to wait in milliseconds for a connection to succeed before giving up

Returns
  0 if the initialization is successful, an error code otherwise

See also
  pico_error_codes

## ◆ cyw43_arch_wifi_connect_timeout_ms()

int cyw43_arch_wifi_connect_timeout_ms | ( | const char * | ssid,
|  | const char * | pw,
|  | uint32_t | auth,
|  | uint32_t | timeout
| ) |  |

Attempt to connect to a wireless access point, blocking until the network is joined, a failure is detected or a timeout occurs.

Parameters

  ssid | the network name to connect to
  pw | the network password or NULL if there is no password required
  auth | the authorization type to use when the password is enabled. Values are CYW43_AUTH_WPA_TKIP_PSK, CYW43_AUTH_WPA2_AES_PSK, or CYW43_AUTH_WPA2_MIXED_PSK (see CYW43_AUTH_)
  timeout | how long to wait in milliseconds for a connection to succeed before giving up

Returns
  0 if the initialization is successful, an error code otherwise

See also
  pico_error_codes