Add LED pattern API for easily animating addressable LEDs

[SamCarlberg]

Add LEDReader and LEDWriter helper interfaces to facilitate composing simple patterns into more complex ones, e.g. LEDPattern.solid(Color.kBlue).breathe(Seconds.of(0.75)). Pattern composition relies on changing out the write behavior; for example, offsetBy increments the indexes to write to; while blink will switch between playing a base pattern and turning off all the LEDs.

Add a view class for splitting a single large buffer into smaller distinct sections, which is useful for dealing with long chained LED strips mounted on different parts of a robot. Views cannot be written directly to an LED strip (in fact, trying to do so won't even compile)

Adds some utility methods to the Color class for interpolating between two colors, and support color representations with 32-bit integers to avoid object allocations

Examples

Command based subsystem:

class LEDs extends SubsystemBase {
  private final AddressableLED m_led;
  private final AddressableLEDBuffer m_ledData;
  private final AddressableLEDBufferView m_leftSide;
  private final AddressableLEDBufferView m_rightSide;

  public LEDs() {
    m_led = new AddressableLED(9);
    m_led.setLength(120);
    m_ledData = new AddressableLEDBuffer(120);
    m_leftSide = m_ledData.createView(0, 59);
    m_rightSide = m_ledData.createView(60, 119).reversed();
  }

  @Override
  public void periodic() {
    m_led.writeData(m_ledData);
  }

  public Command runAnimation(LEDPattern animation) {
    return run(() -> {
      animation.applyTo(m_leftSide);
      animation.applyTo(m_rightSide);
    });
  }
}

Animated rainbow:

LEDPattern rainbow = LEDPattern.rainbow(255, 255).scrollAtRelativeSpeed(Percent.per(Second).of(50));

Flag:

LEDPattern canada = LEDPattern.steps(Map.of(0, Color.kRed, 1 / 3.0, Color.kWhite, 2 / 3.0, Color.kRed));
LEDPattern canadaScroll = canada.scrollAtRelativeSpeed(Percent.per(Second).of(33));

Playing animations for an alliance color based on driverstation data:

LEDPattern breatheBlue = LEDPattern.solid(Color.kFirstBlue).breathe(Seconds.of(2));
LEDPattern breatheRed = LEDPattern.solid(Color.kFirstRed).breathe(Seconds.of(2));
LEDPattern flashYellow = LEDPattern.solid(Color.kYellow).blink(Seconds.of(0.5));

LEDPattern allianceColor = (read, write) -> {
  LEDPattern alliancePattern;
  if (Driverstation.getAlliance().isPresent()) {
    if (Driverstation.getAlliance.get() == Driverstation.Alliance.Blue) {
      alliancePattern = breatheBlue;
    } else {
      alliancePattern = breatheRed;
    }
  } else {
    alliancePattern = flashYellow;
  }
  alliancePattern.applyTo(read, write);
};

[Starlight220]

This API looks amazing!

What is planned for C++ parity?

[SamCarlberg]

What is planned for C++ parity?

No plans for C++ at the moment. The Java API is something I wrote for my FRC team's use so they could make LED patterns without needing to figure out animations; I figured I would contribute it upstream so it could help other teams. But I'm not a C++ developer, and I won't have time to learn the cpp-isms to write a quality port between mentoring my team and resuming work on robotbuilder2.

[spacey-sooty]

Think you might wanna base this off main 😉

[SamCarlberg]

Ah right, I forgot this PR was targeting the development branch

[KangarooKoala]

Overall, looks pretty good! A few doc comments are missing / incomplete, though: ApplyTo(std::span<>, LEDWriterFn) is missing @param, ApplyTo(std::span<>) is missing the entire doc comment, and ScrollAtRelativeSpeed() is missing @param and @return.
Unfortunately, I haven't been able to spend enough time to completely review the logic, but nothing jumps out as wrong. I will say that it would be nice to be able to configure the starting time so that you could guarantee that patterns like the scroll will start in a predictable state at the start of a command regardless of when the command is started, but that could be added later.

[PeterJohnson]

The C++ implementations need lifetime fixes. Since the LEDPattern is a value type, it's unsafe to capture references to it. Similarly std::span is a reference type that needs to be copied into a std::vector when captured.

[PeterJohnson]

It appears the floormod/floordiv change broke tests?

[calcmogul]

Since FloorDiv() and FloorMod() have no unit tests, we should probably add some. As for the bug, my guess is the xor sign check gives the wrong answer if the integers are mismatched sizes. We can either constrain the parameters and return type to be the same integral type, whichever it is, or we could make the sign check more robust.