Project

General

Profile

Revision 1345

Added by Rich Hong over 11 years ago

Final spline code for master/slave

updated outdated libdragonfly and libwireless

View differences:

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