hitlib::LedGroup Class Reference

Owns a set of LedStrand pointers and fans all animation commands out to each strand simultaneously. More...

#include <led_group.hpp>

Public Member Functions
Setup
void	add (LedStrand *strand)
	Register a strand with this group.
void	init (uint32_t refreshMs=20)
	Initialize hardware on all registered strands.
void	start ()
	Start the group refresh task.
Base Animations
Fan-out wrappers, each call is forwarded to every strand in the group.
void	off ()
	Turn all LEDs off (set to black).
void	setColor (uint32_t color)
	Set all LEDs to a solid color.
void	pulse (uint32_t color, uint8_t runLength, uint8_t speed, uint32_t bgColor=0x000000, bool invert=false, bool bounce=false)
	Animate a run of color moving across a background.
void	flash (uint32_t color, uint32_t onMs, uint32_t offMs, uint32_t bgColor=0x000000)
	Blink the whole strip on and off.
void	flow (uint32_t color1, uint32_t color2, uint8_t speed, bool invert=false, bool seamless=true)
	Scroll a two-color gradient across the strip.
void	rainbow (uint8_t speed)
	Scroll a full HSV rainbow across the strip.
void	twinkle (const std::vector< uint32_t > &colors, uint8_t densityPct=30, uint8_t fadeStep=16, uint32_t bgColor=0x000000)
	Spawn randomly fading sparkles from a color palette.
void	bitscroll (const std::vector< LedStrand::BitScrollSegment > &segments, uint8_t speed, bool invert=false, uint32_t bgColor=0x000000, bool bounce=false, uint8_t spacing=5, bool repeating=true)
	Scroll a pattern of colored segments across the strip.
void	levelFill (uint32_t color, uint32_t color2=0x000000, bool gradient=false, uint32_t bgColor=0x000000, bool invert=false)
	Configure the strip as a level meter, and take manual control of it.
void	setLevel (uint8_t level)
	Set how full the meter is.
void	levelSource (LedStrand::LevelFn read, double emptyAt, double fullAt, bool wrap=false, uint8_t smoothing=0)
	Point the meter at a live value and let it follow it on its own.
void	clearLevelSource ()
	Stop following a levelSource() reader, leaving the fill where it is.
void	musicSync (const LedStrand::MusicTrack &track, uint32_t color, uint32_t color2=0x000000, bool gradient=false, uint32_t bgColor=0x000000, bool invert=false, uint8_t sensitivity=100, bool loop=false)
	Fill the meter from a baked music envelope, and start playing it.
void	musicSeek (uint32_t positionMs)
	Jump playback to a position in the song.
void	musicPause (bool paused=true)
	Pause or resume playback, holding the meter where it is.
void	setSensitivity (uint8_t pct)
	Change the gain applied to envelope samples without restarting.
void	spliceMask (uint8_t sections, bool invert=false, bool alternating=false, uint32_t altPeriodMs=100, uint32_t bgColor=0x000000, bool useOverlay=false)
	Apply a splice mask that overrides alternating equal-width bins.
void	spliceMaskCustom (const std::vector< LedStrand::SpliceRegion > &regions)
	Apply a splice mask made of independently placed/sized regions, each running its own animation.
void	clearSpliceMask ()
	Remove the active splice mask, whichever kind is active.
void	setBrightness (uint8_t pct)
	Set global brightness for this strand.
Overlay Animations
void	overlaySetColor (uint32_t color)
	Set the overlay buffer to a solid color.
void	overlayPulse (uint32_t color, uint8_t runLength, uint8_t speed, uint32_t bgColor=0x000000)
	Animate a moving run in the overlay buffer.
void	overlayFlash (uint32_t color, uint32_t onMs, uint32_t offMs, uint32_t bgColor=0x000000)
	Blink the overlay buffer on and off (see flash()).
void	overlayFlow (uint32_t color1, uint32_t color2, uint8_t speed, bool seamless=true)
	Scroll a gradient in the overlay buffer.
void	overlayRainbow (uint8_t speed)
	Scroll a rainbow in the overlay buffer.
Profile System
void	attachProfile (const Profile *profile)
	Attach a Profile and reset the mode stack.
void	detachProfile ()
	Detach the active profile and turn the strand off.
