Light-Emitting Diode (LED)

Overview

The LED API provides access to Light Emitting Diodes, both in individual and strip form.

Configuration Options

Related configuration options:

API Reference

LED

group led_interface

LED Interface.

Since

1.12

Version

1.0.0

Typedefs

Callback API for blinking an LED.

See also

led_blink() for argument descriptions.

typedef int (*led_api_get_info)(const struct device *dev, uint32_t led, const struct led_info **info)

Optional API callback to get LED information.

See also

led_get_info() for argument descriptions.

typedef int (*led_api_set_brightness)(const struct device *dev, uint32_t led, uint8_t value)

Callback API for setting brightness of an LED.

See also

led_set_brightness() for argument descriptions.

typedef int (*led_api_set_color)(const struct device *dev, uint32_t led, uint8_t num_colors, const uint8_t *color)

Optional API callback to set the colors of a LED.

See also

led_set_color() for argument descriptions.

typedef int (*led_api_on)(const struct device *dev, uint32_t led)

Callback API for turning on an LED.

See also

led_on() for argument descriptions.

typedef int (*led_api_off)(const struct device *dev, uint32_t led)

Callback API for turning off an LED.

See also

led_off() for argument descriptions.

typedef int (*led_api_write_channels)(const struct device *dev, uint32_t start_channel, uint32_t num_channels, const uint8_t *buf)

Callback API for writing a strip of LED channels.

See also

led_api_write_channels() for arguments descriptions.

Functions

Blink an LED.

This optional routine starts blinking a LED forever with the given time period.

Parameters:
  • dev – LED device

  • led – LED number

  • delay_on – Time period (in milliseconds) an LED should be ON

  • delay_off – Time period (in milliseconds) an LED should be OFF

Returns:

0 on success, negative on error

int led_get_info(const struct device *dev, uint32_t led, const struct led_info **info)

Get LED information.

This optional routine provides information about a LED.

Parameters:
  • dev – LED device

  • led – LED number

  • info – Pointer to a pointer filled with LED information

Returns:

0 on success, negative on error

int led_set_brightness(const struct device *dev, uint32_t led, uint8_t value)

Set LED brightness.

This optional routine sets the brightness of a LED to the given value. Calling this function after led_blink() won’t affect blinking.

LEDs which can only be turned on or off may provide this function. These should simply turn the LED on if value is nonzero, and off if value is zero.

Parameters:
  • dev – LED device

  • led – LED number

  • value – Brightness value to set in percent

Returns:

0 on success, negative on error

int led_write_channels(const struct device *dev, uint32_t start_channel, uint32_t num_channels, const uint8_t *buf)

Write/update a strip of LED channels.

This optional routine writes a strip of LED channels to the given array of levels. Therefore it can be used to configure several LEDs at the same time.

Calling this function after led_blink() won’t affect blinking.

Parameters:
  • dev – LED device

  • start_channel – Absolute number (i.e. not relative to a LED) of the first channel to update.

  • num_channels – The number of channels to write/update.

  • buf – array of values to configure the channels with. num_channels entries must be provided.

Returns:

0 on success, negative on error

int led_set_channel(const struct device *dev, uint32_t channel, uint8_t value)

Set a single LED channel.

This optional routine sets a single LED channel to the given value.

Calling this function after led_blink() won’t affect blinking.

Parameters:
  • dev – LED device

  • channel – Absolute channel number (i.e. not relative to a LED)

  • value – Value to configure the channel with

Returns:

0 on success, negative on error

int led_set_color(const struct device *dev, uint32_t led, uint8_t num_colors, const uint8_t *color)

Set LED color.

This routine configures all the color channels of a LED with the given color array.

Calling this function after led_blink() won’t affect blinking.

Parameters:
  • dev – LED device

  • led – LED number

  • num_colors – Number of colors in the array.

  • color – Array of colors. It must be ordered following the color mapping of the LED controller. See the the color_mapping member in struct led_info.

Returns:

0 on success, negative on error

int led_on(const struct device *dev, uint32_t led)

Turn on an LED.

This routine turns on an LED

Parameters:
  • dev – LED device

  • led – LED number

Returns:

0 on success, negative on error

int led_off(const struct device *dev, uint32_t led)

Turn off an LED.

This routine turns off an LED

Parameters:
  • dev – LED device

  • led – LED number

Returns:

0 on success, negative on error

struct led_info
#include <led.h>

LED information structure.

This structure gathers useful information about LED controller.

Public Members

const char *label

LED label.

uint32_t index

Index of the LED on the controller.

uint8_t num_colors

Number of colors per LED.

const uint8_t *color_mapping

Mapping of the LED colors.

struct led_driver_api
#include <led.h>

LED driver API.

LED Strip

group led_strip_interface

LED Strip Interface.

Typedefs

typedef int (*led_api_update_rgb)(const struct device *dev, struct led_rgb *pixels, size_t num_pixels)

Callback API for updating an RGB LED strip.

See also

led_strip_update_rgb() for argument descriptions.

typedef int (*led_api_update_channels)(const struct device *dev, uint8_t *channels, size_t num_channels)

Callback API for updating channels without an RGB interpretation.

See also

led_strip_update_channels() for argument descriptions.

typedef size_t (*led_api_length)(const struct device *dev)

Callback API for getting length of an LED strip.

See also

led_strip_length() for argument descriptions.

Functions

static inline int led_strip_update_rgb(const struct device *dev, struct led_rgb *pixels, size_t num_pixels)

Mandatory function to update an LED strip with the given RGB array.

Warning

This routine may overwrite pixels.

Parameters:
  • dev – LED strip device.

  • pixels – Array of pixel data.

  • num_pixels – Length of pixels array.

Return values:
  • 0 – on success.

  • -errno – negative errno code on failure.

static inline int led_strip_update_channels(const struct device *dev, uint8_t *channels, size_t num_channels)

Optional function to update an LED strip with the given channel array (each channel byte corresponding to an individually addressable color channel or LED.

Channels are updated linearly in strip order.

Warning

This routine may overwrite channels.

Parameters:
  • dev – LED strip device.

  • channels – Array of per-channel data.

  • num_channels – Length of channels array.

Return values:
  • 0 – on success.

  • -ENOSYS – if not implemented.

  • -errno – negative errno code on other failure.

static inline size_t led_strip_length(const struct device *dev)

Mandatory function to get chain length (in pixels) of an LED strip device.

Parameters:
  • dev – LED strip device.

Return values:

Length – of LED strip device.

struct led_rgb
#include <led_strip.h>

Color value for a single RGB LED.

Individual strip drivers may ignore lower-order bits if their resolution in any channel is less than a full byte.

Public Members

uint8_t r

Red channel.

uint8_t g

Green channel.

uint8_t b

Blue channel.

struct led_strip_driver_api
#include <led_strip.h>

LED strip driver API.

This is the mandatory API any LED strip driver needs to expose.