Revision 1345
Final spline code for master/slave
updated outdated libdragonfly and libwireless
lights.h | ||
---|---|---|
1 |
// FIXME remove |
|
2 |
typedef unsigned char uint8_t; |
|
3 |
|
|
4 |
|
|
1 | 5 |
/** |
6 |
* Copyright (c) 2007 Colony Project |
|
7 |
* |
|
8 |
* Permission is hereby granted, free of charge, to any person |
|
9 |
* obtaining a copy of this software and associated documentation |
|
10 |
* files (the "Software"), to deal in the Software without |
|
11 |
* restriction, including without limitation the rights to use, |
|
12 |
* copy, modify, merge, publish, distribute, sublicense, and/or sell |
|
13 |
* copies of the Software, and to permit persons to whom the |
|
14 |
* Software is furnished to do so, subject to the following |
|
15 |
* conditions: |
|
16 |
* |
|
17 |
* The above copyright notice and this permission notice shall be |
|
18 |
* included in all copies or substantial portions of the Software. |
|
19 |
* |
|
20 |
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, |
|
21 |
* EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES |
|
22 |
* OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND |
|
23 |
* NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT |
|
24 |
* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, |
|
25 |
* WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING |
|
26 |
* FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR |
|
27 |
* OTHER DEALINGS IN THE SOFTWARE. |
|
28 |
**/ |
|
29 |
|
|
30 |
|
|
31 |
/** |
|
2 | 32 |
* @file lights.h |
3 | 33 |
* @brief Contains declarations for managing the orbs. |
4 | 34 |
* |
... | ... | |
11 | 41 |
#ifndef _LIGHTS_H_ |
12 | 42 |
#define _LIGHTS_H_ |
13 | 43 |
|
44 |
/** |
|
45 |
* @addtogroup orbs |
|
46 |
* @{ |
|
47 |
**/ |
|
14 | 48 |
|
15 | 49 |
/** |
50 |
* Quick start: call orb_init_pwm or orb_init_binary, depending on which mode you want to use. Call orb*set or |
|
51 |
* orb*set_color to set the orbs. |
|
52 |
* |
|
53 |
* The orbs have two modes of operation: PWM mode and binary mode. In PWM mode, a pwm signal is generated by a hardware |
|
54 |
* 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 |
|
55 |
* a value of 0 means "off" and any other value means "on". The mode can be chosen on initialization and can be changed |
|
56 |
* at runtime using the orb_set_mode function. |
|
57 |
* |
|
58 |
* Operation (PWM mode): On timer overflow, all LEDs with a value>0 are turned on and the output compare value for the |
|
59 |
* first LED is loaded. On compare match, the corresponding LED is turned off and the next output compare value is |
|
60 |
* loaded. All masks are precomputed and sorted by time when setting the values. |
|
61 |
* |
|
62 |
* The data structure (pwm_t) containing the PWM times and masks is triple buffered. This is because the buffer the ISR |
|
63 |
* is reading from may only be modified on timer overflow before the next PWM sequence is started, because otherwise the |
|
64 |
* next OCR value might be sed to a value smaller than the current timer value, resulting in the remaining channels not |
|
65 |
* being turned off in that PWM period (flash to on). When using two buffers, the page flip can only occur on a timer |
|
66 |
* overflow for the same reason. So after writing a buffer and marking it for page flip, neither of the buffers could be |
|
67 |
* modified because the front buffer is read by the ISR and the back buffer could be switched at any time. So the |
|
68 |
* calling thread would have to be delayed by up to one full PWM period (8ms in the current implementation, but |
|
69 |
* 20ms-50ms would be a reasonable value to expect here). To avoid this, triple buffering is used. |
|
70 |
* |
|
71 |
* The code for applying the orbs is fairly optimized. See the apply_orbs function for some time measurements and |
|
72 |
* further nodes. |
|
73 |
* |
|
74 |
* The PWM frequency is 120Hz (8ms period time). The next lower frequency (determined by the prescaler) is 30 Hz which |
|
75 |
* is too slow (orbs flicker). |
|
76 |
* |
|
77 |
* The orbs code is thread safe, which means that the functions may be called from another interrupt handler. If there |
|
78 |
* are multiple concurrent calls to the orb*set* functions, one of them is ignored and the orbs are never left in an |
|
79 |
* inconsistent state. For example, if the orbs are set to green by the main thread and to red by an interrupt handler, |
|
80 |
* the resulting color will be either red or green, but never yellow. |
|
81 |
* Thread safety is achieved by grabbing a lock at the beginning of all functions that modify the orb code and releasing |
|
82 |
* the lock at the end. If the lock is already taken, the function just returns doing nothing. |
|
83 |
* |
|
84 |
* Some performance measurements: |
|
85 |
* - Time for setting new orb values (PWM mode): 35us-72us (depending on the degree to which the array is |
|
86 |
* already in the correct order) |
|
87 |
* - Time for setting new orb values (binary mode): 5.5us |
|
88 |
* |
|
89 |
* - Interrupt time (PWM mode only): 8us (overflow) |
|
90 |
* 10us (output compare) |
|
91 |
* 6us (last output compare) |
|
92 |
* 30us (output compare, all value equal) |
|
93 |
* |
|
94 |
* - Maximum total interrupt time per period: 64us |
|
95 |
* - Maximum CPU usage for interrupts (PWM mode only): <0.8% |
|
96 |
* |
|
97 |
* - Maximum contiguous synchronized block: 30us (output compare interrupt, all values equal) |
|
98 |
* |
|
99 |
* There are some potential optimizations left. See the source code for more information. |
|
100 |
* |
|
101 |
* A note on robustness: if the output compare interrupt is disabled for too long, either due to a long ISR or a long |
|
102 |
* synchronized code block, the orbs will flicker to brighter values for being turned off too late. With software PWM, |
|
103 |
* there's nothing at all to be done about that. The problem can be alleviated by using a lower PWM frequency, but then |
|
104 |
* the orbs will start flickering all the time due to the low update frequency. |
|
105 |
* Some measurements: with 100us synchronized blocks, the flickering is accepptably low. Longer synchronized blocks |
|
106 |
* mean more flickering. At 1ms synchronized blocks, the flickering is quite bad, especially for low orb values. Note |
|
107 |
* that orb value 0 never flickers at all because the corresponding channels are not turned on at all. |
|
108 |
* Test code (note the _delay_us restrictions!) |
|
109 |
* orb_set (1,1,1); while (1) { SYNC { for (uint8_t m=0; m<10; ++m) { _delay_us(10); } } } |
|
110 |
**/ |
|
111 |
|
|
112 |
/** @} **/ //end addtogroup |
|
113 |
|
|
114 |
/** |
|
16 | 115 |
* @addtogroup orbs |
17 | 116 |
* @{ |
18 | 117 |
**/ |
19 | 118 |
|
20 |
//ORB Colors
|
|
119 |
// ***** Predefined colors *****
|
|
21 | 120 |
/** @brief Red **/ |
22 | 121 |
#define RED 0xE0 |
23 | 122 |
/** @brief Orange **/ |
... | ... | |
40 | 139 |
#define MAGENTA 0xE3 |
41 | 140 |
/** @brief White **/ |
42 | 141 |
#define WHITE 0xFE |
43 |
/** @brief Turn the orb off (White) **/
|
|
44 |
#define ORB_OFF 0xFE //ORB_OFF->WHITE
|
|
142 |
/** @brief Turn the orb off **/ |
|
143 |
#define ORB_OFF 0x00
|
|
45 | 144 |
|
46 |
/** @brief Enables the orbs **/ |
|
145 |
|
|
146 |
|
|
147 |
// ***** Initialization ***** |
|
148 |
|
|
149 |
/** @brief Enables the orbs in default mode **/ |
|
47 | 150 |
void orb_init(void); |
151 |
|
|
152 |
/** @brief Enables the orbs in binary mode **/ |
|
153 |
void orb_init_binary (void); |
|
154 |
|
|
155 |
/** @brief Enables the orbs in PWM mode **/ |
|
156 |
void orb_init_pwm (void); |
|
157 |
|
|
158 |
|
|
159 |
|
|
160 |
// ***** Mode setting ***** |
|
161 |
|
|
162 |
/** Specification of the orb mode **/ |
|
163 |
typedef uint8_t orb_mode_t; |
|
164 |
|
|
165 |
/** @brief PWM mode **/ |
|
166 |
#define orb_mode_pwm 0 |
|
167 |
|
|
168 |
/** @brief Binary mode **/ |
|
169 |
#define orb_mode_binary 1 |
|
170 |
|
|
171 |
|
|
172 |
/** @brief Switches the orbs to the specified mode **/ |
|
173 |
void orb_set_mode (orb_mode_t mode); |
|
174 |
|
|
175 |
/** @brief Disables the orb timer, but does not change the mode **/ |
|
176 |
void orb_disable_timer (void); |
|
177 |
|
|
178 |
/** @brief Enables the orb timer, but does not change the mode **/ |
|
179 |
void orb_enable_timer (void); |
|
180 |
|
|
181 |
|
|
182 |
|
|
183 |
// ***** Setting RGB colors ***** |
|
184 |
|
|
185 |
/** @brief set the specified orb to a specified color **/ |
|
186 |
void orb_n_set (uint8_t num, uint8_t red, uint8_t green, uint8_t blue); |
|
187 |
|
|
48 | 188 |
/** @brief Set both orbs to a specified color **/ |
49 |
void orb_set(unsigned char red_led, unsigned char green_led,
|
|
50 |
unsigned char blue_led); |
|
189 |
void orb_set(uint8_t red, uint8_t green, uint8_t blue);
|
|
190 |
|
|
51 | 191 |
/** @brief Set orb1 to a specified color **/ |
52 |
void orb1_set(unsigned char red_led, unsigned char green_led,
|
|
53 |
unsigned char blue_led); |
|
192 |
void orb1_set(uint8_t red_led, uint8_t green_led, uint8_t blue_led);
|
|
193 |
|
|
54 | 194 |
/** @brief Set orb2 to a specified color **/ |
55 |
void orb2_set(unsigned char red_led, unsigned char green_led, |
|
56 |
unsigned char blue_led); |
|
195 |
void orb2_set(uint8_t red_led, uint8_t green_led, uint8_t blue_led); |
|
57 | 196 |
|
58 |
/** @brief Set both orbs to a specified color **/ |
|
59 |
void orb_set_color(int col); |
|
197 |
void orbs_set (uint8_t red1, uint8_t green1, uint8_t blue1, uint8_t red2, uint8_t green2, uint8_t blue2); |
|
198 |
|
|
199 |
|
|
200 |
|
|
201 |
// ***** Settings predefined colors ***** |
|
202 |
|
|
203 |
/** @brief set the specified orb to the specified color **/ |
|
204 |
void orb_n_set_color(uint8_t num, uint8_t col); |
|
205 |
|
|
60 | 206 |
/** @brief Set orb1 to a specified color **/ |
61 |
void orb1_set_color(int col); |
|
207 |
void orb1_set_color(uint8_t col); |
|
208 |
|
|
62 | 209 |
/** @brief Set orb2 to a specified color **/ |
63 |
void orb2_set_color(int col);
|
|
210 |
void orb2_set_color(uint8_t col);
|
|
64 | 211 |
|
65 |
/** @brief Disable the orbs **/ |
|
66 |
void orb_disable(void); |
|
67 |
/** @brief Enable the orbs **/ |
|
68 |
void orb_enable(void); |
|
212 |
/** @brief set the orbs to specified colors **/ |
|
213 |
void orbs_set_color(uint8_t col1, uint8_t col2); |
|
69 | 214 |
|
215 |
/** @brief Set both orbs to a specified color **/ |
|
216 |
void orb_set_color(uint8_t col); |
|
217 |
|
|
218 |
|
|
219 |
|
|
70 | 220 |
/** @} **/ //end addtogroup |
71 | 221 |
|
72 | 222 |
#endif |
73 |
|
Also available in: Unified diff