void	activateMode (uint8_t modeIdx)
	Push a persistent mode onto the mode stack.
void	activateModeTimed (uint8_t modeIdx, uint32_t durationMs)
	Push a timed mode onto the mode stack.
void	deactivateMode (uint8_t modeIdx)
	Remove a mode from the stack immediately.
Direct Access
LedStrand *	operator[] (size_t i)
	Access an individual strand by index.
size_t	size () const
	Return the number of strands in this group.

Detailed Description

Owns a set of LedStrand pointers and fans all animation commands out to each strand simultaneously.

LedGroup starts a single PROS task that calls LedStrand::tick() on every strand it owns at the configured refresh interval. Multiple independent groups are fully supported, each runs its own task with no shared state.

Setup

hitlib::LedStrand strand1(6, 63);
hitlib::LedStrand strand2(7, 63);
hitlib::LedGroup  group;
 
void initialize() {
    group.add(&strand1);
    group.add(&strand2);
    group.init();    // initializes hardware on all strands
    group.start();   // starts the refresh task
}

See also

LedStrand

Member Function Documentation

add()

void hitlib::LedGroup::add

(

LedStrand *

strand

)

Register a strand with this group.

Must be called before init().

Parameters

strand

Pointer to a LedStrand. The strand is not owned by the group, it must outlive the group.

init()

void hitlib::LedGroup::init

(

uint32_t

refreshMs = 20

)

Initialize hardware on all registered strands.

Calls LedStrand::init() on each strand. Safe to call from PROS initialize().

Parameters

refreshMs

Refresh interval passed to the group task in milliseconds (default 20 ms = 50 Hz). Pass 0 to use each strand's own configured interval.

start()

void hitlib::LedGroup::start

(

)

Start the group refresh task.

Call after init(). The task calls tick() on every strand each cycle.

off()

void hitlib::LedGroup::off

(

)

Turn all LEDs off (set to black).

setColor()

void hitlib::LedGroup::setColor

(

uint32_t

color

)

Set all LEDs to a solid color.

Parameters

color

24-bit RGB color (0xRRGGBB).

pulse()

void hitlib::LedGroup::pulse	(	uint32_t	color,
		uint8_t	runLength,
		uint8_t	speed,
		uint32_t	bgColor = 0x000000,
		bool	invert = false,
		bool	bounce = false )

Animate a run of color moving across a background.

Parameters

color	Foreground color (0xRRGGBB).
runLength	Number of lit pixels in the run.
speed	Pixels advanced per tick (1 = slowest).
bgColor	Background color (default black).
invert	Reverse the travel direction (default false).
bounce	Reverse direction at each end instead of wrapping (default false).

flash()

void hitlib::LedGroup::flash	(	uint32_t	color,
		uint32_t	onMs,
		uint32_t	offMs,
		uint32_t	bgColor = 0x000000 )

Blink the whole strip on and off.

Every pixel lights at once for onMs, then the whole strip shows bgColor for offMs, and the cycle repeats. On and off times are independent, so rate and duty cycle are set separately.

Durations are rounded to whole refresh ticks and clamped to a minimum of one tick, so the strand can't be asked to blink faster than its refresh interval (see the refreshMs constructor parameter).

Parameters

color	Lit color (0xRRGGBB).
onMs	How long the strip stays lit, in milliseconds.
offMs	How long the strip stays blank, in milliseconds.
bgColor	Background color shown while blank (default black).

flow()

void hitlib::LedGroup::flow	(	uint32_t	color1,
		uint32_t	color2,
		uint8_t	speed,
		bool	invert = false,
		bool	seamless = true )

Scroll a two-color gradient across the strip.

Parameters

color1	Start color (0xRRGGBB).
color2	End color (0xRRGGBB).
speed	Pixels shifted per tick.
invert	Scroll in the reverse direction (default false).
seamless	Loop the gradient back to color1 instead of cutting straight from color2 to color1 at the wrap (default true).

rainbow()

void hitlib::LedGroup::rainbow

(

uint8_t

speed

)

Scroll a full HSV rainbow across the strip.

Parameters

speed

Pixels shifted per tick.

twinkle()

