# SidePulse for agents

Dot: a small USB-C device with two RGB LEDs, connected to the user's iPhone or Android phone.
Signal completion, request input, or animate for fun :) The phone app forwards
updates to Dot; mobile push delivery may be delayed.

SidePulse Pro: an 8-LED status indicator for a MacBook Pro's SD card slot.

`<channel-id>` = everything after `#` in the user's original link, including
`apns_` or `fcm_` and any suffix. Keep the full link and token private.
POST JSON to `https://bridge.sidepulse.io/api/leds/<channel-id>` as below.
Copied Android tokens already begin with `fcm_`; use the copied channel exactly,
without adding another prefix. An Android channel is
`fcm_<opaque registration token>_<32 lowercase hexadecimal sender key>`.
Registration tokens can contain underscores and colons: only the final
`_` plus 32 characters is the authorization suffix. Preserve the entire link.

For Android, JSON objects are preserved; plain LED text is wrapped as `{"leds":"<exact text>"}`.
The bridge replaces root `shared_key` and `sidepulse_push_id` with the URL key
and one generated UUID. An optional `sidepulse_event_id` is preserved.
For Android, every FCM data value is a string: nested `data`, `payload`, `aps`,
and `notification` dictionaries are serialized as compact JSON strings.
Never request a provider notification; Android authorizes data before showing
notifications or writing to Dot. The app owns sender-key expiration/revocation.
Use `title`, `body`, `pattern`, or `leds`, and keep all keys and values together
below the 3,500-byte UTF-8 data budget, including bridge-injected metadata.
`OK` on a push channel means provider acceptance; authorized app receipt and
physical Dot output still need verification.

LED syntax: `#RRGGBB duration effect`, one step per line (`\n` in JSON).
One color sets both LEDs; two set them separately. `pulse` breathes, `cosine`
fades, `none` holds; `off` clears. Limits: 512 bytes, 20 lines.

`repeat` loops forever; `repeat 3` plays the preceding animation three times
total, then continues or holds the final state. `roll 2s` rotates the current
colors one full turn in two seconds; `roll-left`/`roll-right` choose direction.
Set colors first:

    #FF00FF #00E5FF
    roll 2s
    repeat 3

Independent timing: `index:color duration effect delay`, indexes `0`/`1`.
Join assignments with `;` to run together, each with its own duration/delay.
The next line waits for both.

**Needs input: looping amber pulse.**

    curl --fail-with-body 'https://bridge.sidepulse.io/api/leds/<channel-id>' \
      -H 'Content-Type: application/json' \
      -d '{"leds":"off\n#FF3A00 1.6s pulse\nrepeat\n"}'

Alternative `.LED` programs: put the text in the same request's `leds` field.

**Working: looping cyan pulses, 760 ms each; LED 0 starts immediately, LED 1 after 260 ms.**

    off 320ms cosine
    0:#00E5FF 760ms pulse 0ms; 1:#00E5FF 760ms pulse 260ms
    repeat

**Fun: looping magenta (LED 0, 300 ms) and cyan (LED 1, 1200 ms, delayed 600 ms).**

    off
    0:#FF00FF 300ms pulse 0ms; 1:#00E5FF 1200ms pulse 600ms
    repeat

**Done: two green pulses, then off; plays once.**

    off
    #00FF66 #00FF66 240ms pulse
    #000000 #000000 140ms none
    #00FF66 #00FF66 640ms pulse
    #000000 #000000 400ms none

[Full animation spec, including individual timing/delays](https://github.com/inteliwear/sidepulse/blob/main/LEDS_FORMAT.md#delays-and-staggering).