Statistics
| Revision:

root / include / libdragonfly / lights.h @ 1554

History | View | Annotate | Download (8.84 KB)

1
// FIXME remove
2
typedef unsigned char uint8_t;
3

    
4

    
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
/**
32
 * @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
/**
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
// ***** Predefined colors *****
120
/** @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
/** @brief Turn the orb off **/
143
#define ORB_OFF   0x00
144

    
145

    
146

    
147
// ***** Initialization *****
148

    
149
/** @brief Enables the orbs in default mode **/
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
*         @deprecated This function indexes from 0 instead of 1 **/
187
void orb_n_set (uint8_t num, uint8_t red, uint8_t green, uint8_t blue);
188

    
189
/** @brief Set both orbs to a specified color **/
190
void orb_set(uint8_t red, uint8_t green, uint8_t blue);
191

    
192
/** @brief Set orb1 to a specified color **/
193
void orb1_set(uint8_t red_led, uint8_t green_led, uint8_t blue_led); 
194

    
195
/** @brief Set orb2 to a specified color **/
196
void orb2_set(uint8_t red_led, uint8_t green_led, uint8_t blue_led);
197

    
198
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
/** @brief set the specified orb to the specified color
205
*         @deprecated This function indexes from 0 instead of 1 **/
206
void orb_n_set_color(uint8_t num, uint8_t col);
207

    
208
/** @brief Set orb1 to a specified color **/
209
void orb1_set_color(uint8_t col);
210

    
211
/** @brief Set orb2 to a specified color **/
212
void orb2_set_color(uint8_t col);
213

    
214
/** @brief set the orbs to specified colors **/
215
void orbs_set_color(uint8_t col1, uint8_t col2);
216

    
217
/** @brief Set both orbs to a specified color **/
218
void orb_set_color(uint8_t col);
219

    
220

    
221

    
222
/** @} **/ //end addtogroup
223

    
224
#endif