Started on events and actions

[wakeup.git] / doc / design.xml

<?xml version="1.0"?>

<doc style="style.css">

  <book>
  <titlepage>
      <title>Bedroom light control</title>
   </titlepage>

    <chapter>
    <heading>Requirements</heading>
    <section>
    <heading>Top level requirements</heading>

<description>
  <item tag='REQ1.01'>
    Wake up lights fade in to specified color or slightly open curtains.
  </item>

  <item tag='REQ1.02'>
    wake up light starts at preset alarm time
  </item>

  <item tag='REQ1.03'>
    if outside light open curtain else fade to light level
  </item>

  <item tag='REQ1.04'>
    open curtain and fade out light at sunrise
  </item>

  <item tag='REQ1.05'>
    input from sunrise calculation and outside light sensor
  </item>

  <item tag='REQ1.06'>
    user interface for alarm times
  </item>

  <item tag='REQ1.07'>
    user interface for wake up light level, sleep light level, walk-in light level and fade times
  </item>

  <item tag='REQ1.08'>
    light on at walking in and no outside light
  </item>

  <item tag='REQ1.09'>
    lights fade to dark at sleep time
  </item>

  <item tag='REQ1.10'>
    lights fade on to specified color at movement in the night.
  </item>

  <item tag='REQ1.11'>
    curtains fully open if outside light and after alarm
  </item>

  <item tag='REQ1.12'>
    curtains close ar outside dark
  </item>

  <item tag='REQ1.13'>
    wake up times can be specified with a recurrance pattern
  </item>

  <item tag='REQ1.14'>
    recurrence patterns can be n days, weeks, months, years, weekday, weekendday
  </item>

  <item tag='REQ1.15'>
    wake up times can be optained from a online calander
  </item>
</description>

    </section>
    <section>
    <heading>Manual controls</heading>

<description>
  <item tag='REQ2.01'>
    manual controls override automatic controls
  </item>

  <item tag='REQ2.02'>
    manual control for light levels
  </item>

  <item tag='REQ2.03'>
    manual control for light on and off
  </item>

  <item tag='REQ2.04'>
    manual control for curtains open and close
  </item>

  <item tag='REQ2.05'>
    manual control from switches
  </item>

  <item tag='REQ2.06'>
    manual control from remote, online
  </item>
</description>

    </section>

    <section>
    <heading>Security requirements</heading>

<description>
  <item tag='REQ3.01'>
    Accessible by authorized persons and devices only
  </item>

  <item tag='REQ3.02'>
    All remote inputs are logged.
  </item>
</description>

    </section>
    <section>
    <heading>Testability requirements</heading>

<description>
  <item tag='REQ4.01'>
    Time is obtained from actual time or simulated time
  </item>

  <item tag='REQ4.02'>
    A simulated time base is used for testing
  </item>
</description>

    </section>
    </chapter>

    <chapter>
    <heading>Test scenarios</heading>

<itemize>
  <item>
    Wake up sequence when dark outside followed by sunrise
    <enumerate>
    <item>Set the date to dec 21, 23:00.</item>
    <item>Set a wakeup event at dec 22, 06:00</item>
    <item>Start wakeup daemon</item>
    <item>Verify lights on at 06:00</item>
    <item>Verify lights off at sunrise</item>
    </enumerate>
  </item>
  <item>
    wake up sequence when light outside
  </item>
  <item>
    wake up with a single alarm event
  </item>
  <item>
    wake up with recurring alarm events
  </item>
  <item>
    sleep time fade out
  </item>
  <item>
    walk in when dark
  </item>
  <item>
    walk in when light
  </item>
  <item>
    curtains close at dusk
  </item>
</itemize>

    </chapter>

    <chapter>
    <heading>Interfaces</heading>

<para>
    inputs:

<itemize>
  <item>
    alarm time for wake up
  </item>
  <item>
    calculated sunrise and sunset time
  </item>
  <item>
    outside light level
  </item>
  <item>
    manual switches
  </item>
  <item>
    remote control inputs
  </item>
  <item>
    pir sensor
  </item>
</itemize>
</para>

<para>
    outputs:

<itemize>
  <item>
    light levels
  </item>
  <item>
    curtain open and close
  </item>
</itemize>
</para>

    </chapter>

    <chapter>
    <heading>Modules</heading>
<para>
The dataflow diagram shows the high level design.
</para>
<svg src='dataflow.svg'/>
    <section>
    <heading>PWM generator</heading>
<para>
The PWM generator is controlled by a list of <emph>pwm</emph> structures:
<verbatim>

    struct pwm
    {
       int interval;
       int output;
    };

