DELs adressables

LED strips have been commonly used by teams for several years for a variety of reasons. They allow teams to debug robot functionality from the audience, provide a visual marker for their robot, and can simply add some visual appeal. WPILib has an API for controlling WS2812, WS2812B, and WS2815 LEDs with their data pin connected via PWM.

Note

LEDs can be controlled through this API while the robot is disabled.

Instanciation de l’objet adressableLED

You first create an AddressableLED object that takes the PWM port as an argument. It must be a PWM header on the roboRIO. Then you set the number of LEDs located on your LED strip, which can be done with the setLength() function.

Avertissement

Il est important de noter que le réglage de la longueur décrit ci-haut est une tâche relativement longue à exécuter pour le roboRIO, et il n’est pas recommandé de l’exécuter périodiquement.

Une fois la longueur de la bande définie, vous devrez créer un objet AddressableLEDBuffer qui prendra le nombre de LED comme entrée. Vous appellerez ensuite myAddressableLed.setData(myAddressableLEDBuffer) pour définir les données correspondant à chaque LED. Enfin, vous pouvez appeler myAddressableLed.start() pour écrire la sortie en continu. Voici un exemple complet du processus d’initialisation.

Note

C++ ne supporte pas un AddressableLEDBuffer et utilise à la place un tableau.

Java

  /** Called once at the beginning of the robot program. */
  public Robot() {
    // PWM port 9
    // Must be a PWM header, not MXP or DIO
    m_led = new AddressableLED(9);

    // Reuse buffer
    // Default to a length of 60, start empty output
    // Length is expensive to set, so only set it once, then just update data
    m_ledBuffer = new AddressableLEDBuffer(60);
    m_led.setLength(m_ledBuffer.getLength());

    // Set the data
    m_led.setData(m_ledBuffer);
    m_led.start();
  }

C++

 private:
  static constexpr int kLength = 60;

  // PWM port 9
  // Must be a PWM header, not MXP or DIO
  frc::AddressableLED m_led{9};
  std::array<frc::AddressableLED::LEDData, kLength>
      m_ledBuffer;  // Reuse the buffer

  // Our LED strip has a density of 120 LEDs per meter

Robot::Robot() {
  // Default to a length of 60, start empty output
  // Length is expensive to set, so only set it once, then just update data
  m_led.SetLength(kLength);
  m_led.SetData(m_ledBuffer);
  m_led.Start();
}

Controlling Sections of an LED Strip

The roboRIO can only control a single addressable LED output at a time, but there are often multiple physical LED strips daisy-chained around a robot, or a single flexible LED strip wrapped around structures on a robot. Individual sections can be accessed in Java using AddressableLEDBufferView. Buffer views behave like subsections of the larger buffer, and can be accessed using indices in the typical [0, length) range. They can also be reversed, to allow for parallel serpentine sections to be animated in the same physical orientation (i.e. both sections would animate « forward » in the same direction, even if the strips are physically tip-to-tail).

Java

// Create the buffer
AddressableLEDBuffer m_buffer = new AddressableLEDBuffer(120);

// Create the view for the section of the strip on the left side of the robot.
// This section spans LEDs from index 0 through index 59, inclusive.
AddressableLEDBufferView m_left = m_buffer.createView(0, 59);

// The section of the strip on the right side of the robot.
// This section spans LEDs from index 60 through index 119, inclusive.
// This view is reversed to cancel out the serpentine arrangement of the
// physical LED strip on the robot.
AddressableLEDBufferView m_right = m_buffer.createView(60, 119).reversed();

C++

// Create the buffer
std::array<frc::AddressableLED::LEDData, 120> m_buffer;

// Create the view for the section of the strip on the left side of the robot.
// This section spans LEDs from index 0 through index 59, inclusive.
std::view<frc::AddressableLED::LEDData> m_left =
   std::ranges::take_view(m_buffer, 60);

// The section of the strip on the right side of the robot.
// This section spans LEDs from index 60 through index 119, inclusive.
// This view is reversed to cancel out the serpentine arrangement of the
// physical LED strip on the robot.
std::view<frc::AddressableLED::LEDData> m_right =
   std::ranges::reverse_view(
      std::ranges::drop_view(m_buffer, 60));

