LED

Collaboration diagram for LED:

Macros
#define	HW_LED_GPIO_NONE   0xFFu
	Value returned when no default board LED GPIO is available.
#define	HW_LED_POOL_CAPACITY   8u
	Capacity of the LED handle pool. More...
#define	HW_LED_CONTEXT_SIZE   32
	Size in bytes of the per-handle scratch context space embedded in every hw_led_t, for a backend's own private per-LED state - a GPIO or PWM handle pointer, a NeoPixel chain's length/buffer pointer, a sysfs LED path pointer, and similar. More...

Typedefs
typedef struct hw_led_t	hw_led_t
	Opaque LED handle.

Enumerations
enum	hw_led_type_t {   hw_led_type_none = 0, hw_led_type_wifi, hw_led_type_neopixel, hw_led_type_gpio,   hw_led_type_pwm }
	Default board LED access type. More...

Lifecycle
hw_led_t *	hw_led_init_gpio (hw_gpio_t *gpio)
	Initialize a direct GPIO LED. More...
hw_led_t *	hw_led_init_neopixel (hw_gpio_t *gpio, uint8_t led_count)
	Initialize a NeoPixel/WS2812 LED data pin. More...
hw_led_t *	hw_led_init_wifi (void)
	Initialize a Wi-Fi controlled LED. More...
hw_led_t *	hw_led_init_pwm (hw_pwm_t *pwm)
	Initialize a PWM controlled LED. More...
hw_led_t *	hw_led_init_device (const char *name)
	Initialize an LED from a platform-specific device path or name. More...
hw_led_t *	hw_led_init_default (void)
	Initialize the default on-board LED. More...
void	hw_led_deinit (hw_led_t *led)
	Deinitialize an LED handle. More...

Properties
uint8_t	hw_led_gpio_default (hw_led_type_t *out_type, uint8_t *out_count)
	Return the default board LED's control pin. More...

Methods
bool	hw_led_set (hw_led_t *led, uint8_t index, bool enabled)
	Set LED state on or off. More...
bool	hw_led_set_brightness (hw_led_t *led, uint8_t index, float percent)
	Set LED brightness. More...
bool	hw_led_clear (hw_led_t *led)
	Turn off all LED state, cancelling any active blink. More...
bool	hw_led_blink (hw_led_t *led, uint8_t index, uint32_t period_ms, bool repeating)
	Blink an LED using a timer. More...

Detailed Description

Macro Definition Documentation

HW_LED_CONTEXT_SIZE

#define HW_LED_CONTEXT_SIZE   32

Size in bytes of the per-handle scratch context space embedded in every hw_led_t, for a backend's own private per-LED state - a GPIO or PWM handle pointer, a NeoPixel chain's length/buffer pointer, a sysfs LED path pointer, and similar.

Variable-length state (a sysfs path, a NeoPixel color buffer) is heap-allocated by the backend and only its pointer stored here, so this only needs to be big enough for a handful of pointer/scalar fields, not whatever the largest backend's data happens to be.

Override by defining HW_LED_CONTEXT_SIZE at compile time.

Definition at line 45 of file led.h.

HW_LED_POOL_CAPACITY

#define HW_LED_POOL_CAPACITY   8u

Capacity of the LED handle pool.

Override by defining HW_LED_POOL_CAPACITY at compile time.

Definition at line 28 of file led.h.

Enumeration Type Documentation

hw_led_type_t

enum hw_led_type_t

Default board LED access type.

Enumerator
hw_led_type_none	No default board LED is available.
hw_led_type_wifi	LED is controlled through CYW43 Wi-Fi GPIO.
hw_led_type_neopixel	LED is a WS2812/NeoPixel data pin.
hw_led_type_gpio	LED is a directly controlled GPIO pin.
hw_led_type_pwm	LED is controlled through PWM on a GPIO pin.

Definition at line 55 of file led.h.

             {
  hw_led_type_none = 0, 
  hw_led_type_wifi,     
  hw_led_type_neopixel, 
  hw_led_type_gpio,     
  hw_led_type_pwm,      
} hw_led_type_t;

Function Documentation

hw_led_blink()

bool hw_led_blink	(	hw_led_t *	led,
		uint8_t	index,
		uint32_t	period_ms,
		bool	repeating
	)

Blink an LED using a timer.

Parameters

led	LED handle.
index	NeoPixel index to update. Ignored for non-NeoPixel LED types.
period_ms	Blink period in milliseconds.
repeating	When true, blink repeats until hw_led_set or hw_led_clear is called to stop it. When false, LED is turned on immediately and turned off once after one period.

