mirror/pico-sdk
1
0
Fork 0
mirror of https://github.com/raspberrypi/pico-sdk.git synced 2025-12-10 07:14:36 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions

pico_status_led doxygen improvements

Browse source
This commit is contained in:
Andrew Scheller 2025-07-28 20:11:27 +01:00
parent c493a3a64d
commit 2e7753a6b1
1 changed files with 19 additions and 17 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

36
src/rp2_common/pico_status_led/include/pico/status_led.h
View file

@ -9,8 +9,9 @@
* *
* \brief Enables access to the on-board status LED(s) * \brief Enables access to the on-board status LED(s)
* *
* 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) * Boards usually have access to one or two on-board status LEDs which are configured via the board header (PICO_DEFAULT_LED_PIN, CYW43_WL_GPIO_LED_PIN and/or PICO_DEFAULT_WS2812_PIN).
* This library hides the details so you can use the status LEDs for all boards without changing your code. * This library hides the low-level details so you can use the status LEDs for all boards without changing your code.
* \note If your board has both a single-color LED and a colored LED, you can independently control the single-color LED with the `status_led_` APIs, and the colored LED with the `colored_status_led_` APIs
*/ */
#ifndef _PICO_STATUS_LED_H #ifndef _PICO_STATUS_LED_H
@ -28,7 +29,7 @@ struct async_context;
extern "C" { extern "C" {
#endif #endif
// PICO_CONFIG: PICO_STATUS_LED_AVAILABLE, Indicate whether a non-colored status LED is available, type=bool, default=1 if PICO_DEFAULT_LED_PIN or CYW43_WL_GPIO_LED_PIN is defined; may be set by the user to 0 to not use either even if they are available, group=pico_status_led // PICO_CONFIG: PICO_STATUS_LED_AVAILABLE, Indicate whether a single-color status LED is available, type=bool, default=1 if PICO_DEFAULT_LED_PIN or CYW43_WL_GPIO_LED_PIN is defined; may be set by the user to 0 to not use either even if they are available, group=pico_status_led
#ifndef PICO_STATUS_LED_AVAILABLE #ifndef PICO_STATUS_LED_AVAILABLE
#if defined(PICO_DEFAULT_LED_PIN) || defined(CYW43_WL_GPIO_LED_PIN) #if defined(PICO_DEFAULT_LED_PIN) || defined(CYW43_WL_GPIO_LED_PIN)
#define PICO_STATUS_LED_AVAILABLE 1 #define PICO_STATUS_LED_AVAILABLE 1
@ -66,7 +67,7 @@ extern "C" {
/*! \brief Generate an WRGB color value for \ref colored_status_led_set_on_with_color /*! \brief Generate an WRGB color value for \ref colored_status_led_set_on_with_color
* \ingroup pico_status_led * \ingroup pico_status_led
* *
* \note: If your hardware does not support a white pixel, the white component is ignored * \note If your hardware does not support a white pixel, the white component is ignored
*/ */
#ifndef PICO_COLORED_STATUS_LED_COLOR_FROM_WRGB #ifndef PICO_COLORED_STATUS_LED_COLOR_FROM_WRGB
#define PICO_COLORED_STATUS_LED_COLOR_FROM_WRGB(w, r, g, b) (((w) << 24) | ((r) << 16) | ((g) << 8) | (b)) #define PICO_COLORED_STATUS_LED_COLOR_FROM_WRGB(w, r, g, b) (((w) << 24) | ((r) << 16) | ((g) << 8) | (b))
@ -92,7 +93,7 @@ extern "C" {
* If the application already has an async context (e.g. created by cyw43_arch_init) you should use \ref * If the application already has an async context (e.g. created by cyw43_arch_init) you should use \ref
* status_led_init_with_context instead and pass it the \ref async_context already created by your application * status_led_init_with_context instead and pass it the \ref async_context already created by your application
* *
* \note: You must call this function (or \ref status_led_init_with_context) before using any other pico_status_led functions. * \note You must call this function (or \ref status_led_init_with_context) before using any other pico_status_led functions.
* *
* \return Returns true if the LED was initialized successfully, otherwise false on failure * \return Returns true if the LED was initialized successfully, otherwise false on failure
* \sa status_led_init_with_context * \sa status_led_init_with_context
@ -104,7 +105,7 @@ bool status_led_init(void);
* *
* Initialize the status LED(s) and the resources they need before use. * Initialize the status LED(s) and the resources they need before use.
* *
* \note: You must call this function (or \ref status_led_init) before using any other pico_status_led functions. * \note You must call this function (or \ref status_led_init) before using any other pico_status_led functions.
* *
* \param context An \ref async_context used to communicate with the status LED (e.g. on Pico W or Pico 2 W) * \param context An \ref async_context used to communicate with the status LED (e.g. on Pico W or Pico 2 W)
* \return Returns true if the LED was initialized successfully, otherwise false on failure * \return Returns true if the LED was initialized successfully, otherwise false on failure
@ -122,19 +123,20 @@ static inline bool colored_status_led_supported(void) {
return PICO_COLORED_STATUS_LED_AVAILABLE; return PICO_COLORED_STATUS_LED_AVAILABLE;
} }
/*! \brief Determine if the colored status LED is being used for the non-colored `status_led_` APIs /*! \brief Determine if the colored status LED is being used for the single-color `status_led_` APIs
* \ingroup pico_status_led * \ingroup pico_status_led
* \return true if the olored status LED is being used for the non-colored `status_led_` API * \return true if the colored status LED is being used for the single-color `status_led_` API
* \sa PICO_STATUS_LED_VIA_COLORED_STATUS_LED * \sa PICO_STATUS_LED_VIA_COLORED_STATUS_LED
*/ */
static inline bool status_led_via_colored_status_led(void) { static inline bool status_led_via_colored_status_led(void) {
return PICO_STATUS_LED_VIA_COLORED_STATUS_LED; return PICO_STATUS_LED_VIA_COLORED_STATUS_LED;
} }
/*! \brief Determine if the non-colored `status_led_` APIs are supported (i.e. if there is a regular LED, and its /*! \brief Determine if the single-color `status_led_` APIs are supported (i.e. if there is a regular LED, and its
* use isn't disabled via \ref PICO_STATUS_LED_AVAILABLE being set to 0, or if the colored status LED is being used for * use isn't disabled via \ref PICO_STATUS_LED_AVAILABLE being set to 0, or if the colored status LED is being used for
* the single-color `status_led_` APIs
* \ingroup pico_status_led * \ingroup pico_status_led
* \return true if the non-colored status LED API is available and expected to produce visible results * \return true if the single-color status LED API is available and expected to produce visible results
* \sa PICO_STATUS_LED_AVAILABLE * \sa PICO_STATUS_LED_AVAILABLE
* \sa PICO_STATUS_LED_VIA_COLORED_STATUS_LED * \sa PICO_STATUS_LED_VIA_COLORED_STATUS_LED
*/ */
@ -148,7 +150,7 @@ static inline bool status_led_supported(void) {
/*! \brief Set the colored status LED on or off /*! \brief Set the colored status LED on or off
* \ingroup pico_status_led * \ingroup pico_status_led
* *
* \note: If your hardware does not support a colored status LED (\see PICO_DEFAULT_WS2812_PIN), this function does nothing and returns false. * \note If your hardware does not support a colored status LED (PICO_DEFAULT_WS2812_PIN), this function does nothing and returns false.
* *
* \param led_on true to turn the colored LED on. Pass false to turn the colored LED off * \param led_on true to turn the colored LED on. Pass false to turn the colored LED off
* \return true if the colored status LED could be set, otherwise false * \return true if the colored status LED could be set, otherwise false
@ -158,7 +160,7 @@ bool colored_status_led_set_state(bool led_on);
/*! \brief Get the state of the colored status LED /*! \brief Get the state of the colored status LED
* \ingroup pico_status_led * \ingroup pico_status_led
* *
* \note: If your hardware does not support a colored status LED (\see PICO_DEFAULT_WS2812_PIN), this function returns false. * \note If your hardware does not support a colored status LED (PICO_DEFAULT_WS2812_PIN), this function returns false.
* *
* \return true if the colored status LED is on, or false if the colored status LED is off * \return true if the colored status LED is on, or false if the colored status LED is off
*/ */
@ -167,17 +169,17 @@ bool colored_status_led_get_state(void);
/*! \brief Ensure the colored status LED is on, with the specified color /*! \brief Ensure the colored status LED is on, with the specified color
* \ingroup pico_status_led * \ingroup pico_status_led
* *
* \note: If your hardware does not support a colored status LED (\see PICO_DEFAULT_WS2812_PIN), this function does nothing and returns false. * \note If your hardware does not support a colored status LED (PICO_DEFAULT_WS2812_PIN), this function does nothing and returns false.
* *
* \param color The color to use for the colored status LED when it is on, in 0xWWRRGGBB format * \param color The color to use for the colored status LED when it is on, in 0xWWRRGGBB format
* \return true if the coloured status LED could be set, otherwise false on failure * \return true if the colored status LED could be set, otherwise false on failure
*/ */
bool colored_status_led_set_on_with_color(uint32_t color); bool colored_status_led_set_on_with_color(uint32_t color);
/*! \brief Get the color used for the status LED value when it is on /*! \brief Get the color used for the status LED value when it is on
* \ingroup pico_status_led * \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. * \note If your hardware does not support a colored status LED (PICO_DEFAULT_WS2812_PIN), this function always returns 0x0.
* *
* \return The color used for the colored status LED when it is on, in 0xWWRRGGBB format * \return The color used for the colored status LED when it is on, in 0xWWRRGGBB format
*/ */
@ -186,7 +188,7 @@ uint32_t colored_status_led_get_on_color(void);
/*! \brief Set the status LED on or off /*! \brief Set the status LED on or off
* \ingroup pico_status_led * \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. * \note If your hardware does not support a status LED, this function does nothing and returns false.
* *
* \param led_on true to turn the LED on. Pass false to turn the LED off * \param led_on true to turn the LED on. Pass false to turn the LED off
* \return true if the status LED could be set, otherwise false * \return true if the status LED could be set, otherwise false
@ -213,7 +215,7 @@ static inline bool status_led_set_state(bool led_on) {
/*! \brief Get the state of the status LED /*! \brief Get the state of the status LED
* \ingroup pico_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. * \note If your hardware does not support a status LED, this function always returns false.
* *
* \return true if the status LED is on, or false if the status LED is off * \return true if the status LED is on, or false if the status LED is off
*/ */