LED Patterns

The LEDPattern API simplifies setting LED data. Rather than needing to manually loop over every LED index, you can apply a pattern object to the data buffer directly. LED patterns are stateless, and can safely be applied to multiple buffers or views.

Java

// Create an LED pattern that sets the entire strip to solid red
LEDPattern red = LEDPattern.solid(Color.kRed);

// Apply the LED pattern to the data buffer
red.applyTo(m_ledBuffer);

// Write the data to the LED strip
m_led.setData(m_ledBuffer);

C++

// Create an LED pattern that sets the entire strip to solid red
LEDPattern red = LEDPattern.Solid(Color::kRed);

// Apply the LED pattern to the data buffer
red.ApplyTo(m_ledBuffer);

// Write the data to the LED strip
m_led.SetData(m_ledBuffer);

Création d’un effet arc-en-ciel

Using the built in LEDPattern.rainbow method, we can create a pattern that displays a full rainbow across an entire LED strip. Then, by calling scrollAtAbsoluteSpeed we can make it animate and cycle around the strip. rainbow accepts two arguments - one for the saturation and one for the value, expressed as a number from 0 to 255.

Note

Animating effects like scrolling use the Java units library and the C++ units library for speeds and durations.

The base rainbow pattern will look like this:

Java

  // all hues at maximum saturation and half brightness
  private final LEDPattern m_rainbow = LEDPattern.rainbow(255, 128);

  // Our LED strip has a density of 120 LEDs per meter
  private static final Distance kLedSpacing = Meters.of(1 / 120.0);

  // Create a new pattern that scrolls the rainbow pattern across the LED strip, moving at a speed
  // of 1 meter per second.
  private final LEDPattern m_scrollingRainbow =
      m_rainbow.scrollAtAbsoluteSpeed(MetersPerSecond.of(1), kLedSpacing);

C++

  // Our LED strip has a density of 120 LEDs per meter
  units::meter_t kLedSpacing{1 / 120.0};

  // Create an LED pattern that will display a rainbow across
  // all hues at maximum saturation and half brightness
  frc::LEDPattern m_rainbow = frc::LEDPattern::Rainbow(255, 128);

  // Create a new pattern that scrolls the rainbow pattern across the LED
  // strip, moving at a speed of 1 meter per second.
  frc::LEDPattern m_scrollingRainbow =
      m_rainbow.ScrollAtAbsoluteSpeed(1_mps, kLedSpacing);

Now that the rainbow pattern is defined, we only need to apply it.

Java

  public void robotPeriodic() {
    // Update the buffer with the rainbow animation
    m_scrollingRainbow.applyTo(m_ledBuffer);
    // Set the LEDs
    m_led.setData(m_ledBuffer);
  }
}

C++

void Robot::RobotPeriodic() {
  // Run the rainbow pattern and apply it to the buffer
  m_scrollingRainbow.ApplyTo(m_ledBuffer);
  // Set the LEDs
  m_led.SetData(m_ledBuffer);
}

Controlling when patterns are applied

Use commands. The command framework is specifically built for managing when actions run and stop, and prevents multiple actions from running simultaneously.

Java

public class LEDSubsystem extends SubsystemBase {
  private static final int kPort = 9;
  private static final int kLength = 120;

  private final AddressableLED m_led;
  private final AddressableLEDBuffer m_buffer;

  public LEDSubsystem() {
    m_led = new AddressableLED(kPort);
    m_buffer = new AddressableLEDBuffer(kLength);
    m_led.setLength(kLength);
    m_led.start();

    // Set the default command to turn the strip off, otherwise the last colors written by
    // the last command to run will continue to be displayed.
    // Note: Other default patterns could be used instead!
    setDefaultCommand(runPattern(LEDPattern.solid(Color.kBlack)).withName("Off"));
  }

  @Override
  public void periodic() {
    // Periodically send the latest LED color data to the LED strip for it to display
    m_led.setData(m_buffer);
  }

  /**
   * Creates a command that runs a pattern on the entire LED strip.
   *
   * @param pattern the LED pattern to run
   */
  public Command runPattern(LEDPattern pattern) {
    return run(() -> pattern.apply(m_buffer));
  }
}

C++

Header:

