root / trunk / code / projects / libdragonfly / lights.h @ 1973
History | View | Annotate | Download (8.84 KB)
1 | 1142 | deffi | // FIXME remove
|
---|---|---|---|
2 | typedef unsigned char uint8_t; |
||
3 | |||
4 | |||
5 | 8 | bcoltin | /**
|
6 | 241 | bcoltin | * 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 | /**
|
||
32 | 8 | bcoltin | * @file lights.h
|
33 | * @brief Contains declarations for managing the orbs.
|
||
34 | *
|
||
35 | * Contains declarations for using the orbs and PWM.
|
||
36 | *
|
||
37 | * @author Colony Project, CMU Robotics Club
|
||
38 | * Based on Firefly Library, by Tom Lauwers and Steven Shamlian
|
||
39 | **/
|
||
40 | |||
41 | #ifndef _LIGHTS_H_
|
||
42 | #define _LIGHTS_H_
|
||
43 | |||
44 | /**
|
||
45 | * @addtogroup orbs
|
||
46 | * @{
|
||
47 | **/
|
||
48 | |||
49 | 1144 | deffi | /**
|
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 | /**
|
||
115 | * @addtogroup orbs
|
||
116 | * @{
|
||
117 | **/
|
||
118 | |||
119 | 1142 | deffi | // ***** Predefined colors *****
|
120 | 8 | bcoltin | /** @brief Red **/
|
121 | #define RED 0xE0 |
||
122 | /** @brief Orange **/
|
||
123 | #define ORANGE 0xE4 |
||
124 | /** @brief Yellow **/
|
||
125 | #define YELLOW 0xE8 |
||
126 | /** @brief Lime **/
|
||
127 | #define LIME 0x68 |
||
128 | /** @brief Green **/
|
||
129 | #define GREEN 0x1C |
||
130 | /** @brief Cyan **/
|
||
131 | #define CYAN 0x1F |
||
132 | /** @brief Blue **/
|
||
133 | #define BLUE 0x03 |
||
134 | /** @brief Pink **/
|
||
135 | #define PINK 0xA6 |
||
136 | /** @brief Purple **/
|
||
137 | #define PURPLE 0x41 |
||
138 | /** @brief Magenta **/
|
||
139 | #define MAGENTA 0xE3 |
||
140 | /** @brief White **/
|
||
141 | #define WHITE 0xFE |
||
142 | 1142 | deffi | /** @brief Turn the orb off **/
|
143 | #define ORB_OFF 0x00 |
||
144 | 8 | bcoltin | |
145 | 1142 | deffi | |
146 | |||
147 | // ***** Initialization *****
|
||
148 | |||
149 | /** @brief Enables the orbs in default mode **/
|
||
150 | 8 | bcoltin | void orb_init(void); |
151 | 1142 | deffi | |
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 | 1404 | nparis | /** @brief set the specified orb to a specified color
|
186 | * @deprecated This function indexes from 0 instead of 1 **/
|
||
187 | 1142 | deffi | void orb_n_set (uint8_t num, uint8_t red, uint8_t green, uint8_t blue);
|
188 | |||
189 | 8 | bcoltin | /** @brief Set both orbs to a specified color **/
|
190 | 1142 | deffi | void orb_set(uint8_t red, uint8_t green, uint8_t blue);
|
191 | |||
192 | 8 | bcoltin | /** @brief Set orb1 to a specified color **/
|
193 | 1142 | deffi | void orb1_set(uint8_t red_led, uint8_t green_led, uint8_t blue_led);
|
194 | |||
195 | 8 | bcoltin | /** @brief Set orb2 to a specified color **/
|
196 | 1142 | deffi | void orb2_set(uint8_t red_led, uint8_t green_led, uint8_t blue_led);
|
197 | 8 | bcoltin | |
198 | 1142 | deffi | void orbs_set (uint8_t red1, uint8_t green1, uint8_t blue1, uint8_t red2, uint8_t green2, uint8_t blue2);
|
199 | |||
200 | |||
201 | |||
202 | // ***** Settings predefined colors *****
|
||
203 | |||
204 | 1404 | nparis | /** @brief set the specified orb to the specified color
|
205 | * @deprecated This function indexes from 0 instead of 1 **/
|
||
206 | 1142 | deffi | void orb_n_set_color(uint8_t num, uint8_t col);
|
207 | |||
208 | 8 | bcoltin | /** @brief Set orb1 to a specified color **/
|
209 | 1142 | deffi | void orb1_set_color(uint8_t col);
|
210 | |||
211 | 8 | bcoltin | /** @brief Set orb2 to a specified color **/
|
212 | 1142 | deffi | void orb2_set_color(uint8_t col);
|
213 | 8 | bcoltin | |
214 | 1142 | deffi | /** @brief set the orbs to specified colors **/
|
215 | void orbs_set_color(uint8_t col1, uint8_t col2);
|
||
216 | 8 | bcoltin | |
217 | 1142 | deffi | /** @brief Set both orbs to a specified color **/
|
218 | void orb_set_color(uint8_t col);
|
||
219 | |||
220 | |||
221 | |||
222 | 8 | bcoltin | /** @} **/ //end addtogroup |
223 | |||
224 | #endif |