3 <doc style="style.css">
7 <title>Bedroom light control</title>
11 <heading>Requirements</heading>
13 <heading>Top level requirements</heading>
17 Wake up lights fade in to specified color or slightly open curtains.
21 wake up light starts at preset alarm time
25 if outside light open curtain else fade to light level
29 open curtain and fade out light at sunrise
33 input from sunrise calculation and outside light sensor
37 user interface for alarm times
41 user interface for wake up light level, sleep light level, walk-in light level and fade times
45 light on at walking in and no outside light
49 lights fade to dark at sleep time
53 lights fade on to specified color at movement in the night.
57 curtains fully open if outside light and after alarm
61 curtains close ar outside dark
65 wake up times can be specified with a recurrance pattern
69 recurrence patterns can be n days, weeks, months, years, weekday, weekendday
73 wake up times can be optained from a online calander
79 <heading>Manual controls</heading>
83 manual controls override automatic controls
87 manual control for light levels
91 manual control for light on and off
95 manual control for curtains open and close
99 manual control from switches
103 manual control from remote, online
110 <heading>Security requirements</heading>
114 Accessible by authorized persons and devices only
118 All remote inputs are logged.
124 <heading>Testability requirements</heading>
128 Time is obtained from actual time or simulated time
132 A simulated time base is used for testing
140 <heading>Test scenarios</heading>
144 Wake up sequence when dark outside followed by sunrise
146 <item>Set the date to dec 21, 23:00.</item>
147 <item>Set a wakeup event at dec 22, 06:00</item>
151 wake up sequence when light outside
154 wake up with a single alarm event
157 wake up with recurring alarm events
169 curtains close at dusk
176 <heading>Interfaces</heading>
183 alarm time for wake up
186 calculated sunrise and sunset time
195 remote control inputs
211 curtain open and close
219 <heading>Modules</heading>
221 The dataflow diagram shows the high level design.
223 <svg src='dataflow.svg'/>
225 <heading>PWM generator</heading>
227 The PWM generator is controlled by a list of <emph>pwm</emph> structures:
237 Each structure holds an interval in microseconds and an output that is to be switched off after
238 that interval of time has passed.
239 An interval defines the width of the pulse of the PWM output signal relative to the previous interval in the list.
240 The pulse width of a specifc output is the addition of all intervals up to and including the interval for that output.
241 The last entry in the list has an output of -1, which deniotes the end of the list.
242 After that final interval has passed, all outputs are switched ON and the PWM generator returns to the first entry in the list.
244 <svg src='pwm-algorithm.svg'/>
246 This allows the PWM genrator run run with a minimum of calculations.
247 The algorithm of the PWM generator is shown in the figure below:
249 <svg src='pwm-psd.svg'/>
251 The list of PWM signal intervals and associated outputs are store in shared memory.
252 The content of this shared memroy is written by <emph>lightcontrol</emph>.
253 The PWM generator reads the list continuously to generate the output signals.
258 <heading>lightcontrol</heading>
260 The program <emph>lightcontrol</emph> is used to control the levels of the red, green, blue and white LEDs.
261 The levels specified on the command line are converted into PWM signals and passed to the PWM generator.
262 The PWM generator uses a list of incremental intervals, as described in the previous section.
263 These intervals are calculated by <emph>lightcontrol</emph> and stored in the shared memory interface
264 for the PWM generator.
265 The algorithm is shown is the figure below:
267 <svg src='light_to_pwm.svg'/>
269 The following figure shows the algorithm to fade the lights:
271 <svg src='lightfade.svg'/>
273 <heading>Command line interface</heading>
275 Command line options specify the operation of the LEDs:
278 lightcontrol [-l] [-V] [-r red] [-g green] [-b blue] [-w white] [-f fadetime]
281 Not all levels need to be specified. If the desired level for a LED is not specified, it will not be changed.
282 For example if only the option "-r 50" is given,
283 the red LED will light at 50% but the green, blue and white levels will be unchanged.
286 Set the level of the red LED. The level is an integer number between 0 and 100, 0 meaning fully off and 100 meaning fully on.
288 <item tag="-g green">
289 Set the level of the green LED. The level is an integer number between 0 and 100, 0 meaning fully off and 100 meaning fully on.
292 Set the level of the blue LED. The level is an integer number between 0 and 100, 0 meaning fully off and 100 meaning fully on.
294 <item tag="-w white">
295 Set the level of the white LED. The level is an integer number between 0 and 100, 0 meaning fully off and 100 meaning fully on.
297 <item tag="-f fadetime">
298 Do not set the levels of the LEDs immediately but fade from the current levels to the desired levels
299 in <emph>fadetime</emph> seconds.
300 The default fade time is 0, which will immeditely change the light levels.
303 List the current light levels.
304 The current levels are printed to standard output on a single line of 4 numbers.
305 The numbers are the current levels in the order red, green, blue and white.
308 Print the version of the program and exit.
312 <remark>TODO:</remark> Option -p to set the PWM period, default 10000 microseconds.
316 <heading>Execution interface</heading>
318 Create a run file when fading lights to the desired level.
319 The run file holds the process id and the Tachyon name.
320 A fade can be interrupted by a signal. This allows another lightcontrol process to override a running fade.
321 The Tachyon name can be used to control the time base used by the fade process.
322 This is mainly used for test purpooses.
323 The run file is removed on exit.
329 <heading>Wakeup</heading>
332 The primary function of the wakeup process is to gradually increase the light at wakeup time in the morning.
333 Either by fading in the lights to a specified level or by (slightly) opening the curtains.
334 Controlling the curtains is the secondary function of wakeup.
335 This means fully opening the curtains in the morning and closing the curtains in the evening,
336 depending on the times of sunrise and sunset.
340 The wakeup times are specified like calendar events, possibly with a recurrence pattern and an end date.
341 Elements in a wakeup event are:
344 <item> Light parameters</item>
345 <item> Start time</item>
346 <item> Recurrence pattern</item>
347 <item> Number of recurrences</item>
348 <item> End time</item>
350 A recurrence pattern can be specified with a number of days, weeks or months as well as a set of weekdays.
351 A set of weekdays implies the recurrence will be weekly.