Defines | |
| #define | RED 0xE0 |
| Red. | |
| #define | ORANGE 0xE4 |
| Orange. | |
| #define | YELLOW 0xE8 |
| Yellow. | |
| #define | LIME 0x68 |
| Lime. | |
| #define | GREEN 0x1C |
| Green. | |
| #define | CYAN 0x1F |
| Cyan. | |
| #define | BLUE 0x03 |
| Blue. | |
| #define | PINK 0xA6 |
| Pink. | |
| #define | PURPLE 0x41 |
| Purple. | |
| #define | MAGENTA 0xE3 |
| Magenta. | |
| #define | WHITE 0xFE |
| White. | |
| #define | ORB_OFF 0x00 |
| Turn the orb off. | |
| #define | orb_mode_pwm 0 |
| PWM mode. | |
| #define | orb_mode_binary 1 |
| Binary mode. | |
Typedefs | |
| typedef uint8_t | orb_mode_t |
Functions | |
| void | orb_init (void) |
| Enables the orbs in default mode. | |
| void | orb_init_binary (void) |
| Enables the orbs in binary mode. | |
| void | orb_init_pwm (void) |
| Enables the orbs in PWM mode. | |
| void | orb_set_mode (orb_mode_t mode) |
| Switches the orbs to the specified mode. | |
| void | orb_disable_timer (void) |
| Disables the orb timer, but does not change the mode. | |
| void | orb_enable_timer (void) |
| Enables the orb timer, but does not change the mode. | |
| void | orb_n_set (uint8_t num, uint8_t red, uint8_t green, uint8_t blue) |
| set the specified orb to a specified color | |
| void | orb_set (uint8_t red, uint8_t green, uint8_t blue) |
| Set both orbs to a specified color. | |
| void | orb1_set (uint8_t red_led, uint8_t green_led, uint8_t blue_led) |
| Set orb1 to a specified color. | |
| void | orb2_set (uint8_t red_led, uint8_t green_led, uint8_t blue_led) |
| Set orb2 to a specified color. | |
| void | orbs_set (uint8_t red1, uint8_t green1, uint8_t blue1, uint8_t red2, uint8_t green2, uint8_t blue2) |
| void | orb_n_set_color (uint8_t num, uint8_t col) |
| set the specified orb to the specified color | |
| void | orb1_set_color (uint8_t col) |
| Set orb1 to a specified color. | |
| void | orb2_set_color (uint8_t col) |
| Set orb2 to a specified color. | |
| void | orbs_set_color (uint8_t col1, uint8_t col2) |
| set the orbs to specified colors | |
| void | orb_set_color (uint8_t col) |
| Set both orbs to a specified color. | |
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:
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 (note the _delay_us restrictions!) orb_set (1,1,1); while (1) { SYNC { for (uint8_t m=0; m<10; ++m) { _delay_us(10); } } }
| typedef uint8_t orb_mode_t |
Specification of the orb mode
| void orb1_set | ( | uint8_t | red, | |
| uint8_t | green, | |||
| uint8_t | blue | |||
| ) |
Set orb1 to a specified color.
Set orb1 to the color specified. The orbs must be initialized before this function may be used. Note that, when setting both orbs, using orbs_set is faster then setting the orbs individually because the values are only sorted once.
| red | the red component of the color | |
| green | the green component of the color | |
| blue | the blue component of the color |
| void orb1_set_color | ( | uint8_t | col | ) |
Set orb1 to a specified color.
Set orb1 to the specified color. This function is intended to be used with the predefined colors.
| col | the color to set the orbs to |
| void orb2_set | ( | uint8_t | red, | |
| uint8_t | green, | |||
| uint8_t | blue | |||
| ) |
Set orb2 to a specified color.
Set orb2 to the color specified. The orbs must be initialized before this function may be used. Note that, when setting both orbs, using orbs_set is faster then setting the orbs individually because the values are only sorted once.
| red_led | the red component of the color | |
| green_led | the green component of the color | |
| blue_led | the blue component of the color |
| void orb2_set_color | ( | uint8_t | col | ) |
Set orb2 to a specified color.
Set orb2 to the specified color. This function is intended to be used with the predefined colors.
| col | the color to set the orbs to |
| void orb_disable_timer | ( | void | ) |
Disables the orb timer, but does not change the mode.
Disables the orb timer. Note that you usually don't want to use this function directly. Instead, use orb_set_mode.
| void orb_enable_timer | ( | void | ) |
Enables the orb timer, but does not change the mode.
Enables the orb timer. Note that you usually don't want to use this function directly. Instead, use orb_set_mode.
| void orb_init | ( | void | ) |
Enables the orbs in default mode.
Initializes the orbs in default mode. One of the orb_init* functions must be called before the orbs can be used. Use the orb_init_binary or orb_init_pwm function if you want one specific mode.
| void orb_init_binary | ( | void | ) |
Enables the orbs in binary mode.
Initializes the orbs in PWM mode. One of the orb_init* functions must be called before the orbs can be used.
| void orb_init_pwm | ( | void | ) |
Enables the orbs in PWM mode.
Initializes the orbs in PWM mode. One of the orb_init* functions must be called before the orbs can be used.
| void orb_n_set | ( | uint8_t | num, | |
| uint8_t | red, | |||
| uint8_t | green, | |||
| uint8_t | blue | |||
| ) |
set the specified orb to a specified color
Sets the specified orb to the specified color. The orbs must be initialized before this function may be used. Note that, when setting both orbs, using orbs_set is faster then setting the orbs individually because the values are only sorted once.
| num | the number of the orb to set (0 or 1) | |
| red | the red value for the specified orb | |
| green | the green value for the specified orb | |
| blue | the blue value for the specified orb |
| void orb_n_set_color | ( | uint8_t | num, | |
| uint8_t | col | |||
| ) |
set the specified orb to the specified color
Set the specified orb to the specified color. This function is intended to be used with the predefined colors.
| num | the number of the orb to set (0 or 1) | |
| col | the color to set the orbs to |
| void orb_set | ( | uint8_t | red, | |
| uint8_t | green, | |||
| uint8_t | blue | |||
| ) |
Set both orbs to a specified color.
Set both orbs to the color specified. The orbs must be initialized before this function may be used.
| red_led | the red component of the color | |
| green_led | the green component of the color | |
| blue_led | the blue component of the color |
| void orb_set_color | ( | uint8_t | col | ) |
Set both orbs to a specified color.
Set both orbs to the specified color. This function is intended to be used with the predefined colors.
| col | the color to set the orbs to |
| void orbs_set | ( | uint8_t | red1, | |
| uint8_t | green1, | |||
| uint8_t | blue1, | |||
| uint8_t | red2, | |||
| uint8_t | green2, | |||
| uint8_t | blue2 | |||
| ) |
Set the orbs to the respective values. The orbs must be initialized before this function may be used. Note that, when setting both orbs, this function is faster than calling orb1_set and orb2_set (or orb_n_set) because the values are only sorted once.
| red1 | ||
| green1 | ||
| blue1 | ||
| red2 | ||
| green2 | ||
| blue2 |
| void orbs_set_color | ( | uint8_t | col1, | |
| uint8_t | col2 | |||
| ) |
set the orbs to specified colors
Set the orbs to the respective color. This function is intended to be used with the predefined colors.
| col1 | the color to set orb 1 to | |
| col2 | the color to set orb 2 to |
1.5.8