</verbatim>
Each structure holds an interval in microseconds and an output that is to be switched off after
that interval of time has passed.
An interval defines the width of the pulse of the PWM output signal relative to the previous interval in the list.
The pulse width of a specifc output is the addition of all intervals up to and including the interval for that output.
The last entry in the list has an output of -1, which deniotes the end of the list.
After that final interval has passed, all outputs are switched ON and the PWM generator returns to the first entry in the list.
</para>
<svg src='pwm-algorithm.svg'/>
<para>
This allows the PWM genrator run run with a minimum of calculations.
The algorithm of the PWM generator is shown in the figure below:
</para>
<svg src='pwm-psd.svg'/>
<para>
The list of PWM signal intervals and associated outputs are store in shared memory.
The content of this shared memroy is written by <emph>lightcontrol</emph>.
The PWM generator reads the list continuously to generate the output signals.
</para>
    </section>

    <section>
    <heading>lightcontrol</heading>
<para>
The program <emph>lightcontrol</emph> is used to control the levels of the red, green, blue and white LEDs.
The levels specified on the command line are converted into PWM signals and passed to the PWM generator.
The PWM generator uses a list of incremental intervals, as described in the previous section.
These intervals are calculated by <emph>lightcontrol</emph> and stored in the shared memory interface
for the PWM generator.
The algorithm is shown is the figure below:
</para>
<svg src='light_to_pwm.svg'/>
<para>
The following figure shows the algorithm to fade the lights:
</para>
<svg src='lightfade.svg'/>
    <subsection>
    <heading>Command line interface</heading>
<para>
Command line options specify the operation of the LEDs:
<verbatim>

   lightcontrol [-l] [-V] [-r red] [-g green] [-b blue] [-w white] [-f fadetime]

</verbatim>
Not all levels need to be specified. If the desired level for a LED is not specified, it will not be changed.
For example if only the option "-r 50" is given,
the red LED will light at 50% but the green, blue and white levels will be unchanged.
<description>
  <item tag="-r red">
    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.
  </item>
  <item tag="-g green">
    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.
  </item>
  <item tag="-b blue">
    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.
  </item>
  <item tag="-w white">
    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.
  </item>
  <item tag="-f fadetime">
    Do not set the levels of the LEDs immediately but fade from the current levels to the desired levels
    in <emph>fadetime</emph> seconds.
    The default fade time is 0, which will immeditely change the light levels.
  </item>
  <item tag="-l">
    List the current light levels.
    The current levels are printed to standard output on a single line of 4 numbers.
    The numbers are the current levels in the order red, green, blue and white.
  </item>
  <item tag="-V">
    Print the version of the program and exit.
  </item>
</description>

<remark>TODO:</remark> Option -p to set the PWM period, default 10000 microseconds.
</para>
    </subsection>
    <subsection>
    <heading>Execution interface</heading>
<para>
Create a run file when fading lights to the desired level.
The run file holds the process id and the Tachyon name.
A fade can be interrupted by a signal. This allows another lightcontrol process to override a running fade.
The Tachyon name can be used to control the time base used by the fade process.
This is mainly used for test purpooses.
The run file is removed on exit.
</para>
    </subsection>

    </section>
    <section>
    <heading>Wakeup</heading>

<para>
The primary function of the wakeup process is to gradually increase the light at wakeup time in the morning.
Either by fading in the lights to a specified level or by (slightly) opening the curtains.
Controlling the curtains is the secondary function of wakeup.
This means fully opening the curtains in the morning and closing the curtains in the evening,
depending on the times of sunrise and sunset.
</para>

<para>
The wakeup times are specified like calendar events, possibly with a recurrence pattern and an end date.
Elements in an event are:
<itemize>
   <item> Label</item>
   <item> Action</item>
   <item> Start time</item>
   <item> Recurrence pattern</item>
   <item> Number of recurrences</item>
   <item> End time</item>
</itemize>
A recurrence pattern can be specified with a number of days, weeks or months as well as a set of weekdays.
A set of weekdays implies the recurrence will be weekly.
The action for an event can be a light sequence or a curtain control.
</para>

<para>
An event is read from an XML element or created dynamically, for example calculated from the time of sunrise.
From any event, the next occurance is calculated, which is an event that happens after a certain time.
When the next event does happen, meaning the time of the occurance is the current time, the sequence of actions is executed.
Each action can for example be a change in lights or the opening or closing of curtains.
Event methods:

FromXML
ToXML
add_recurrance
next_occurance
add_action
execute_actions
</para>
    </section>
    </chapter>

  </book>

</doc>