void hitlib::LedGroup::twinkle	(	const std::vector< uint32_t > &	colors,
		uint8_t	densityPct = 30,
		uint8_t	fadeStep = 16,
		uint32_t	bgColor = 0x000000 )

Spawn randomly fading sparkles from a color palette.

Each sparkle fades in to full brightness, holds briefly, then fades out. New sparkles are spawned at most one per tick to stagger phase offsets.

Parameters

colors	Color palette, one color is chosen at random per sparkle.
densityPct	Target percentage of LEDs simultaneously lit (0–100).
fadeStep	Brightness step applied each tick (higher = faster fade).
bgColor	Background color shown on unlit pixels (default black).

bitscroll()

void hitlib::LedGroup::bitscroll	(	const std::vector< LedStrand::BitScrollSegment > &	segments,
		uint8_t	speed,
		bool	invert = false,
		uint32_t	bgColor = 0x000000,
		bool	bounce = false,
		uint8_t	spacing = 5,
		bool	repeating = true )

Scroll a pattern of colored segments across the strip.

Parameters

segments	List of BitScrollSegment descriptors defining the pattern.
speed	Pixels advanced per tick.
invert	Scroll in the reverse direction (default false).
bgColor	Color shown between segments and in blank areas.
bounce	Rock the pattern back and forth instead of wrapping.
spacing	Gap pixels inserted between segments (default 5).
repeating	Tile the pattern across the whole strip (true) or show a single copy of it (false). works for both wrapping and bounce travel.

levelFill()

void hitlib::LedGroup::levelFill	(	uint32_t	color,
		uint32_t	color2 = 0x000000,
		bool	gradient = false,
		uint32_t	bgColor = 0x000000,
		bool	invert = false )

Configure the strip as a level meter, and take manual control of it.

Sets up the colors the meter fills with, then leaves the level itself alone, drive it with setLevel(). A meter starts empty, so nothing lights until the first setLevel() call.

With gradient the two colors are laid out across the whole strip, not across the lit part, so a given pixel is always the same color no matter how full the meter is (a VU meter that runs green at the bottom and red at the top, rather than a gradient that stretches). With gradient false only color is used.

The pixel at the edge of the fill is dimmed proportionally rather than snapping on, so a 30-LED strand shows a smooth ramp instead of 30 visible steps.

Calling this takes the meter back to manual control: any MusicTrack or levelSource() reader is detached, since either would overwrite whatever setLevel() puts there on the very next tick.

Parameters

color	Fill color, and the gradient's start color (0xRRGGBB).
color2	Gradient end color. Ignored unless gradient.
gradient	Blend color to color2 across the strip.
bgColor	Color shown on the unfilled part (default black).
invert	Fill from the far end of the strip instead of pixel 0.

setLevel()

void hitlib::LedGroup::setLevel

(

uint8_t

level

)

Set how full the meter is.

Cheap enough to call every control-loop iteration, it only stores a byte, the fill is computed at flush time. Detaches any MusicTrack or levelSource() reader, so manual updates aren't fighting one of those for the same meter.

Parameters

level

0 = empty, 255 = the whole strip lit.

levelSource()

void hitlib::LedGroup::levelSource	(	LedStrand::LevelFn	read,
		double	emptyAt,
		double	fullAt,
		bool	wrap = false,
		uint8_t	smoothing = 0 )

Point the meter at a live value and let it follow it on its own.

