Skip to content

CLI for SidePulse

Python
6.1 KB
Raw Blame

SidePulse Pro and SidePulse Dot - How it works

SidePulse Pro and SidePulse Dot expose an LED controller as a virtual filesystem, inspired by Linux sysfs. LED animations are controlled by writing commands to the LEDS.LED file. No drivers are needed. SidePulse Pro fits into the SD card slot on MacBook Pro 2021+ models and has 8 RGB LEDs. SidePulse Dot is a tiny 2-LED USB-C device for Mac, iPhone, Linux, and Windows.

On macOS they mount under /Volumes/SidePulsePro and /Volumes/SidePulseDot.

The simplest way to change the color is

$ echo "#FF00FF" > /Volumes/SidePulsePro/LEDS.LED

Or to slowly pulse it.

 $ echo "off\n#FF00FF 1s pulse\nrepeat" > /Volumes/SidePulsePro/LEDS.LED

There is a quirk with the MacBook SD card reader: it can power off SidePulse Pro after 3 minutes of inactivity. A simple way to prevent it is to 'touch' it once a minute like

$ touch /Volumes/SidePulsePro/keepalive

or

$ while touch /Volumes/SidePulsePro/keepalive; do sleep 60; done

To recap, write to LEDS.LED what you want displayed. That's all you have to know.

Initial state.

The content in INIT.LED is played on power up. It can be anything supported by LEDS.LED. Fresh firmware seeds INIT.LED with the one-second startup fill sequence. Writing INIT.LED also applies the new startup program immediately for visual confirmation.

LEDS.LED DSL

Write LED animation programs to LEDS.LED. Each non-empty, non-comment line is one animation step. The embedded controller accepts at most 512 bytes and at most 20 physical lines.

The controller keeps the current visible LED state across parses. A successful parse starts the new program from line 1 using the current state as the transition start colors. A parse error stops the current program and blinks all LEDs red six times with 150 ms on/off phases.

Comments

Blank lines are ignored. Comment lines may start with ;, //, or # .

# all LEDs white
#ffffff

; all LEDs off
off

Colors

Set all LEDs to one color:

#ffffff

Turn all LEDs off:

off

Assign colors by position. LEDs past the list turn off. Extra colors past the compiled LED count are checked for valid syntax, then ignored:

#ff0000 #00ff00 #0000ff

Assign specific LEDs. Unmentioned LEDs hold their current state. Indexes past the compiled LED count are checked for valid syntax, then ignored:

0:#ffffff 2:#ff00ee 7:#0040ff

Multiple segments may appear on one line, separated by semicolons. If an LED is assigned more than once on a line, the last assignment wins:

0:#ff0000 1s; 0:#0000ff 1s

Brightness

Brightness scales the RGB values. It does not change the stored animation colors. Each successful parse starts with brightness 255 unless the program includes brightness N.

brightness 128
#808080

Timing

A color assignment may be followed by:

duration
easing
duration easing
duration easing delay
duration delay
easing delay

Durations and delays accept integer milliseconds, integer seconds, or decimal seconds, up to 65535 ms:

#ff00ff 330ms
#ff00ff ease-in
#ff00ff 0.33s
#ff00ff 0.33s ease-in
#ff00ff 0.33s ease-in 1s
#ff00ff pulse 1s

An easing name without a duration uses the default 330 ms duration. Each line finishes after the longest delay plus duration on that line. A line with no duration, easing, or delay lasts one 60 Hz frame.

Easing

Supported easing names:

linear
ease
ease-in
ease-out
ease-in-out
cosine
pulse
none

cosine is a smooth half-cosine transition from the line's start color to the target color. pulse is a full-cycle envelope: it moves from the line's start color to the target color and back to the start color over one duration. The target color is the peak, not the final hold.

// fade to purple
#ff00ff 0.33s cosine

// pulse to purple and return to the current color
#ff00ff 1.4s pulse

// same pulse using the default 330 ms duration
#ff00ff pulse

none jumps to the target after any delay and holds until the line finishes:

3:#ffffff 80ms none

Roll

Roll the current visible LED state by one full wraparound loop:

roll 2s
roll 2s linear
roll 2s ease
roll-left 800ms ease-in-out
roll-right 1.5s cosine

roll is an alias for roll-right. Missing easing defaults to linear. Duration is the time for one complete loop, so roll 2s returns to the starting arrangement after 2 seconds. Roll always uses the current visible LED state as its source. To roll a chosen palette, set it first:

#ff0044 #ff8800 #ffff00 #00ff66 #00ccff #004cff #8800ff #ff00cc
roll 2s linear
repeat

Delays And Staggering

Different LEDs can use independent timing on the same line:

0:#ff00ff 0.33s ease-in 0s; 1:#00ff00 0.33s linear 250ms

Stagger all 8 LEDs:

0:#ff0000 150ms ease 0ms; 1:#ff8000 150ms ease 50ms; 2:#ffff00 150ms ease 100ms; 3:#00ff00 150ms ease 150ms
4:#00ccff 150ms ease 0ms; 5:#004cff 150ms ease 50ms; 6:#8800ff 150ms ease 100ms; 7:#ff00cc 150ms ease 150ms

Repeat

Loop forever from the first animation line:

0:#ffffff 80ms none
1:#ffffff 80ms none
2:#ffffff 80ms none
repeat

Run the animation before the repeat marker 10 total times, then hold the final state:

#ff0000 200ms none
#00ff00 200ms none
repeat 10

Finite repeat can continue with more animation lines:

off
#ff0000 200ms none
#00ff00 200ms none
repeat 2
off

Examples

Soft breathing pulse:

#404040 1.4s pulse
off 400ms none
repeat

One-line chase step. Only LED 3 changes; all others hold:

3:#ffffff 80ms none

Indexed sparkle:

0:#ffffff 90ms none
2:#ff00ee 90ms none
5:#00ccff 90ms none
off 120ms ease-out
repeat

Smooth seeded roll:

#ff0044 #ff8800 #ffff00 #00ff66 #00ccff #004cff #8800ff #ff00cc
roll 2s linear
repeat

Compile-time LED count matters, but shared scripts are portable. On an 8 LED build, indexes 0 through 7 affect LEDs. On a 2 LED build, only indexes 0 and 1 affect LEDs. Higher indexes and extra color-list entries are parsed so bad syntax still fails, but valid out-of-range LED targets are ignored. A line that only targets ignored LEDs is a no-op.