class LEDSubsystem : public SubsystemBase {
 public:
  LEDSubsystem();
  void Periodic() override;

  frc::CommandPtr RunPattern(frc::LEDPattern pattern);

 private:
  static constexpr int kPort = 9;
  static constexpr int kLength = 120;
  frc::AddressableLED m_led{kPort};
  std::array<frc::AddressableLED::LEDData, kLength> m_ledBuffer;
}

LEDSubsystem::LEDSubsystem() {
  m_led.SetLength(kLength);
  m_led.Start();

  // Set the default command to turn the strip off, otherwise the last colors written by
  // the last command to run will continue to be displayed.
  // Note: Other default patterns could be used instead!
  SetDefaultCommand(RunPattern(frc::LEDPattern::Solid(frc::Color::kBlack)).WithName("Off"));
}

LEDSubsystem::Periodic() {
  // Periodically send the latest LED color data to the LED strip for it to display
  m_led.SetData(m_ledBuffer);
}

frc::CommandPtr LEDSubsystem::RunPattern(frc::LEDPattern pattern) {
  // std::move is necessary for inline pattern declarations to work
  // Otherwise we could have a use-after-free!
  return Run([this, pattern = std::move(pattern)] { pattern.ApplyTo(m_buffer); });
}

Combinatory effects

Complex LED patterns are built up from combining simple base patterns (such as solid colors or gradients) with animating effects (such as scrolling or breathing) and combinatory effects (like masks and overlays). Multiple effects can be combined at once, like in the scrolling rainbow effect above that takes a basic base effect - a static rainbow - and then adds a scrolling effect to it.

Mask

Masks work by combining the RGB values of two patterns and keeping only the values that are shared by both. The combination works on the individual bits of each color using a bitwise AND operation - for example, if a pixel’s red channel were set to 255 by one pattern (represented as 11111111 in binary), then the output red color would be identical to the red channel of the second pattern. If the first pattern sets it to zero (00000000 in binary), then the output red color would also be zero, regardless of whatever the second pattern sets. For this reason, black (all zeroes) and white (all ones) masks are very useful for selectively enabling and disabling parts of another pattern. Other mask colors can be used as well: masking with solid red would keep only the red channel of the original pattern, while discarding all green and blue values.

Java

// Create an LED pattern that displays a red-to-blue gradient at a variable length
// depending on the relative position of the elevator. The blue end of the gradient
// will only be shown when the elevator gets close to its maximum height; otherwise,
// that end will be solid black when the elevator is at lower heights.
LEDPattern base = LEDPattern.discontinuousGradient(Color.kRed, Color.kBlue);
LEDPattern mask = LEDPattern.progressMaskLayer(() -> m_elevator.getHeight() / m_elevator.getMaxHeight());
LEDPattern heightDisplay = base.mask(mask);

// Apply the LED pattern to the data buffer
heightDisplay.applyTo(m_ledBuffer);

// Write the data to the LED strip
m_led.setData(m_ledBuffer);

C++

// Create an LED pattern that displays a red-to-blue gradient at a variable length
// depending on the relative position of the elevator. The blue end of the gradient
// will only be shown when the elevator gets close to its maximum height; otherwise,
// that end will be solid black when the elevator is at lower heights.
std::array<Color, 2> colors{Color::kRed, Color::kBlue};
LEDPattern base = LEDPattern::DiscontinuousGradient(colors);
LEDPattern mask = LEDPattern::ProgressMaskLayer([&]() { m_elevator.GetHeight() / m_elevator.GetMaxHeight() });
LEDPattern heightDisplay = base.Mask(mask);

// Apply the LED pattern to the data buffer
heightDisplay.ApplyTo(m_ledBuffer);

// Write the data to the LED strip
m_led.SetData(m_ledBuffer);

Masks can also be animated (see progressMask). Masking a base pattern with a scrolling pattern will result in a panning effect. The animation above was generated by masking a rainbow pattern with a scrolling white/black pattern

Java

Map<Double, Color> maskSteps = Map.of(0, Color.kWhite, 0.5, Color.kBlack);
LEDPattern base = LEDPattern.rainbow(255, 255);
LEDPattern mask =
   LEDPattern.steps(maskSteps).scrollAtRelativeSpeed(Percent.per(Second).of(0.25));

