Status led library

Functions for turning a binary led on and off and setting value of a
colour status led.

Fixes #188

Author: peterharperuk

src/rp2_common/pico_status_led/BUILD.bazel

@@ -0,0 +1,28 @@
+load("//bazel:defs.bzl", "compatible_with_rp2")
+
+package(default_visibility = ["//visibility:public"])
+
+cc_library(
+    name = "pico_status_led",
+    srcs = ["status_led.c"],
+    hdrs = ["include/pico/status_led.h"],
+    includes = ["include"],
+    target_compatible_with = compatible_with_rp2(),
+    deps = [
+        "//src/rp2_common:hardware_gpio",
+        "//src/rp2_common/hardware_pio",
+    ] + select({
+        "//bazel/constraint:is_pico_w": [
+            "//src/rp2_common/pico_cyw43_driver",
+        ],
+        "//bazel/constraint:is_pico2_w": [
+            "//src/rp2_common/pico_cyw43_driver"
+        ],
+        "//conditions:default": [],
+    }),
+)
+
+pico_generate_pio_header(
+    name = "ws2812",
+    srcs = ["ws2812.pio"],
+)

src/rp2_common/pico_status_led/CMakeLists.txt

@@ -0,0 +1,22 @@
+pico_add_library(pico_status_led)
+target_sources(pico_status_led INTERFACE
+    ${CMAKE_CURRENT_LIST_DIR}/status_led.c
+)
+target_include_directories(pico_status_led_headers SYSTEM INTERFACE
+    ${CMAKE_CURRENT_LIST_DIR}/include
+)
+pico_mirrored_target_link_libraries(pico_status_led INTERFACE
+    hardware_gpio
+    hardware_pio
+)
+if (PICO_CYW43_SUPPORTED)
+    pico_mirrored_target_link_libraries(pico_status_led INTERFACE
+        pico_cyw43_driver pico_async_context_threadsafe_background
+    )
+    target_compile_definitions(pico_status_led INTERFACE
+        CYW43_LWIP_DEFAULT=0 # Disable LwIP by default. Can be overridden if LwIP is needed.
+    )
+endif()
+pico_generate_pio_header(pico_status_led ${CMAKE_CURRENT_LIST_DIR}/ws2812.pio)
+
+get_target_property(OUT pico_status_led LINK_LIBRARIES)

src/rp2_common/pico_status_led/include/pico/status_led.h

@@ -0,0 +1,124 @@
+/*
+ * Copyright (c) 2025 Raspberry Pi (Trading) Ltd.
+ *
+ * SPDX-License-Identifier: BSD-3-Clause
+ */
+
+/** \file pico/status_led.h
+ *  \defgroup pico_status_led pico_status_led
+ *
+ * \brief Enables access to the on-board status leds
+ *
+ * Boards usually have access to an on-board status leds which are configured via the board header (\see PICO_DEFAULT_LED_PIN and \see PICO_DEFAULT_WS2812_PIN)
+ * This library hides the details so you can use the status leds for all boards without changing your code.
+ */
+
+#ifndef _PICO_STATUS_LED_H
+#define _PICO_STATUS_LED_H
+
+#include "hardware/gpio.h"
+
+struct async_context;
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+// PICO_CONFIG: PICO_STATUS_LED_WS2812_WRGB, Inidicate if the colored status led supports WRGB, type=bool, default=false group=pico_status_led
+#ifndef PICO_STATUS_LED_WS2812_WRGB
+#define PICO_STATUS_LED_WS2812_WRGB 0
+#endif
+
+/*! \brief Initialise the status leds
+ *  \ingroup pico_status_led
+ *
+ *  Initialise the status leds and the resources they need before use.
+ *
+ * \param context The hardware for some devices (e.g. Pico W) requires an async context.
+ * You can usually only have one of these. Pass the async context into the function or pass NULL to get the function to just create a context for it's own use if needed .
+ * \return Returns true if the led was initialised successfully, otherwise an error occurred
+ */
+bool pico_status_led_init(struct async_context *context);
+
+/*! \brief Set the status led on or off
+ *  \ingroup pico_status_led
+ *
+ * \note: If your hardware does not support a status led (\see PICO_DEFAULT_LED_PIN), this function does nothing and returns false.
+ *
+ * \param led_on True to turn the led on. Pass False to turn the led off
+ * \param True if the status led could be set, otherwise false
+ */
+static inline bool pico_status_led_set(bool led_on) {
+#if defined PICO_DEFAULT_LED_PIN
+    gpio_put(PICO_DEFAULT_LED_PIN, led_on);
+#elif defined CYW43_WL_GPIO_LED_PIN
+    cyw43_arch_gpio_put(CYW43_WL_GPIO_LED_PIN, led_on);
+#endif
+    return true;
+}
+
+/*! \brief Get the state of the status led
+ *  \ingroup pico_status_led
+ *
+ * \note: If your hardware does not support a status led (\see PICO_DEFAULT_LED_PIN), this function always returns false.
+ *
+ * \return True if the led is on, or False if the led is off
+ */
+static inline bool pico_status_led_get(void) {
+#if defined PICO_DEFAULT_LED_PIN
+    return gpio_get(PICO_DEFAULT_LED_PIN);
+#elif defined CYW43_WL_GPIO_LED_PIN
+    return cyw43_arch_gpio_get(CYW43_WL_GPIO_LED_PIN);
+#else
+    return false;
+#endif
+}
+
+/*! \brief Set the colored status led value
+ *  \ingroup pico_status_led
+ *
+ * The colored status led defaults to off. Use this function to change its color.
+ *
+ * \note: If your hardware does not support a colored status led (\see PICO_DEFAULT_WS2812_PIN), this function does nothing and returns false.
+ *
+ * \param value The color of the colored status led in 0xWWRRGGBB format.
+ * \param True if the coloured status led could be set, otherwise false on failure
+ */
+bool pico_status_led_color_set(uint32_t value);
+
+/*! \brief Get the colored status led value
+ *  \ingroup pico_status_led
+ *
+ * \note: If your hardware does not support a colored status led (\see PICO_DEFAULT_WS2812_PIN), this function always returns 0x0.
+ *
+ * \return The color of the colored status led in 0xWWRRGGBB format.
+ */
+uint32_t pico_status_led_color_get(void);
+
+/*! \brief Generate an RGB colour value for /ref pico_status_led_color_set
+ *  \ingroup pico_status_led
+ */
+#define PICO_STATUS_LED_RGB(R, G, B) (((R) << 16) | ((G) << 8) | (B))
+
+/*! \brief Generate an WRGB colour value for \ref pico_status_led_color_set
+ *
+ *  \note: If your hardware does not support a white pixel, the white component is ignored
+ *
+ *  \ingroup pico_status_led
+ */
+#define PICO_STATUS_LED_WRGB(W, R, G, B) (((W) << 24) | ((R) << 16) | ((G) << 8) | (B))
+
+/*! \brief Deinitialise the status leds
+ *  \ingroup pico_status_led
+ *
+ * Deinitialises the status leds when they are no longer needed.
+ *
+ * \param context The async context to be used. This should be the same as the value passed into pico_status_led_init
+ */
+void pico_status_led_deinit(struct async_context *context);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif

src/rp2_common/pico_status_led/status_led.c

@@ -0,0 +1,111 @@
+/*
+ * Copyright (c) 2025 Raspberry Pi (Trading) Ltd.
+ *
+ * SPDX-License-Identifier: BSD-3-Clause
+ */
+
+#include "pico/status_led.h"
+
+#if defined(CYW43_WL_GPIO_LED_PIN)
+#include "pico/cyw43_driver.h"
+#include "pico/async_context_threadsafe_background.h"
+#endif
+
+#ifdef PICO_DEFAULT_WS2812_PIN
+#include <hardware/pio.h>
+#include "ws2812.pio.h"
+
+// PICO_CONFIG: PICO_STATUS_LED_WS2812_FREQ, Frequency per bit for the WS2812 status led pio, type=int, default=800000, group=pico_status_led
+#ifndef PICO_STATUS_LED_WS2812_FREQ
+#define PICO_STATUS_LED_WS2812_FREQ 800000
+#endif
+
+static PIO pio;
+static uint sm;
+static int offset = -1;
+static uint32_t ws2812_value;
+
+// Extract from 0xWWRRGGBB
+#define RED(C) ((C >> 16) & 0xff)
+#define GREEN(C) ((C >> 8) & 0xff)
+#define BLUE(C) ((C >> 0) & 0xff)
+#define WHITE(C) ((C >> 24) && 0xff)
+#endif // PICO_STATUS_LED_WS2812_PIN
+
+bool pico_status_led_color_set(uint32_t value) {
+#ifdef PICO_DEFAULT_WS2812_PIN
+    ws2812_value = value;
+    if (offset > -1) {
+#if PICO_STATUS_LED_WS2812_WRGB
+        // Convert to 0xWWGGRRBB
+        pio_sm_put_blocking(pio, sm, WHITE(ws2812_value) << 24 | GREEN(ws2812_value) << 16 | RED(ws2812_value) << 8 | BLUE(ws2812_value));
+#else
+        // Convert to 0xGGRRBB00
+        pio_sm_put_blocking(pio, sm, GREEN(ws2812_value) << 24 | RED(ws2812_value) << 16 | BLUE(ws2812_value) << 8);
+#endif //P ICO_STATUS_LED_WS2812_WRGB
+        return true;
+    }
+#else
+    (void)value;
+#endif // PICO_DEFAULT_WS2812_PIN
+    return false;
+}
+
+uint32_t pico_status_led_color_get(void) {
+#ifdef PICO_DEFAULT_WS2812_PIN
+    return ws2812_value;
+#else
+    return 0x0;
+#endif
+}
+
+#if defined(CYW43_WL_GPIO_LED_PIN)
+static async_context_threadsafe_background_t status_led_context;
+#endif
+
+bool pico_status_led_init(struct async_context *context) {
+#if defined(PICO_DEFAULT_LED_PIN)
+    gpio_init(PICO_DEFAULT_LED_PIN);
+    gpio_set_dir(PICO_DEFAULT_LED_PIN, GPIO_OUT);
+#elif defined(CYW43_WL_GPIO_LED_PIN)
+    assert(!status_led_context.core.type);
+    if (!context) {
+        async_context_threadsafe_background_config_t config = async_context_threadsafe_background_default_config();
+        if (!async_context_threadsafe_background_init(&status_led_context, &config)) {
+            return false;
+        }
+        if (!cyw43_driver_init(&status_led_context.core)) {
+            async_context_deinit(&status_led_context.core);
+            return false;
+        }
+    }
+#endif
+#if PICO_DEFAULT_WS2812_PIN
+    if (pio_claim_free_sm_and_add_program_for_gpio_range(&ws2812_program, &pio, &sm, &offset, PICO_DEFAULT_WS2812_PIN, 1, true)) {
+        ws2812_program_init(pio, sm, offset, PICO_DEFAULT_WS2812_PIN, PICO_STATUS_LED_WS2812_FREQ, PICO_STATUS_LED_WS2812_WRGB);
+    } else {
+        pico_status_led_deinit(context);
+        return false;
+    }
+#endif
+    return true;
+}
+
+void pico_status_led_deinit(struct async_context *context) {
+    // Note: We cannot deinit cyw43 in case it has other users
+#if defined(PICO_DEFAULT_LED_PIN)
+    gpio_deinit(PICO_DEFAULT_LED_PIN);
+#elif defined(CYW43_WL_GPIO_LED_PIN)
+    assert((context && !status_led_context.core.type) || (!context && status_led_context.core.type));
+    if (context) {
+        cyw43_driver_deinit(&status_led_context.core);
+        async_context_deinit(&status_led_context.core);
+    }
+#endif
+#if PICO_DEFAULT_WS2812_PIN
+    if (offset >= 0) {
+        pio_remove_program_and_unclaim_sm(&ws2812_program, pio, sm, offset);
+        offset = -1;
+    }
+#endif
+}

