This release is largely a bug fix release, however it also makes Bluetooth support official and adds some new libraries and functionality.

Highlights are listed below, or you can see the full list of individual commits here, and the full list of resolved issues here.

Board Support

The following board has been added and may be specified via PICO_BOARD:

• pololu_3pi_2040_robot

The following board configurations have been modified:

• adafruit_itsybitsy_rp2040 - corrected the mismatched PICO_DEFAULT_I2C bus number (favors the breadboard pins not the stemma connector).
• sparkfun_thingplus - added WS2812 pin config.

Library Changes/Improvements

hardware_dma

• Added dma_channel_cleanup() function that can be used to clean up a dynamically claimed DMA channel after use, such that it won't be in a surprising state for the next user, making sure that any in-flight transfer is aborted, and no interrupts are left pending.

hardware_spi

• The spi_set_format, spi_set_slave, spi_set_baudrate functions that modify the configuration of an SPI instance, now disable the SPI while changing the configuration as specified in the data sheet.

pico_async_context

• Added user_data member to async_when_pending_worker_t to match async_at_time_worker_t.

pico_cyw43_arch

• Added cyw43_arch_disable_sta_mode() function to complement cyw43_arch_enable_sta_mode().
• Added cyw43_arch_disable_ap_mode() function to complement cyw43_arch_enable_ap_mode().

pico_stdio_usb

• The 20-character limit for descriptor strings USBD_PRODUCT and USBD_MANUFACTURER can now be extended by defining USBD_DESC_STR_MAX.
• PICO_STDIO_USB_CONNECT_WAIT_TIMEOUT_MS is now supported in the build as well as compiler definitions; if it is set in the build, it is added to the compile definitions.

pico_rand

• Fixed poor randomness when PICO_RAND_ENTROPY_SRC_BUS_PERF_COUNTER=1.

PLL and Clocks

• The set_sys_clock_pll and set_sys_clock_khz methods now reference a pre-processor define PICO_CLOCK_AJDUST_PERI_CLOCK_WITH_SYS_CLOCK. If set to 1, the peripheral clock is updated to match the new system clock, otherwise the preexisting behavior (of setting the peripheral clock to a safe 48Mhz) is preserved.
• Support for non-standard crystal frequencies, and compile-time custom clock configurations:
  • The new define XOSC_KHZ is used in preference to the preexisting XOSC_MHZ to define the crystal oscillator frequency. This value is now also correctly plumbed through the various clock setup functions, such that they behave correctly with a crystal frequency other than 12Mhz. XOSC_MHZ will be automatically defined for backwards compatibility if XOSC_KHZ is an exact multiple of 1000 Khz. Note that either XOSC_MHZ or XOSC_KHZ may be specified by the user, but not both.
  • The new define PLL_COMMON_REFDIV can be specified to override the default reference divider of 1.
  • The new defines PLL_SYS_VCO_FREQ_KHZ, PLL_SYS_POSTDIV1 and PLL_SYS_POSTDIV2 are used to configure the system clock PLL during runtime initialization. These are defaulted for you if SYS_CLK_KHZ=125000, XOSC_KHZ=12000 and PLL_COMMON_REFDIV=1. You can modify these values in your CMakeLists.txt if you want to configure a different system clock during runtime initialization, or are using a non-standard crystal.
  • The new defines PLL_USB_VCO_FREQ_KHZ, PLL_USB_POSTDIV1 and PLL_USB_POSTDIV2 are used to configure the USB clock PLL during runtime initialization. These are defaulted for you if USB_CLK_KHZ=48000, XOSC_KHZ=12000 and PLL_COMMON_REFDIV=1. You can modify these values in your CMakeLists.txt if you want to configure a different USB clock if you are using a non-standard crystal.
  • The new define PICO_PLL_VCO_MIN_FREQ_KHZ is used in preference to the pre-existing PICO_PLL_VCO_MIN_FREQ_MHZ, though specifying either is supported.
  • The new define PICO_PLL_VCO_MAX_FREQ_KHZ is used in preference to the pre-existing PICO_PLL_VCO_MAX_FREQ_MHZ, though specifying either is supported.

New Libraries

pico_flash

