Peripheral: LED: Add pulsing LED API

[MetaGlennA]

This is a proposal to modify the Zephyr LED interface for multi-channel ‘breathing’ LED drivers.

A breathing LED driver may have the following parameters per channel:

1. Delay before first pulse begins
2. Rise time from off to on
3. On-time
4. Fall time from on to off
5. Off-time until the start of the next rise

The current LED API only has a square-wave On-Time and Off-Time for the led_blink() function.

The led_blink() function also does not support synchronizing the start of blinking on a multi-channel device.

I propose an led_pulse() function to handle multi-channel breathing LEDs.

The function signature would be:

int led_pulse(const struct device *dev, struct led_pulse_parameter *parameters)

The parameters argument takes a pointer to an array of struct led_pulse_parameter objects with the following members:

struct led_pulse_parameter {
	uint8_t brightness;
	uint32_t start_delay_ms;
	uint32_t rise_time_ms;
	uint32_t on_time_ms;
	uint32_t fall_time_ms;
	uint32_t off_time_ms;
};

The number of items in the array is the same as the number of channels on the device.

If a channel is to be set to always on or always off rather than pulsing this can be accomplished through the led_pulse() command as well:

• If on, set all time values to zero except on_time_ms
• If off, set all time values to zero except off_time_ms

The API already has a brightness command, so having it in the led_pulse_parameter struct is open to debate.

[nordicjm]

@simonguinot

[simonguinot]

Hello @MetaGlennA,

Thanks for starting this discussion.

Do you own a LED controller with a pulse capability you need to take advantage of ?

For me the question is: is the kernel the right place to implement software LED effects ? So far, my opinion is no. I think that sotfware LED effects should go in a user module/library/layer on the top of the kernel API. And the kernel API should be limited to expose the hardware capabilities to userland. So the relevance of a pulse API depends on the availability of a such feature on LED controllers.

About the API proposal itself, it could be interesting to split the brightness parameter into two parameters: brightness_low and brightness_high. This should allow to configure the minimum and maximum level of a breathing/pulse LED effect. Also you may want to be able to set the initial color of a LED (in the case of a multicolor LED).

On my side I am using the following definitions for a breathing/pulse LED effect:

/**
 * @brief Enumeration of the different states during a breath LED effect.
 *
 * @note The order of the states is important. They are applied by the LED
 *       effect function following this order.
 */
enum breath_state {
        /* @brief High brightness level. */
        BREATH_HIGH = 0,
        /* @brief Brightness level is moving from the high to the low state. */
        BREATH_RAMP_DOWN,
        /* @brief Low brightness level. */
        BREATH_LOW,
        /* @brief Brightness level is moving from the low to the high state. */
        BREATH_RAMP_UP,
        /* @brief Number of states during a breath effect. */
        BREATH_MAX_STATE,
};

/**
 * @brief Breath LED effect structure.
 *
 * @param colors           Color array to apply before starting the effect.
 *                         This parameter is only relevant for multicolor LEDs.
 *                         And if omitted for multicolor LEDs, then the breath
 *                         effect will apply to their current colors.
 * @param delay            Array to keep the delay to spend at each state
 *                         (in milliseconds).
 * @param brightness_high  Brightness at high state.
 * @param brightness_low   Brightness at low state.
 * @param state            Current breath state (see enum breath_state).
 */
struct breath {
        uint8_t         colors[LED_MAX_COLORS];
        uint16_t        delay[BREATH_MAX_STATE];
        uint8_t         brightness_high;
        uint8_t         brightness_low;
};

[MetaGlennA]

Do you own a LED controller with a pulse capability you need to take advantage of ?

Yes, we do. It has the parameters listed built into the hardware. We're currently using a driver-specific API for it but would like to make a suitable generic interface for all future LED drivers we may use.

For me the question is: is the kernel the right place to implement software LED effects ? So far, my opinion is no. I think that sotfware LED effects should go in a user module/library/layer on the top of the kernel API. And the kernel API should be limited to expose the hardware capabilities to userland. So the relevance of a pulse API depends on the availability of a such feature on LED controllers.

We already expose the led_blink() as part of the API, so are expecting hardware control over the LED by the driver beyond on/off/brightness/colour. led_breathe() would just implement a better version for more capable LED controllers.

About the API proposal itself, it could be interesting to split the brightness parameter into two parameters: brightness_low and brightness_high. This should allow to configure the minimum and maximum level of a breathing/pulse LED effect. Also, you may want to be able to set the initial color of a LED (in the case of a multicolor LED).

That makes sense and I welcome the suggestion. We do have led_brightness() and led_color() in the API which could handle those tasks separately to prevent the struct getting too unwieldy, given we need to pass in a copy for each channel.

I have two use cases I'm considering:

1. Using a multi-channel driver to drive separate channels to different breathing patterns.
2. Using a 3-channel driver to pulse a single RGB LED in a single pattern with a given colour.

Both can be accomplished by passing in a struct for each channel, and moving the concept of 'colour' up to the application API level, or by having some method of initializing e.g. a 3-channel driver as either three individual channels or a single-channel RGB LED that responds to led_color().

[simonguinot]

@soburi @bbilas @mbolivar @Mani-Sadhasivam @kartben