Colony

/**

 * Quick start: call orb_init_pwm or orb_init_binary, depending on which mode you want to use. Call orb*set or

 * orb*set_color to set the orbs.

 * 

 * The orbs have two modes of operation: PWM mode and binary mode. In PWM mode, a pwm signal is generated by a hardware

 * timer and the orbs can be set to a value of 0 through 255. In binary mode, the orbs can only be turned on or off and

 * a value of 0 means "off" and any other value means "on". The mode can be chosen on initialization and can be changed

 * at runtime using the orb_set_mode function.

 *

 * Operation (PWM mode): On timer overflow, all LEDs with a value>0 are turned on and the output compare value for the

 * first LED is loaded. On compare match, the corresponding LED is turned off and the next output compare value is

 * loaded. All masks are precomputed and sorted by time when setting the values.

 *

 * The data structure (pwm_t) containing the PWM times and masks is triple buffered. This is because the buffer the ISR

 * is reading from may only be modified on timer overflow before the next PWM sequence is started, because otherwise the

 * next OCR value might be sed to a value smaller than the current timer value, resulting in the remaining channels not

 * being turned off in that PWM period (flash to on). When using two buffers, the page flip can only occur on a timer

 * overflow for the same reason. So after writing a buffer and marking it for page flip, neither of the buffers could be

 * modified because the front buffer is read by the ISR and the back buffer could be switched at any time. So the

 * calling thread would have to be delayed by up to one full PWM period (8ms in the current implementation, but

 * 20ms-50ms would be a reasonable value to expect here). To avoid this, triple buffering is used.

 *

 * The code for applying the orbs is fairly optimized. See the apply_orbs function for some time measurements and

 * further nodes.

 *

 * The PWM frequency is 120Hz (8ms period time). The next lower frequency (determined by the prescaler) is 30 Hz which

 * is too slow (orbs flicker).

 *

 * The orbs code is thread safe, which means that the functions may be called from another interrupt handler. If there

 * are multiple concurrent calls to the orb*set* functions, one of them is ignored and the orbs are never left in an

 * inconsistent state. For example, if the orbs are set to green by the main thread and to red by an interrupt handler,

 * the resulting color will be either red or green, but never yellow.

 * Thread safety is achieved by grabbing a lock at the beginning of all functions that modify the orb code and releasing

 * the lock at the end. If the lock is already taken, the function just returns doing nothing.

 *

 * Some performance measurements:

 *   - Time for setting new orb values (PWM mode):       35us-72us (depending on the degree to which the array is

 *                                                                  already in the correct order)

 *   - Time for setting new orb values (binary mode):        5.5us

 *

 *   - Interrupt time (PWM mode only):                         8us (overflow)

 *                                                            10us (output compare)

 *                                                             6us (last output compare)

 *                                                            30us (output compare, all value equal)

 *

 *   - Maximum total interrupt time per period:               64us

 *   - Maximum CPU usage for interrupts (PWM mode only):     <0.8%

 *

 *   - Maximum contiguous synchronized block:                 30us (output compare interrupt, all values equal)

 *

 * There are some potential optimizations left. See the source code for more information.

 *

 * A note on robustness: if the output compare interrupt is disabled for too long, either due to a long ISR or a long

 * synchronized code block, the orbs will flicker to brighter values for being turned off too late. With software PWM,

 * there's nothing at all to be done about that. The problem can be alleviated by using a lower PWM frequency, but then

 * the orbs will start flickering all the time due to the low update frequency.

 * Some measurements: with 100us synchronized blocks, the flickering is accepptably low. Longer synchronized blocks

 * mean more flickering. At 1ms synchronized blocks, the flickering is quite bad, especially for low orb values. Note

 * that orb value 0 never flickers at all because the corresponding channels are not turned on at all.

 * Test code (not the _delay_us restrictions!)

 *   orb_set (1,1,1); while (1) { SYNC { for (uint8_t m=0; m<10; ++m) { _delay_us(10); } } }

 **/

/*

All different:

Overflow: 8us

OC: 5*10+1*6

All same:

OC: 30us

*/