Package frc.spectrumLib.leds

Class SpectrumLEDs

java.lang.Object
frc.spectrumLib.leds.SpectrumLEDs
All Implemented Interfaces:
Subsystem
Direct Known Subclasses:
Leds
public class SpectrumLEDs extends Object implements Subsystem
CANdle-based addressable LED subsystem that wraps a CTRE CANdle and exposes a rich library of pattern factories (solid, stripe, blink, breathe, rainbow, chase, bounce, gradient, ombre, wave, countdown, etc.).

Patterns are split into two categories:

Multiple SpectrumLEDs instances can share a single physical CANdle device by passing the same CANdle reference in their SpectrumLEDs.Config objects and selecting non-overlapping startIdx/numLeds ranges.

Patterns are applied via setPattern(CANdlePattern, int), which returns a Command that runs continuously and respects the priority system (checkPriority(int)).

  • Field Details

    • candle

      protected final CANdle candle
      The CANdle device (owned or shared).

    • defaultPattern

      protected final SpectrumLEDs.CANdlePattern defaultPattern
      Default pattern shown when no other command requires this subsystem (orange blink).

      Initialized in the constructor body (after config is set) so that pattern factories can safely reference the config.

    • defaultCommand

      protected final Command defaultCommand
      The default command built by this class (displays defaultPattern at lowest priority). Installed via setDefaultCommand in the constructor; subclasses may install their own default command to replace it. Use getDefaultCommand() (from Subsystem) to query whichever default is currently installed.

    • defaultTrigger

      public final Trigger defaultTrigger
      Trigger that is active while the currently installed default command (whichever one that is) is the one running — i.e. no higher-priority pattern owns the subsystem.

    • purple

      public final Color purple
      Spectrum purple color constant (RGB 130, 103, 185).

    • white

      public final Color white
      Convenience alias for Color.kWhite.

  • Constructor Details

    • SpectrumLEDs

      public SpectrumLEDs(SpectrumLEDs.Config config)
      Constructs the LED subsystem, configures the hardware (or reuses a shared device), and registers with the WPILib CommandScheduler.
      Parameters:
      config - the configuration describing the device, segment range, and strip type

  • Method Details

    • isAttached

      public boolean isAttached()
      Returns whether this LED strip is physically connected to the robot.
      Returns:
      true if attached

    • isAnimating

      public boolean isAnimating()
      Returns true if the most recently applied pattern was a CANdle hardware animation running in firmware, false if it was a software SolidColor pattern.

    • getCurrentCommandName

      public String getCurrentCommandName()
      Returns the currently running command that is applying a pattern to this subsystem, or null if no command is currently running.
      Returns:
      the currently running command, or null if none

    • checkPriority

      public Trigger checkPriority(int priority)
      Returns a Trigger that is active when the currently running command's priority is at or below the given value. Use to gate lower-priority commands from overriding higher-priority ones.
      Parameters:
      priority - the maximum priority level that allows the trigger to be active
      Returns:
      trigger active when commandPriority ≤ priority

    • setPattern

      public Command setPattern(SpectrumLEDs.CANdlePattern pattern, int priority)
      Returns a command that continuously applies pattern to the LED segment and records the given priority while running. The command runs while the robot is disabled.

      When switching from a hardware animation to a software (SolidColor) pattern, all active animation slots are cleared automatically before the first software write.

      Parameters:
      pattern - the SpectrumLEDs.CANdlePattern to apply each loop cycle
      priority - priority level stored in commandPriority while this command runs
      Returns:
      a command that applies the pattern continuously

    • setPattern

      public Command setPattern(SpectrumLEDs.CANdlePattern pattern)
      Returns a command that continuously applies pattern to the LED segment at priority 0.
      Parameters:
      pattern - the SpectrumLEDs.CANdlePattern to apply
      Returns:
      a command that applies the pattern continuously at the default priority

    • blink

      public SpectrumLEDs.CANdlePattern blink(Color color, double onTimeSecs)
      Blinking (strobe) pattern — alternates between color and off. Each half-cycle (on and off) lasts onTimeSecs seconds.

      Implemented using StrobeAnimation. Frame rate = 1 / onTimeSecs Hz.

      Parameters:
      color - the blink color
      onTimeSecs - duration in seconds of each on (and off) half-cycle
      Returns:
      a hardware animation SpectrumLEDs.CANdlePattern

    • breathe

      public SpectrumLEDs.CANdlePattern breathe(Color color, double periodSecs)
      Breathing (sinusoidal fade-in/out) pattern — fades between the peak color and off.

      Implemented using SingleFadeAnimation. Each animation frame changes brightness by 1%, so frame rate = 200 / periodSecs Hz for a complete 0→100→0% cycle.

      Parameters:
      color - the peak color at full brightness
      periodSecs - duration in seconds of one full breathe cycle
      Returns:
      a hardware animation SpectrumLEDs.CANdlePattern

    • rainbow

      public SpectrumLEDs.CANdlePattern rainbow()
      Static rainbow — hue distributed evenly across the strip, advancing very slowly.
      Returns:
      a hardware animation SpectrumLEDs.CANdlePattern

    • rainbow

      public SpectrumLEDs.CANdlePattern rainbow(double brightness)
      Static rainbow with configurable brightness.
      Parameters:
      brightness - brightness scalar (0.0–1.0)
      Returns:
      a hardware animation SpectrumLEDs.CANdlePattern

    • scrollingRainbow

      public SpectrumLEDs.CANdlePattern scrollingRainbow()
      Scrolling rainbow that advances quickly across the strip.
      Returns:
      a hardware animation SpectrumLEDs.CANdlePattern

    • chase

      public SpectrumLEDs.CANdlePattern chase(Color color, double speed)
      Chase / color-flow pattern — progressively lights LEDs one at a time across the strip and repeats.

      Implemented using ColorFlowAnimation. Frame rate = numLeds × speed Hz so that speed full cycles occur per second.

      Parameters:
      color - the chase color
      speed - desired number of full strip cycles per second
      Returns:
      a hardware animation SpectrumLEDs.CANdlePattern

    • bounce

      public SpectrumLEDs.CANdlePattern bounce(Color color, double durationSecs)
      Bouncing dot pattern — a pocket of light travels back and forth across the strip.

      Implemented using LarsonAnimation with LarsonBounceValue.Back. Frame rate is computed so one back-and-forth cycle takes durationSecs seconds.

      Parameters:
      color - the dot color
      durationSecs - seconds per complete back-and-forth cycle
      Returns:
      a hardware animation SpectrumLEDs.CANdlePattern

    • fire

      public SpectrumLEDs.CANdlePattern fire()
      Fire animation using the CANdle's built-in hardware animation engine.
      Returns:
      a hardware animation SpectrumLEDs.CANdlePattern

    • rgbCycle

      public SpectrumLEDs.CANdlePattern rgbCycle()
      RGB color-cycle animation using the CANdle's built-in hardware animation engine.
      Returns:
      a hardware animation SpectrumLEDs.CANdlePattern

    • solid

      public SpectrumLEDs.CANdlePattern solid(Color color)
      Solid color pattern.

      Uses a single SolidColor control request (one-shot, resent each loop).

      Parameters:
      color - the color to display
      Returns:
      a software SpectrumLEDs.CANdlePattern showing a constant solid color

    • stripe

      public SpectrumLEDs.CANdlePattern stripe(double percent, Color color1, Color color2)
      Two-color stripe: the first percent fraction of LEDs shows color1, the remainder shows color2.

      Uses two SolidColor controls (one-shot each, resent each loop).

      Parameters:
      percent - fraction of the strip (0.0–1.0) assigned to color1
      color1 - color for the leading segment
      color2 - color for the trailing segment
      Returns:
      a software SpectrumLEDs.CANdlePattern showing the two-color stripe

    • gradient

      public SpectrumLEDs.CANdlePattern gradient(Color color1, Color color2)
      Linear gradient between two colors across the strip. Colors are pre-computed at first use.

      Uses N SolidColor controls (one per LED, one-shot, resent each loop).

      Parameters:
      color1 - color at the start (index 0) of the segment
      color2 - color at the end of the segment
      Returns:
      a software SpectrumLEDs.CANdlePattern showing the two-color gradient

    • edges

      public SpectrumLEDs.CANdlePattern edges(Color color, int length)
      Edge-highlight pattern — lights the first and last length LEDs with color and turns off the center LEDs.

      Uses two or three SolidColor controls (one-shot, resent each loop).

      Parameters:
      color - the color to apply to the edge LEDs
      length - the number of LEDs to illuminate at each end of the strip
      Returns:
      a software SpectrumLEDs.CANdlePattern showing lit edges and a dark center

    • ombre

      public SpectrumLEDs.CANdlePattern ombre(Color startColor, Color endColor)
      Animated ombre — transitions smoothly between two colors across the strip and scrolls the blend point over time.

      Uses N SolidColor controls (one per LED, one-shot, resent each loop with updated colors). RGBWColor objects are created each loop since the type is immutable.

      Parameters:
      startColor - the leading color
      endColor - the trailing color
      Returns:
      a software SpectrumLEDs.CANdlePattern showing the animated ombre

    • wave

      public SpectrumLEDs.CANdlePattern wave(Color c1, Color c2, double cycleLength, double durationSecs)
      Sinusoidal wave pattern blending between two colors.

      Uses N SolidColor controls (one per LED, one-shot, resent each loop).

      Parameters:
      c1 - first wave color
      c2 - second wave color
      cycleLength - number of LEDs per wave period
      durationSecs - period of the time-based animation in seconds
      Returns:
      a software SpectrumLEDs.CANdlePattern showing the wave

    • countdown

      public SpectrumLEDs.CANdlePattern countdown(DoubleSupplier countStartTimeSec, double durationInSeconds)
      Countdown pattern — LEDs transition from yellow to red and progressively turn off from the end of the segment toward the beginning as time elapses.

      Uses N SolidColor controls (one per LED, one-shot, resent each loop).

      Parameters:
      countStartTimeSec - supplies the FPGA timestamp (seconds) when the countdown began
      durationInSeconds - total countdown duration in seconds
      Returns:
      a software SpectrumLEDs.CANdlePattern showing the countdown

    • switchCountdown

      public SpectrumLEDs.CANdlePattern switchCountdown(Color startingColor)
      Alliance switch countdown — cycles through alliance colors (and purple) on a hard-coded match-time schedule, progressively turning off LEDs within each segment as time elapses.

      Segment schedule (seconds remaining → color): 

        140–130  purple
  130–105  startingColor
  105–80   opponent color
   80–55   startingColor
   55–30   opponent color
   30–0    purple

      Uses N SolidColor controls (one per LED, one-shot, resent each loop).

      Parameters:
      startingColor - the alliance color displayed during this robot's segments
      Returns:
      a software SpectrumLEDs.CANdlePattern reflecting the current switch-countdown state

    • getConfig

      public SpectrumLEDs.Config getConfig()
      Active configuration for this instance.

    • getCandle

      public CANdle getCandle()
      The CANdle device (owned or shared).

    • getCommandPriority

      public int getCommandPriority()
      Priority level of the pattern command currently running. Higher values indicate higher priority; setPattern(CANdlePattern, int) stores this while a command runs and resets it to -1 when the command ends.

    • setCommandPriority

      public void setCommandPriority(int commandPriority)
      Priority level of the pattern command currently running. Higher values indicate higher priority; setPattern(CANdlePattern, int) stores this while a command runs and resets it to -1 when the command ends.