LEDPattern pattern = base.mask(mask);

// Apply the LED pattern to the data buffer
pattern.applyTo(m_ledBuffer);

// Write the data to the LED strip
m_led.setData(m_ledBuffer);

C++

std::array<std::pair<double, Color>, 2> maskSteps{std::pair{0.0, Color::kWhite},
                                                  std::pair{0.5, Color::kBlack}};
LEDPattern base = LEDPattern::Rainbow(255, 255);
LEDPattern mask =
   LEDPattern::Steps(maskSteps).ScrollAtRelativeSpeed(units::hertz_t{0.25});

LEDPattern pattern = base.Mask(mask);

// Apply the LED pattern to the data buffer
pattern.ApplyTo(m_ledBuffer);

// Write the data to the LED strip
m_led.SetData(m_ledBuffer);

Overlay

Overlays can be used to « stack » patterns atop each other, where black pixels (set to Color.kBlack, RGB value #000000) are treated as transparent and allow a lower layer to be displayed. Upper layers are typically combined with masks to set transparent sections; recall that masking a pixel with Color.kBlack will set that pixel to black, which will then be treated by the overlay as transparent.

Blend

Blends will combine the output colors of patterns together, by averaging out the individual RGB colors for every pixel. Like the brightness modifier, this tends to output colors that are more desaturated than its inputs.

Low Level Access

LEDPattern is an easy and convenient way of controlling LEDs, but direct access to the LED colors is sometimes needed for custom patterns and animations.

Color can be set to an individual led on the strip using two methods: setRGB(), which takes RGB values as an input, and setHSV(), which takes HSV values as an input. Low-level access is typically done with an indexed for-loop that iterates over each LED index of the section to control. This method can be used for both AddressableLEDBuffer and AddressableLEDBufferView objects in Java, and for std::span for C++.

Note

RGB stands for Red, Green, and Blue. This is a fairly common color model as it’s quite easy to understand, and it corresponds with a typical LED configuration that’s comprised of one red, one green, and one blue sub-LED. LEDs can be set with the setRGB method that takes 4 arguments: index of the LED, amount of red, amount of green, amount of blue. The amount of red, green, and blue are integer values between 0-255.

Note

HSV stands for Hue, Saturation, and Value. Hue describes the color or tint, saturation being the amount of gray, and value being the brightness. In WPILib, Hue is an integer from 0 - 180. Saturation and Value are integers from 0 - 255. If you look at a color picker like Google’s, Hue will be 0 - 360 and Saturation and Value are from 0% to 100%. This is the same way that OpenCV handles HSV colors. Make sure the HSV values entered to WPILib are correct, or the color produced might not be the same as was expected.

These examples demonstrate setting an entire LED strip to solid red using the RGB and HSV methods:

Java (RGB)

for (var i = 0; i < m_ledBuffer.getLength(); i++) {
   // Sets the specified LED to the RGB values for red
   m_ledBuffer.setRGB(i, 255, 0, 0);
}
m_led.setData(m_ledBuffer);

C++ (RGB)

for (int i = 0; i < kLength; i++) {
   m_ledBuffer[i].SetRGB(255, 0, 0);
}
m_led.SetData(m_ledBuffer);

Java (HSV)

for (var i = 0; i < m_ledBuffer.getLength(); i++) {
   // Sets the specified LED to the HSV values for red
   m_ledBuffer.setHSV(i, 0, 100, 100);
}
m_led.setData(m_ledBuffer);

C++ (HSV)

for (int i = 0; i < kLength; i++) {
   m_ledBuffer[i].SetHSV(0, 100, 100);
}
m_led.SetData(m_ledBuffer);

Utilisation des valeurs HSV

DELs adressables

Instanciation de l’objet adressableLED

Controlling Sections of an LED Strip

LED Patterns

Création d’un effet arc-en-ciel

Controlling when patterns are applied

Basic effects

Solid color

Continuous Gradient

Discontinuous Gradient

Steps

Progress mask

Modifying effects

Offset

Reverse

Scroll

Breathe

Blink

Brightness

Combinatory effects

Mask

Overlay

Blend

Low Level Access

Utilisation des valeurs HSV