src/rp2_common/pico_status_led/ws2812.pio

@@ -0,0 +1,53 @@
+;
+; Copyright (c) 2020 Raspberry Pi (Trading) Ltd.
+;
+; SPDX-License-Identifier: BSD-3-Clause
+;
+.pio_version 0 // only requires PIO version 0
+
+.program ws2812
+.side_set 1
+
+; The following constants are selected for broad compatibility with WS2812,
+; WS2812B, and SK6812 LEDs. Other constants may support higher bandwidths for
+; specific LEDs, such as (7,10,8) for WS2812B LEDs.
+
+.define public T1 3
+.define public T2 3
+.define public T3 4
+
+.lang_opt python sideset_init = pico.PIO.OUT_HIGH
+.lang_opt python out_init     = pico.PIO.OUT_HIGH
+.lang_opt python out_shiftdir = 1
+
+.wrap_target
+bitloop:
+    out x, 1       side 0 [T3 - 1] ; Side-set still takes place when instruction stalls
+    jmp !x do_zero side 1 [T1 - 1] ; Branch on the bit we shifted out. Positive pulse
+do_one:
+    jmp  bitloop   side 1 [T2 - 1] ; Continue driving high, for a long pulse
+do_zero:
+    nop            side 0 [T2 - 1] ; Or drive low, for a short pulse
+.wrap
+
+% c-sdk {
+#include "hardware/clocks.h"
+
+static inline void ws2812_program_init(PIO pio, uint sm, uint offset, uint pin, float freq, bool rgbw) {
+
+    pio_gpio_init(pio, pin);
+    pio_sm_set_consecutive_pindirs(pio, sm, pin, 1, true);
+
+    pio_sm_config c = ws2812_program_get_default_config(offset);
+    sm_config_set_sideset_pins(&c, pin);
+    sm_config_set_out_shift(&c, false, true, rgbw ? 32 : 24);
+    sm_config_set_fifo_join(&c, PIO_FIFO_JOIN_TX);
+
+    int cycles_per_bit = ws2812_T1 + ws2812_T2 + ws2812_T3;
+    float div = clock_get_hz(clk_sys) / (freq * cycles_per_bit);
+    sm_config_set_clkdiv(&c, div);
+
+    pio_sm_init(pio, sm, offset, &c);
+    pio_sm_set_enabled(pio, sm, true);
+}
+%}