• This is a new higher level library than hardware_flash. It provides helper functions to facilitate getting into a state where it is safe to write to flash (the default implementation disables interrupts on the current core, and if necessary, makes sure the other core is running from RAM, and has interrupts disabled).
• Adds a flash_safe_execute() function to execute a callback function while in the "safe" state.
• Adds a flash_safe_execute_core_init() function which must be called from the "other core" when using pico_multicore to enable the cooperative support for entering a "safe" state.
• Supports user override of the mechanism by overriding the get_flash_safety_helper() function.

Miscellaneous

• All assembly (including inline) in the SDK now uses the unified syntax.
  • New C macros pico_default_asm( ... ) and pico_default_asm_volatile( ... ) are provided that are equivalent to __asm and __asm volatile blocks, but with a .syntax unified at the beginning.
• A new assembler macro pico_default_asm_setup is provided to configure the correct CPU and dialect.
• Some code cleanup to make the SDK code at least compile cleanly on Clang and IAR.

Build

• PICO_BOARD and PICO_BOARD_HEADER_DIRS now correctly use the latest environment variable value if present.

• A CMake performance regression due to repeated calls to find_package has been fixed.

• Experimental support is provided for compiling with Clang. As an example, you can build with the LLVM Embedded Toolchain for Arm, noting however that currently only version 14.0.0 works, as later versions use picolib rather than newlib.

  • Note that if you are using TinyUSB you need to use the latest master to compile with Clang.

  mkdir clang_build
  cd clang_build
  cmake -DPICO_COMPILER=pico_arm_clang -DPICO_TOOLCHAIN_PATH=/path/to/arm-embedded-llvm-14.0.0 ..
  make
  

Bluetooth Support for Pico W

The support is now official. Please find examples in pico-examples.

• The Bluetooth API is provided by BTstack.
• The following libraries are provided that expose core BTstack functionality:
  • pico_btstack_ble - Adds Bluetooth Low Energy (LE) support.
  • pico_btstack_classic - Adds Bluetooth Classic support.
  • pico_btstack_sbc_encoder - Adds Bluetooth Sub Band Coding (SBC) encoder support.
  • pico_btstack_sbc_decoder - Adds Bluetooth Sub Band Coding (SBC) decoder support.
  • pico_btstack_bnep_lwip - Adds Bluetooth Network Encapsulation Protocol (BNEP) support using LwIP.
  • pico_btstack_bnep_lwip_sys_freertos - Adds Bluetooth Network Encapsulation Protocol (BNEP) support using LwIP with FreeRTOS for NO_SYS=0.
• The following integration libraries are also provided:
  • pico_btstack_run_loop_async_context - provides a common async_context backed implementation of a BTstack "run loop" that can be used for all BTstack use with the pico-sdk.
  • pico_btstack_flash_bank - provides a sample implementation for storing required Bluetooth state in flash.
  • pico_btstack_cyw43 - integrates BTstack with the CYW43 driver.
• The CMake function pico_btstack_make_gatt_header can be used to run the BTstack compile_gatt tool to make a GATT header file from a BTstack GATT file.
• pico_cyw43_driver and cyw43_driver now support HCI communication for Bluetooth.
• cyw43_driver_picow now supports Pico W specific HCI communication for Bluetooth over SPI.
• cyw43_arch_init() and cyw43_arch_deinit() automatically handle Bluetooth support if CYW43_ENABLE_BLUETOOTH is 1 (as it will be automatically if you depend on pico_btstack_cyw43).

Key changes since 1.5.0:

• Added Raspberry Pi specific BTstack license.
• The storage offset in flash for pico_btstack_flash_bank can be specified at runtime by defining pico_flash_bank_get_storage_offset_func to your own function to return the offset within flash.
• pico_btstack_flash_bank is now safe for multicore / FreeRTOS SMP use, as it uses the new pico_flash library to make sure the other core is not accessing flash during flash updates. If you are using pico_multicoreyou must have called flash_safe_execute_core_init from the "other" core (to the one Bluetooth is running on).
• Automatically set Bluetooth MAC address to the correct MAC address (Wi-Fi MAC address + 1), as some devices do not have it set in OTP and were using the same default MAC from the Bluetooth chip causing collisions.
• Various bug-fixes and stability improvements (especially with concurrent Wi-Fi), including updating cyw43_driver and btstack to the newest versions.

Authors

Thanks to the following for their contributions:

2bndy5, agento2, Andrew Burge, Andrew Scheller, arjunak234, David Thacher, djazz, Graham Sanderson, hubiscode, James Hughes, Luke Wren, Malte Thiesen, Michael Busby, Mr. Green's Workshop, Paul Grayson, Peter Harper