The strand polls read once per refresh tick and maps what comes back onto the strip, so a gauge needs no code in your control loop: set it up once (in initialize(), or in a ProfileMode's onActivate) and the bar tracks the value from then on.

Units are yours to choose, emptyAt and fullAt are given in whatever the reader returns:

pros::Motor intake(11);
 
strand.levelFill(0x00FF00, 0xFF0000, true);                 // green -> red scale
strand.levelSource([] { return intake.get_temperature(); },
                   20.0, 70.0);                             // cool -> shutdown hot
 
// A battery gauge that empties as the battery does:
strand.levelSource([] { return pros::battery::get_capacity(); }, 0.0, 100.0);
 
// A bar that fills once per revolution and starts over:
strand.levelSource([] { return arm.get_position(); }, 0.0, 360.0, true);

Values outside the range clamp to empty or full. With wrap they cycle instead, for a continuously turning motor or a heading: 450° of a 0-360 range shows the bar a quarter full, not full.

Putting fullAt below emptyAt is allowed and reverses the meter, so a "distance remaining" bar that drains as a number climbs needs no arithmetic of its own.

This keeps the colors from the preceding levelFill(), it only changes what drives the fill, so call levelFill() first. Any MusicTrack is detached.

Parameters

read	Value to follow. nullptr clears the source, so exported code can name a hook before it is assigned.
emptyAt	Reading that shows an empty strip.
fullAt	Reading that shows a full one.
wrap	Cycle back to empty past fullAt instead of clamping.
smoothing	0-99. How much of the previous frame's fill to keep each tick: 0 follows the value exactly, higher glides toward it, for noisy readings (motor velocity, current draw). The bar still reaches its target, over a few ticks.

clearLevelSource()

void hitlib::LedGroup::clearLevelSource

(

)

Stop following a levelSource() reader, leaving the fill where it is.

The meter stays set up and keeps its colors, it just stops moving on its own, so setLevel() takes over cleanly from here.

musicSync()

void hitlib::LedGroup::musicSync	(	const LedStrand::MusicTrack &	track,
		uint32_t	color,
		uint32_t	color2 = 0x000000,
		bool	gradient = false,
		uint32_t	bgColor = 0x000000,
		bool	invert = false,
		uint8_t	sensitivity = 100,
		bool	loop = false )

Fill the meter from a baked music envelope, and start playing it.

Playback is anchored to the wall clock at the moment of this call, so call it when the music starts, typically from a ProfileMode's onActivate. The strand then tracks the song on its own with no further calls, samples are interpolated between frames so the fill stays smooth even when the envelope's frame rate is coarser than refreshMs.

Colors, gradient and invert behave exactly as in levelFill(). Any levelSource() reader is detached, the song drives the meter now.

Parameters

track	Envelope to play. Must outlive the strand.
color	Fill color, and the gradient's start color.
color2	Gradient end color. Ignored unless gradient.
gradient	Blend color to color2 across the strip.
bgColor	Color shown on the unfilled part.
invert	Fill from the far end of the strip.
sensitivity	Gain applied to every sample, as a percentage. 100 = the envelope as baked, higher makes quiet passages reach further up the strip (and clips loud ones at full), lower makes it more selective.
loop	Restart from the top when the song ends instead of going dark.

musicSeek()

void hitlib::LedGroup::musicSeek

(

uint32_t

positionMs

)

Jump playback to a position in the song.

Parameters

positionMs

Offset from the start of the track, in milliseconds.

musicPause()

void hitlib::LedGroup::musicPause

(

bool

paused = true

)

Pause or resume playback, holding the meter where it is.

Parameters

paused

true to pause, false to resume.

setSensitivity()

void hitlib::LedGroup::setSensitivity

(

uint8_t

pct

)

Change the gain applied to envelope samples without restarting.

Parameters

pct	Percentage gain, see musicSync()'s sensitivity.

spliceMask()

void hitlib::LedGroup::spliceMask	(	uint8_t	sections,
		bool	invert = false,
		bool	alternating = false,
		uint32_t	altPeriodMs = 100,
		uint32_t	bgColor = 0x000000,
		bool	useOverlay = false )

Apply a splice mask that overrides alternating equal-width bins.

The strip is divided into sections + 1 equal bins. Even-indexed bins (or their complement when invert is true) show bgColor, or the overlay buffer when useOverlay is true, instead of the active base animation.

Parameters

sections	Number of divider boundaries (e.g. 1 = two halves). Pass 0 to disable.
invert	Swap which bins are overridden (default false).
alternating	Toggle invert automatically every altPeriodMs.
altPeriodMs	Toggle period when alternating is true (ms).
bgColor	Color shown in masked bins when useOverlay is false.
useOverlay	Show the overlay buffer in masked bins instead of bgColor.

spliceMaskCustom()

void hitlib::LedGroup::spliceMaskCustom

(

const std::vector< LedStrand::SpliceRegion > &

regions

)

Apply a splice mask made of independently placed/sized regions, each running its own animation.

Unlike spliceMask(), regions can start and end anywhere on the strip, don't alternate, and each gets a dedicated buffer generated over just its own width. So e.g. one region can rainbow-scroll while another pulses, simultaneously. Regions stay fixed until spliceMaskCustom() or clearSpliceMask() is called again. Later entries win where regions overlap.

A GAUGE region is the same idea pointed at a sensor instead of a clock: it polls its own reader every tick and colors itself off its own scale, so one strip can carry several independent meters. The strand-wide levelFill() meter is limited to one per strand.

// Six motors, six segments of a 60-LED strip under the drivebase, each
// colored by how hot its own motor is.
pros::Motor drive[6] = {...};
std::vector<LedStrand::SpliceRegion> regions;
for (uint8_t i = 0; i < 6; ++i) {
    regions.push_back(LedStrand::motorHeatGauge(i * 10, 9, readers[i]));
}
strand.spliceMaskCustom(regions);

Parameters

regions

Override regions to apply.

clearSpliceMask()

void hitlib::LedGroup::clearSpliceMask

(

)

Remove the active splice mask, whichever kind is active.

setBrightness()

void hitlib::LedGroup::setBrightness

(

uint8_t

pct

)

Set global brightness for this strand.

Applied non-destructively at flush time, the animation buffers are not modified. Does not require the strand to be re-initialized.

Parameters

pct	Brightness percentage (0 = off, 100 = full). Clamped to [0, 100].

overlaySetColor()

void hitlib::LedGroup::overlaySetColor

(

uint32_t

color

)

Set the overlay buffer to a solid color.

overlayPulse()

void hitlib::LedGroup::overlayPulse	(	uint32_t	color,
		uint8_t	runLength,
		uint8_t	speed,
		uint32_t	bgColor = 0x000000 )

Animate a moving run in the overlay buffer.

overlayFlash()

void hitlib::LedGroup::overlayFlash	(	uint32_t	color,
		uint32_t	onMs,
		uint32_t	offMs,
		uint32_t	bgColor = 0x000000 )

Blink the overlay buffer on and off (see flash()).

overlayFlow()

void hitlib::LedGroup::overlayFlow	(	uint32_t	color1,
		uint32_t	color2,
		uint8_t	speed,
		bool	seamless = true )

Scroll a gradient in the overlay buffer.

Parameters

seamless

Loop the gradient back to color1 instead of cutting straight from color2 to color1 at the wrap (default true). See flow().

overlayRainbow()

void hitlib::LedGroup::overlayRainbow

(

uint8_t

speed

)

Scroll a rainbow in the overlay buffer.

attachProfile()

void hitlib::LedGroup::attachProfile

(

const Profile *

profile

)

Attach a Profile and reset the mode stack.

Parameters

profile

Pointer to a statically-allocated Profile. Must remain valid for the lifetime of the attachment.

detachProfile()

void hitlib::LedGroup::detachProfile

(

)

Detach the active profile and turn the strand off.

activateMode()

void hitlib::LedGroup::activateMode

(

uint8_t

modeIdx

)

Push a persistent mode onto the mode stack.

The mode remains active until explicitly removed with deactivateMode(). Calling this for an already-active persistent mode is a no-op.

Parameters

modeIdx

Index into the attached profile's modes array.

activateModeTimed()

void hitlib::LedGroup::activateModeTimed	(	uint8_t	modeIdx,
		uint32_t	durationMs )

Push a timed mode onto the mode stack.

The mode auto-expires after durationMs milliseconds. If the mode is already active (as a timed entry), its deadline is extended rather than creating a duplicate.

Parameters

modeIdx	Index into the attached profile's modes array.
durationMs	How long the mode stays active (milliseconds).

deactivateMode()

void hitlib::LedGroup::deactivateMode

(

uint8_t

modeIdx

)

Remove a mode from the stack immediately.

Parameters

modeIdx

Index of the mode to remove.

operator[]()

LedStrand * hitlib::LedGroup::operator[] ( size_t i )

inline

Access an individual strand by index.

Useful when you need to apply different animations to specific strands while still using the group for shared commands.

Parameters

i	Zero-based index in the order strands were added.

size()

size_t hitlib::LedGroup::size ( ) const

inline

Return the number of strands in this group.