Skip to content

RaftCoreLEDPixels

Jump to bottom
Rob Dobson edited this page Mar 5, 2026 · 2 revisions

Raft Core LEDPixels

The LEDPixels module is responsible for managing and controlling LED strips and segments (arbitrary groupings of LEDs). It handles the setup, management of LED patterns, and updates to LED states. The module also includes functionality for starting/stopping patterns, showing pixels, and handling per-pixel settings.

The LEDPixelsDevice class is the device wrapper that exposes LED control through the REST-style API and ties JSON configuration into LEDPixels.

Features

  • LED Strip Management: Supports multiple LED strips with individual drivers.
  • Segmented Control: Allows for dividing the pixel array into logical segments.
  • Pattern Support: Allows custom patterns to be applied to the LEDs.
  • Callbacks: Pre and post-show callbacks for additional control during pixel updates.
  • Device API: REST-style LED control via LEDPixelsDevice.

Configuration

Configuration is generally done via JSON although a LEDPixelConfig object can also be constructed directly and setup in this way. For JSON configuration see LEDPixels JSON Configuration

Constructor and Destructor

LEDPixels::LEDPixels()

The constructor initializes the LEDPixels object.

LEDPixels::~LEDPixels()

The destructor is responsible for cleaning up resources used by the LEDPixels object.

Setup

bool setup(const RaftJsonIF& config)

This setup function configures the LED pixels based on a provided configuration in JSON format. It initializes the number of pixels, the LED strip drivers, and the segments.

Parameters:

  • config: The configuration object (RaftJsonIF) that contains the settings for the LED pixel setup.

Returns:

  • bool: Returns true if the setup was successful, false otherwise.

bool setup(LEDPixelConfig& config)

An alternative setup method that directly accepts a LEDPixelConfig object. It initializes the pixel array, LED strip drivers, and LED segments.

Parameters:

  • config: A configuration object containing the LED pixel settings (LEDPixelConfig).

Returns:

  • bool: Returns true if the setup was successful, false otherwise.

Main Loop

void loop()

The main loop function that updates the LED strips and segments. It processes each segment, updating patterns and handling stop requests.

LEDPixelsDevice API

LEDPixelsDevice registers a REST endpoint named led. Requests are transport-agnostic and can arrive via HTTP, serial, BLE, etc.

Endpoint format:

led/<elem>/<cmd>/<data>?<args>

Where <elem> is a segment name or index (e.g., ring, 0).

Supported commands:

  • setall / color / colour: Set all LEDs in the segment to a single color. Accepts RRGGBB or RRGGBBCCWW.
  • setleds: Set multiple LEDs from a concatenated color string (stride 6 or 10).
  • setled / set: Set a single LED by index and color.
  • off: Stop pattern and blank the segment.
  • pattern: Start a named pattern with optional query args (e.g., speed, brightness, forMs).
  • listpatterns: Return available pattern names.

Examples:

led/ring/setall/FF0000
led/ring/set/0/00FF00
led/ring/pattern/RainbowSnake?speed=1000&brightness=50
led/ring/listpatterns

Adding Patterns

void addPattern(const String& patternName, LEDPatternCreateFn createFn)

This function adds a custom pattern to the LED system. If a pattern with the same name exists, it replaces the old pattern with the new one.

Parameters:

  • patternName: The name of the new pattern to add.
  • createFn: The function that creates the pattern (LEDPatternCreateFn).

Retrieving Pattern Names

void getPatternNames(std::vector<String>& patternNames) const

This function retrieves the names of all available patterns.

Parameters:

  • patternNames: A vector to store the names of all available patterns.

Segments

int32_t getSegmentIdx(const String& segmentName) const

Retrieves the index of a segment by its name.

Parameters:

  • segmentName: The name of the segment to find.

Returns:

  • int32_t: The index of the segment, or -1 if the segment is not found.

Pixel Control

bool show()

Updates the LEDs by sending the current pixel values to the hardware drivers. It also triggers pre and post-show callbacks if defined.

Returns:

  • bool: Always returns true after showing the pixels.

void waitUntilShowComplete()

Waits until the hardware drivers finish updating the LEDs.

void clear(bool showAfterClear)

Clears all pixels by setting their color values to zero. Optionally, it can call show() after clearing.

Parameters:

  • showAfterClear: If true, the show() function is called after clearing the pixels.

Debugging

Several compile-time debug options are available to log pixel and segment data:

  • DEBUG_LED_PIXEL_VALUES: Logs the color values of each pixel during the show() process.
  • DEBUG_LED_PIXELS_LOOP_SHOW: Logs information about segment updates and stop requests during the loop() process.

Clone this wiki locally