Animations & Scenes¶

Lightnet's animation system lets you compose multi-layer light shows in JSON and play them across any number of panels. Panel-local animations run entirely on the ATmega after a single setup packet — zero per-frame I²C traffic. Most controller runners compile to per-panel local pulses (one setup burst); RAIN, SPARKLE, and MATRIX spawn stochastic drops over the step window.

How it fits together¶

Text Only

Scene
└── Layer (group ID, panel target, optional palette)
    └── Step  →  Step  →  Step …
        ├── Panel-local  (BREATHE, PULSE, WAVE …)  runs on ATmega
        └── Controller runner  (WAVE, RIPPLE, CHASE, WHEEL, BOUNCE, RAIN, SPARKLE, MATRIX)  compiled/spawned on ESP

Multiple layers within a scene run in parallel. Each layer targets its own set of panels and belongs to a group ID so the controller can start them simultaneously with a single I²C broadcast.

Panel-local animations¶

Run entirely on the ATmega. The controller sends one setup packet; the panel handles every frame itself.

Type	What it does
`SOLID`	Holds a static colour
`FADE`	Linearly interpolates from one colour to another
`TRANSITION`	Interpolates colour from `colorFrom` to `colorTo`
`BREATHE`	Sinusoidal (parabolic) colour envelope — oscillates between `colorFrom` and `colorTo`
`PULSE`	3-phase rise → hold → fall flash
`BLINK`	Binary on/off at a fixed half-period
`HUE_CYCLE`	6-step HSV rainbow rotation
`STROBE`	Binary flash at a frequency in Hz
`REACTIVE`	Decay model triggered by WebSocket beat events

Controller runners¶

Most runners compile to one local PULSE per panel at step start (zero per-frame I²C). RAIN, SPARKLE, and MATRIX are particle spawners that emit drop packets over the step window.

Runner	What it does
`WAVE`	Triangular colour envelope sweeps across the panel list
`RIPPLE`	Colour ring expands outward from an origin panel
`CHASE`	A single lit panel travels through the panel list
`WHEEL`	Rotating-blade sweep from a pivot
`BOUNCE`	Wave band whose peak reflects at field edges
`RAIN` / `SPARKLE` / `MATRIX`	Stochastic particle spawners (drops/flashes/matrix rain)

In this section¶

Concepts — scenes, layers, steps, groups, palettes, colour references, and timing
Animation Types — field reference and parameters for every type and runner
API & Examples — HTTP endpoints, WebSocket triggers, and five worked examples