Skip to content

Commit 9ddbb2a

Browse files
kilograhamkilograham
committed
Rework the API a little/lot
1 parent d49eca6 commit 9ddbb2a

File tree

2 files changed

+244
-210
lines changed

2 files changed

+244
-210
lines changed

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

Lines changed: 152 additions & 123 deletions
Original file line numberDiff line numberDiff line change
@@ -7,10 +7,10 @@
77
/** \file pico/status_led.h
88
* \defgroup pico_status_led pico_status_led
99
*
10-
* \brief Enables access to the on-board status leds
10+
* \brief Enables access to the on-board status LED(s)
1111
*
12-
* 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)
13-
* This library hides the details so you can use the status leds for all boards without changing your code.
12+
* 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)
13+
* This library hides the details so you can use the status LEDs for all boards without changing your code.
1414
*/
1515

1616
#ifndef _PICO_STATUS_LED_H
@@ -28,188 +28,217 @@ struct async_context;
2828
extern "C" {
2929
#endif
3030

31-
// PICO_CONFIG: PICO_STATUS_LED_COLOR_WRGB, Indicate if the colored status led supports WRGB, type=bool, default=0, group=pico_status_led
32-
#ifndef PICO_STATUS_LED_COLOR_WRGB
33-
#define PICO_STATUS_LED_COLOR_WRGB 0
31+
// PICO_CONFIG: PICO_STATUS_LED_AVAILABLE, Indicate whether a non-colored status LED is availble, 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
32+
#ifndef PICO_STATUS_LED_AVAILABLE
33+
#if defined(PICO_DEFAULT_LED_PIN) || defined(CYW43_WL_GPIO_LED_PIN)
34+
#define PICO_STATUS_LED_AVAILABLE 1
35+
#else
36+
#define PICO_STATUS_LED_AVAILABLE 0
37+
#endif
3438
#endif
3539

36-
// PICO_CONFIG: PICO_STATUS_LED_COLOR_ONLY, Indicate if only the colored status led should be used. Only true by default if a WS2812 pin is defined and no led pin is defined, type=bool, group=pico_status_led
40+
// PICO_CONFIG: PICO_COLORED_STATUS_LED_AVAILABLE, Indicate whether a colored status LED is availble, type=bool, default=1 if PICO_DEFAULT_WS2812_PIN is defined; may be set by the user to 0 to not use either even if available, group=pico_status_led
41+
#ifndef PICO_COLORED_STATUS_LED_AVAILABLE
3742
#ifdef PICO_DEFAULT_WS2812_PIN
38-
#ifndef PICO_STATUS_LED_COLOR_ONLY
39-
#define PICO_STATUS_LED_COLOR_ONLY !(defined PICO_DEFAULT_LED_PIN || defined CYW43_WL_GPIO_LED_PIN)
40-
#endif
43+
#define PICO_COLORED_STATUS_LED_AVAILABLE 1
4144
#else
42-
// Force this off if PICO_DEFAULT_WS2812_PIN is not defined
43-
#undef PICO_STATUS_LED_COLOR_ONLY
44-
#define PICO_STATUS_LED_COLOR_ONLY 0
45+
#define PICO_COLORED_STATUS_LED_AVAILABLE 0
46+
#endif
47+
#endif
48+
49+
// PICO_CONFIG: PICO_STATUS_LED_VIA_COLORED_STATUS_LED, Indicate if the colored status LED should be used for both status_led and colored_status_led APIs. type=bool, default=1 if PICO_COLORED_STATUS_LED_AVAILABLE is 1 and PICO_STATUS_LED_AVAILABLE is 0, group=pico_status_led
50+
#ifndef PICO_STATUS_LED_VIA_COLORED_STATUS_LED
51+
#define PICO_STATUS_LED_VIA_COLORED_STATUS_LED (PICO_COLORED_STATUS_LED_AVAILABLE && !PICO_STATUS_LED_AVAILABLE)
52+
#endif
53+
54+
// PICO_CONFIG: PICO_COLORED_STATUS_LED_USES_WRGB, Indicate if the colored status LED supports WRGB, type=bool, default=0, group=pico_status_led
55+
#ifndef PICO_COLORED_STATUS_LED_USES_WRGB
56+
#define PICO_COLORED_STATUS_LED_USES_WRGB 0
4557
#endif
4658

47-
/*! \brief Generate an RGB color value for /ref pico_status_led_color_set_on_value
59+
/*! \brief Generate an RGB color value for /ref colored_status_led_set_on_with_color
4860
* \ingroup pico_status_led
4961
*/
50-
#ifndef PICO_STATUS_LED_COLOR_FROM_RGB
51-
#define PICO_STATUS_LED_COLOR_FROM_RGB(r, g, b) (((r) << 16) | ((g) << 8) | (b))
62+
#ifndef PICO_COLORED_STATUS_LED_COLOR_FROM_RGB
63+
#define PICO_COLORED_STATUS_LED_COLOR_FROM_RGB(r, g, b) (((r) << 16) | ((g) << 8) | (b))
5264
#endif
5365

54-
/*! \brief Generate an WRGB color value for \ref pico_status_led_color_set_on_value
66+
/*! \brief Generate an WRGB color value for \ref colored_status_led_set_on_with_color
5567
* \ingroup pico_status_led
5668
*
5769
* \note: If your hardware does not support a white pixel, the white component is ignored
5870
*/
59-
#ifndef PICO_STATUS_LED_COLOR_FROM_WRGB
60-
#define PICO_STATUS_LED_COLOR_FROM_WRGB(w, r, g, b) (((w) << 24) | ((r) << 16) | ((g) << 8) | (b))
71+
#ifndef PICO_COLORED_STATUS_LED_COLOR_FROM_WRGB
72+
#define PICO_COLORED_STATUS_LED_COLOR_FROM_WRGB(w, r, g, b) (((w) << 24) | ((r) << 16) | ((g) << 8) | (b))
6173
#endif
6274

63-
// PICO_CONFIG: PICO_STATUS_LED_COLOR_ON_DEFAULT, the default pixel color value of the colored status led when it is on, type=int, group=pico_status_led
64-
#ifndef PICO_STATUS_LED_COLOR_ON_DEFAULT
65-
#if PICO_STATUS_LED_COLOR_WRGB
66-
#define PICO_STATUS_LED_COLOR_ON_DEFAULT PICO_STATUS_LED_WRGB(0xaa, 0, 0, 0)
75+
// PICO_CONFIG: PICO_DEFUALT_COLORED_STATUS_LED_ON_COLOR, the default pixel color value of the colored status LED when it is on, type=int, group=pico_status_led
76+
#ifndef PICO_DEFUALT_COLORED_STATUS_LED_ON_COLOR
77+
#if PICO_COLORED_STATUS_LED_USES_WRGB
78+
#define PICO_DEFUALT_COLORED_STATUS_LED_ON_COLOR PICO_COLORED_STATUS_LED_COLOR_FROM_WRGB(0xaa, 0, 0, 0)
6779
#else
68-
#define PICO_STATUS_LED_COLOR_ON_DEFAULT PICO_STATUS_LED_RGB(0xaa, 0xaa, 0xaa)
80+
#define PICO_DEFAULT_COLORED_STATUS_LED_ON_COLOR PICO_COLORED_STATUS_LED_COLOR_FROM_RGB(0xaa, 0xaa, 0xaa)
6981
#endif
7082
#endif
7183

72-
// PICO_CONFIG: PICO_STATUS_LED_COLOR_OFF, the pixel color value of the colored status led when it is off, type=int, group=pico_status_led
73-
#ifndef PICO_STATUS_LED_COLOR_OFF
74-
#if PICO_STATUS_LED_COLOR_WRGB
75-
#define PICO_STATUS_LED_COLOR_OFF PICO_STATUS_LED_WRGB(0, 0, 0, 0)
76-
#else
77-
#define PICO_STATUS_LED_COLOR_OFF PICO_STATUS_LED_RGB(0, 0, 0)
78-
#endif
79-
#endif
80-
81-
/*! \brief Initialise the status leds
84+
/*! \brief Initialize the status LED(s)
8285
* \ingroup pico_status_led
8386
*
84-
* Initialise the status leds and the resources they need before use.
87+
* Initialize the status LED(s) and the resources they need before use. On some devices (e.g. Pico W, Pico 2 W) accessing
88+
* the status LED requires talking to the WiFi chip, which requires an \ref async_context. This method will create one for you,
89+
* however an application only one has a single \ref async_context instance to talk to the WiFi chip, you should use \ref
90+
* status_led_init_with_context instead and pass it the \ref async_context already created within your application
8591
*
86-
* \note: You must call this function before using any other status led functions.
92+
* \note: You must call this function (or \ref status_led_init_with_context) before using any other pico_status_led functions.
8793
*
88-
* \param context An async context is needed to control the led on some devices (e.g. Pico W).
89-
* You generally only have one async context, so pass your async context into the function if you have one, or pass NULL if you know one isn't needed (not Pico W) oror if you don't have one, pass NULL to get the function to just create a context for it's own use as and if required.
90-
* \return Returns true if the led was initialised successfully, otherwise false on failure
94+
* \return Returns true if the LED was initialized successfully, otherwise false on failure
95+
* \sa status_led_init_with_context
9196
*/
92-
bool pico_status_led_init(void);
97+
bool status_led_init(void);
9398

94-
/*! \brief Initialise the status leds
99+
/*! \brief Initialise the status LED(s)
95100
* \ingroup pico_status_led
96101
*
97-
* Initialise the status leds and the resources they need before use.
102+
* Initialize the status LED(s) and the resources they need before use.
98103
*
99-
* \note: You must call this function before using any other status led functions.
104+
* \note: You must call this function (or \ref status_led_init) before using any other pico_status_led functions.
100105
*
101-
* \param context An async context is needed to control the led on some devices (e.g. Pico W).
102-
* You generally only have one async context, so pass your async context into the function if you have one, or pass NULL if you know one isn't needed (not Pico W) oror if you don't have one, pass NULL to get the function to just create a context for it's own use as and if required.
103-
* \return Returns true if the LED was initialised successfully, otherwise false on failure
106+
* \param context An \ref async_context used to communicate with the status LED (e.g. on Pico W or Pico 2 W)
107+
* \return Returns true if the LED was initialized successfully, otherwise false on failure
108+
* \sa status_led_init_with_context
104109
*/
105-
bool pico_status_led_init_with_context(struct async_context *context);
110+
bool status_led_init_with_context(struct async_context *context);
106111

107-
/*! \brief Set the status led on or off
112+
/*! \brief Determine if the `colored_status_led_` APIs are supported (i.e. if there is a colored status LED, and its
113+
* use isn't disabled via \ref PICO_COLORED_STATUS_LED_AVAILABLE being set to 0
108114
* \ingroup pico_status_led
109-
*
110-
* \note: If your hardware does not support a status led (\see PICO_DEFAULT_LED_PIN), this function does nothing and returns false.
111-
*
112-
* \param led_on True to turn the led on. Pass False to turn the led off
113-
* \param True if the status led could be set, otherwise false
115+
* \return true if the colored status LED API is available and expected to produce visible results
116+
* \sa PICO_COLORED_STATUS_LED_AVAILABLE
114117
*/
115-
static inline bool status_led_set_state(bool led_on) {
116-
#if PICO_STATUS_LED_COLOR_ONLY
117-
return pico_status_led_color_set(led_on);
118-
#elif defined PICO_DEFAULT_LED_PIN
119-
#if defined(PICO_DEFAULT_LED_PIN_INVERTED) && PICO_DEFAULT_LED_PIN_INVERTED
120-
gpio_put(PICO_DEFAULT_LED_PIN, !led_on);
121-
#else
122-
gpio_put(PICO_DEFAULT_LED_PIN, led_on);
123-
#endif
124-
return true;
125-
#elif defined CYW43_WL_GPIO_LED_PIN
126-
cyw43_gpio_set(&cyw43_state, CYW43_WL_GPIO_LED_PIN, led_on);
127-
return true;
128-
#else
129-
return false;
130-
#endif
118+
static inline bool colored_status_led_supported() {
119+
return PICO_COLORED_STATUS_LED_AVAILABLE;
131120
}
132121

133-
/*! \brief Get the state of the status led
122+
/*! \brief Determine if the colored status LED is being used for the non-colored `status_led_` APIs
134123
* \ingroup pico_status_led
135-
*
136-
* \note: If your hardware does not support a status led (\see PICO_DEFAULT_LED_PIN), this function always returns false.
137-
*
138-
* \return True if the status led is on, or False if the status led is off
124+
* \return true if the olored status LED is being used for the non-colored `status_led_` API
125+
* \sa PICO_STATUS_LED_VIA_COLORED_STATUS_LED
139126
*/
140-
static inline bool status_led_get_state() {
141-
#if PICO_STATUS_LED_COLOR_ONLY
142-
return pico_status_led_color_get();
143-
#elif defined PICO_DEFAULT_LED_PIN
144-
#if defined(PICO_DEFAULT_LED_PIN_INVERTED) && PICO_DEFAULT_LED_PIN_INVERTED
145-
return !gpio_get(PICO_DEFAULT_LED_PIN);
146-
#else
147-
return gpio_get(PICO_DEFAULT_LED_PIN);
148-
#endif
149-
#elif defined CYW43_WL_GPIO_LED_PIN
150-
bool value = false;
151-
cyw43_gpio_get(&cyw43_state, CYW43_WL_GPIO_LED_PIN, &value);
152-
return value;
153-
#else
154-
return false;
155-
#endif
127+
static inline bool status_led_via_colored_status_led() {
128+
return PICO_STATUS_LED_VIA_COLORED_STATUS_LED;
129+
}
130+
131+
/*! \brief Determine if the non-colored `status_led_` APIs are supported (i.e. if there is a regular LED, and its
132+
* use isn't disabled via \ref PICO_STATUS_LED_AVAILABLE being set to 0, or if the colored status LED is being used for
133+
* \ingroup pico_status_led
134+
* \return true if the non-colored status LED API is available and expected to produce visible results
135+
* \sa PICO_STATUS_LED_AVAILABLE
136+
* \sa PICO_STATUS_LED_VIA_COLORED_STATUS_LED
137+
*/
138+
static inline bool status_led_supported() {
139+
if (status_led_via_colored_status_led()) {
140+
return colored_status_led_supported();
141+
}
142+
return PICO_STATUS_LED_AVAILABLE;
156143
}
157144

158-
/*! \brief Set the color used for the status led when it is on
145+
/*! \brief Set the colored status LED on or off
159146
* \ingroup pico_status_led
160147
*
161-
* \note: If your hardware does not support a colored status led (\see PICO_DEFAULT_WS2812_PIN), this function does nothing and returns false.
148+
* \note: If your hardware does not support a colored status LED (\see PICO_DEFAULT_WS2812_PIN), this function does nothing and returns false.
162149
*
163-
* \param value The color to use for the colored status led when it is on, in 0xWWRRGGBB format
164-
* \param True if the colored status led could be set, otherwise false on failure
150+
* \param led_on true to turn the colored LED on. Pass false to turn the colored LED off
151+
* \return true if the colored status LED could be set, otherwise false
165152
*/
153+
bool colored_status_led_set_state(bool led_on);
166154

167-
static inline bool status_led_set_state(bool led_on);
168-
static inline bool status_led_get_state();
169-
170-
bool status_led_coloroed_set_on_color(uint32_t color);
171-
bool status_led_coloroed_set_on_with_color(uint32_t color);
172-
bool status_led_coloroed_set_state(bool on);
173-
bool status_led_coloroed_get_state();
174-
uint32_t colored_status_led_on_get_color(uint32_t color);
175-
176-
177-
/*! \brief Get the color used for the status led value when it is on
155+
/*! \brief Get the state of the colored status LED
178156
* \ingroup pico_status_led
179157
*
180-
* \note: If your hardware does not support a colored status led (\see PICO_DEFAULT_WS2812_PIN), this function always returns 0x0.
158+
* \note: If your hardware does not support a colored status LED (\see PICO_DEFAULT_WS2812_PIN), this function returns false.
181159
*
182-
* \return The color used for the colored status led when it is on, in 0xWWRRGGBB format
160+
* \return true if the colored status LED is on, or false if the colored status LED is off
183161
*/
184-
uint32_t pico_status_led_color_get_on_value(void);
185-
186-
/*! \brief Set the colored status led on or off
162+
bool colored_status_led_get_state();
163+
164+
/*! \brief Ensure the colored status LED is on, with the specified color
187165
* \ingroup pico_status_led
188166
*
189-
* \note: If your hardware does not support a colored status led (\see PICO_DEFAULT_WS2812_PIN), this function does nothing and returns false.
167+
* \note: If your hardware does not support a colored status LED (\see PICO_DEFAULT_WS2812_PIN), this function does nothing and returns false.
190168
*
191-
* \param led_on True to turn the colored led on. Pass False to turn the colored led off
192-
* \param True if the colored status led could be set, otherwise false
169+
* \param color The color to use for the colored status LED when it is on, in 0xWWRRGGBB format
170+
* \return true if the coloured status LED could be set, otherwise false on failure
193171
*/
194-
bool pico_status_led_color_set(bool led_on);
172+
bool colored_status_led_set_on_with_color(uint32_t color);
195173

196-
/*! \brief Get the state of the colored status led
174+
/*! \brief Get the color used for the status LED value when it is on
197175
* \ingroup pico_status_led
198176
*
199-
* \note: If your hardware does not support a colored status led (\see PICO_DEFAULT_WS2812_PIN), this function returns false.
177+
* \note: If your hardware does not support a colored status LED (\see PICO_DEFAULT_WS2812_PIN), this function always returns 0x0.
200178
*
201-
* \return True if the colored status led is on, or False if the colored status led is off
202-
*/
203-
bool pico_status_led_color_get(void);
179+
* \return The color used for the colored status LED when it is on, in 0xWWRRGGBB format
180+
*/
181+
uint32_t colored_status_led_get_on_color(void);
204182

205-
/*! \brief Deinitialise the status leds
183+
/*! \brief Set the status LED on or off
184+
* \ingroup pico_status_led
185+
*
186+
* \note: If your hardware does not support a status LED (\see PICO_DEFAULT_LED_PIN), this function does nothing and returns false.
187+
*
188+
* \param led_on true to turn the LED on. Pass false to turn the LED off
189+
* \return true if the status LED could be set, otherwise false
190+
*/
191+
static inline bool status_led_set_state(bool led_on) {
192+
if (status_led_via_colored_status_led()) {
193+
return colored_status_led_set_state(led_on);
194+
} else if (status_led_supported()) {
195+
#if defined(PICO_DEFAULT_LED_PIN)
196+
#if PICO_DEFAULT_LED_PIN_INVERTED
197+
gpio_put(PICO_DEFAULT_LED_PIN, !led_on);
198+
#else
199+
gpio_put(PICO_DEFAULT_LED_PIN, led_on);
200+
#endif
201+
return true;
202+
#elif defined(CYW43_WL_GPIO_LED_PIN)
203+
cyw43_gpio_set(&cyw43_state, CYW43_WL_GPIO_LED_PIN, led_on);
204+
return true;
205+
#endif
206+
}
207+
return false;
208+
}
209+
210+
/*! \brief Get the state of the status LED
206211
* \ingroup pico_status_led
207212
*
208-
* Deinitialises the status leds when they are no longer needed.
213+
* \note: If your hardware does not support a status LED (\see PICO_DEFAULT_LED_PIN), this function always returns false.
214+
*
215+
* \return true if the status LED is on, or false if the status LED is off
216+
*/
217+
static inline bool status_led_get_state() {
218+
if (status_led_via_colored_status_led()) {
219+
return colored_status_led_get_state();
220+
} else if (status_led_supported()) {
221+
#if defined(PICO_DEFAULT_LED_PIN)
222+
#if PICO_DEFAULT_LED_PIN_INVERTED
223+
return !gpio_get(PICO_DEFAULT_LED_PIN);
224+
#else
225+
return gpio_get(PICO_DEFAULT_LED_PIN);
226+
#endif
227+
#elif defined CYW43_WL_GPIO_LED_PIN
228+
bool value = false;
229+
cyw43_gpio_get(&cyw43_state, CYW43_WL_GPIO_LED_PIN, &value);
230+
return value;
231+
#endif
232+
}
233+
return false;
234+
}
235+
236+
/*! \brief De-initialize the status LED(s)
237+
* \ingroup pico_status_led
209238
*
210-
* \param context The async context to be used. This should be the same as the value passed into pico_status_led_init
239+
* De-initializes the status LED(s) when they are no longer needed.
211240
*/
212-
void pico_status_led_deinit(struct async_context *context);
241+
void status_led_deinit();
213242

214243
#ifdef __cplusplus
215244
}

0 commit comments

Comments
 (0)