Return values

true	Blink started.
false	Handle is invalid, blink is already active on this handle, or timer setup failed.

Todo:

Not implemented yet - always returns false. Planned for a separate PR once the rest of the LED module has landed.

hw_led_clear()

bool hw_led_clear

(

hw_led_t *

led

)

Turn off all LED state, cancelling any active blink.

Parameters

led	LED handle.

For NeoPixel LED types, every LED in the chain is turned off, not just a single index.

Return values

true	State was cleared.
false	Handle is invalid or LED type is unsupported.

hw_led_deinit()

void hw_led_deinit

(

hw_led_t *

led

)

Deinitialize an LED handle.

Parameters

led	LED handle.

hw_led_gpio_default()

uint8_t hw_led_gpio_default	(	hw_led_type_t *	out_type,
		uint8_t *	out_count
	)

Return the default board LED's control pin.

Parameters

out_type	Optional destination for detected LED type.
out_count	Optional destination for LED count. Defaults to 1 for available LEDs, or 0 when no default LED is available.

Returns

The default board LED's control pin, or HW_LED_GPIO_NONE when no default on-board LED is available. For hw_led_type_wifi, this is a CYW43 Wi-Fi-chip GPIO index (e.g. CYW43_WL_GPIO_LED_PIN), not an RP2040 board pin - it isn't valid to pass to hw_gpio_init() or any other GPIO API, only to hw_led_init_wifi()'s own internals.

hw_led_init_default()

hw_led_t* hw_led_init_default

(

void

)

Initialize the default on-board LED.

The backend detects the default LED type and initializes the corresponding LED path automatically.

Returns

LED handle, or NULL when no default on-board LED is available or initialization fails.

hw_led_init_device()

hw_led_t* hw_led_init_device

(

const char *

name

)

Initialize an LED from a platform-specific device path or name.

Parameters

name	LED identifier, e.g. "led0" for /sys/class/leds/led0 on Linux.

Returns

LED handle, or NULL when unsupported or invalid.

This entry point is intended for platforms where LEDs are bound to a kernel driver and exposed by name rather than reachable as a raw GPIO - on Linux/Raspberry Pi, the on-board activity LED is owned by the LED class subsystem (/sys/class/leds/), not a GPIO userspace can toggle directly. Unsupported elsewhere.

hw_led_init_gpio()

hw_led_t* hw_led_init_gpio

(

hw_gpio_t *

gpio

)

Initialize a direct GPIO LED.

Parameters

gpio	GPIO handle for the LED pin.

Returns

LED handle, or NULL when unsupported or invalid.

hw_led_init_neopixel()

hw_led_t* hw_led_init_neopixel	(	hw_gpio_t *	gpio,
		uint8_t	led_count
	)

Initialize a NeoPixel/WS2812 LED data pin.

Parameters

gpio	GPIO handle for the NeoPixel data pin.
led_count	Number of NeoPixels in the daisy chain.

Returns

LED handle, or NULL when unsupported or invalid.

hw_led_init_pwm()

hw_led_t* hw_led_init_pwm

(

hw_pwm_t *

pwm

)

Initialize a PWM controlled LED.

Parameters

pwm	PWM handle for the LED.

The PWM output is forced to an off state during initialization.

Returns

LED handle, or NULL when unsupported or invalid.

hw_led_init_wifi()

hw_led_t* hw_led_init_wifi

(

void

)

Initialize a Wi-Fi controlled LED.

Returns

LED handle when CYW43 support is available, otherwise NULL.

hw_led_set()

bool hw_led_set	(	hw_led_t *	led,
		uint8_t	index,
		bool	enabled
	)

Set LED state on or off.

Parameters

led	LED handle.
index	NeoPixel index to update. Ignored for non-NeoPixel LED types.
enabled	true turns LED on, false turns LED off.

Return values

true	State update was applied.
false	Handle is invalid or LED type is unsupported.

hw_led_set_brightness()

bool hw_led_set_brightness	(	hw_led_t *	led,
		uint8_t	index,
		float	percent
	)

Set LED brightness.

Parameters

led	LED handle.
index	NeoPixel index to update. Ignored for non-NeoPixel LED types. For NeoPixel, brightness is per-index - each pixel keeps its own color untouched and independently scaled.
percent	Brightness percentage in [0.0, 100.0]. Values outside this range are clamped. GPIO and Wi-Fi LED types have no intermediate level - any nonzero value is just "on".

Return values

true	Brightness was applied.
false	Handle is invalid, or brightness control is unsupported by this LED type.