design.txt

A quick and dirty description of the software design...

Work in progress... Feel free to fold spindle and mutilate

Serenity Effects
Serenity supports four different types of effects:
    * Flame effects
    * Jar LED effects
    * Sound effects
    * Firefly LED effects

Flame Effects
Flame effects include triggering individual poofers and running poofer
sequences - see the flame controller code in Noetica for an example of
how this can be done. I would suggest using the same high-level 
specification for a sequence that we used in Noetica - the code already
exists and is working, which is always a plus.

One difference from Noetica from Noetica is instead of having a 
single large sculpture, we have three separate bugs. I'd suggest 
that we (mostly) define sequences that run on a single bug, with
the exception of an all-poof (always a favorite) and a global chase.

Since the admin console and the central controller are separate, the admin
console depends on the controller for lists of IDs (bug, sound controller, and
so forth) rather than coding / loading it in two places.

Assuming that we have a mechanism to define the sequences, the API 
to the UI would look something like:
PUT /flames/sequences/<sequencename> bugid=<bugid>
PUT /flames/stop bugid=<bugid>
PUT /flames/poofers/<pooferid> on=<tf> duration=<some_relatively_short_duration> bugid=<bugid>
POST /flames/sequences/<sequencename>
GET /flames/sequences
GET /flames/poofers 
GET /flames/bugs (bugid is also used for jar LEDs)
DELETE /flames/sequences/<sequencename> (although dont allow deletion of built in all-poof and chase)

Jar LED Effects
I'm imagining the same sort of thing as above, except without the ability to
add and delete patterns from the fuel depot. Although we might want to allow
people to add images... Anyway - there's one Jar piece for each bug, so 
the API looks some thing like:
PUT /light/jar/patterns/<patternid> bugid=<bugid> image=<imageid>
GET /light/jar/patterns
GET /light/jar/images (if we can use images. Images end up being a good way to grab a
color palette, even if we can't project the actual image on the the jar. See the
Soma code for an example of this)
POST /light/jar/images
DELETE /light/jar/images/<imageid>

Firefly Effects
Here we can set the blink interval (which probably ends up following a gaussian)
and a color. There are probably other interesting effects as well - think of more!
GET /light/firefly/swarms
PUT /light/firefly/interval/<interval> swarmid=<swarmid>
PUT /light/firefly/color/<color (or color sequence)? swarmid=<swarmid>

Sound Effects
Looking at what Ted was showing a couple of weeks back, we seem to have the
ability to layer sound effects over one another, and to turn off a particular
effect. I'd also like to have some controls over the ambient buzzing sound as well.
There are a (currently unknown) number of separate sound controllers in the field. 

NOTE: The sound API is likely to change significantly. Comments from cswales:

https://github.com/FlamingLotusGirls/Serenity/pull/1#issuecomment-496274887

> In terms of what the sound system can do - each controller has two different
> output channels that can be controlled independently. In each channel we can mix
> together a set of sound effects, and those effects can be layered on top of one
> another. The button box that Ted showed me had a button for 'add more sound
> effect X' and another for 'stop all sound effect X'. Thinking at a design level,
> I'd like to have a certain background noise/drone/effects that the participants
> *cant* change, and then ideally some set of buttons like Ted's that the
> participants can use to add additional sounds on top of the ambient. That says
> that our admin app definitely needs to be able to modify, save, and restore the
> ambient, and probably needs to be able to have some control over the effects.

These are covered in the sound directory, please see the REST.md in the sound
directory for definitions of the REST calls in question.