The day of week mask (DOW) is a 7 character field. Each position represents a day of the week when the timer should work. A timer that should execute every day is represented by the string "smtwtfs". To deactivate a timer for any chosen day of the week, substitute a period ´.´ for the appropriate letter.

For instance, to activate a timer for Monday, Thursday and Saturday, you´d use the following string: ".m..t.s" (without the quotes).

The DOW mask is combined with the date when the CM11A checks to see if it should execute a timer. Both date and DOW must match for the timer to execute.

The begin-end range is a pair of month and day dates separated by a hyphen ´-´ or by a colon ´:´. The first date represents when to begin, and the second represents when to end. The range is inclusive.

The order in which month and day appear in each date must agree with the order specified with config directive DATE_FORMAT (or its default), for example with the default ´DATE_FORMAT YMD´, the date range would be entered as mm/dd-mm/dd, whereas for ´DATE_FORMAT DMY´ it would be entered as dd/mm-dd/mm. The separator between month and day may any of the separators which can optionally be specified with DATE_FORMAT, namely ´/´, ´-´, or ´.´. It does not have to be the same one.

A single date can be specified by using the same values for the begin and end dates. Older versions of Heyu required that the begin date be less than or equal to the end date. Beginning with version 2.0, Heyu will interpret a begin date later than the end date as meaning the date range wraps around at the end of the year into the beginning of the year (including the current year).
Examples:
You would use 01/01-12/31 to indicate a timer that should be run daily.
The range 12/01-02/01 is equivalent to the two ranges 12/01-12/31 and 01/01-02/01
With DATE_FORMAT DMY, the above range could be specified as 01-12:01-02, 01.12-01.02, or 01/12-01/02

For a date range involving the last day of February, see the description of the FEB_KLUGE directive in x10config(5).

Beginning with Heyu version 2.0, the effective date range of an uploaded schedule can be configured to span years. A schedule uploaded at any time during the year can be configured to operate correctly for a period of from 1 to 366 days beginning on the upload date. So for example, a schedule uploaded on September 1st can be configured to run correctly and continually through September 1st (or 2nd) of the following year. For more information, see the descriptions for the MODE and PROGRAM_DAYS directives in the x10config(5) man file, in particular "HEYU" mode versus "COMPATIBLE" mode.

Regardless of the above directives, the user would normally program the schedule for the entire year. (Envision the schedule as being repeated for each year, past, present, and future.) When compiling for upload, Heyu automatically selects whatever parts of it are to be used in accordance with those directives and adjusts dates and times for Leap Years and Daylight Saving Time as required.

As a special case beginning with Heyu 2.0, the date range "mm/dd-mm/dd" may optionally be entirely replaced with the expression "expire-dd", where dd represents the range of dd+1 days ending on the last day of validity of the uploaded schedule. Thus the CM11A can be programmed to execute some macro as a reminder to the user that the schedule will shortly need to be reloaded. Note that in COMPATIBLE mode, reloading the schedule before Jan 1st will not accomplish anything, as the exact same schedule will be loaded.

The start and stop times are in hh:mm format (hour:minutes 24 hour clock) You don´t have to use two digits, 1:5 will work just fine for 5 minutes after 1 AM.

The start macro and stop macro will be executed when their respective time is reached. Note that these are really unrelated and independant timers, and that the start macro is not restricted to turning things on and that the stop macro does not have to control the same X10 modules as the start macro. Either the start or stop macro can be the macro named "null" which is a dummy macro - it´s never executed and thus does nothing.

The macros referenced in the timer must be defined somewhere in the file. The schedule upload will abort if a macro is missing or mis-typed. (A warning will be issued if a macro is not referenced by any timer or trigger.)

With versions of Heyu prior to 2.0, times for events had to be programmed separately for dates when Standard Time and Daylight Time were in effect. Beginning with version 2.0, the user programs times for all events in legal (i.e., wall clock) time, and Heyu makes the necessary internal adjustment for the changeovers from Daylight -> Standard and vice-versa. The CM11A clock is maintained on Standard Time year around, transparent to the user.

Also new with version 2.0 is the ability to directly specify times relative to Dawn and Dusk. (A separate program was supplied with earlier versions to do this.) Instead of the time expressed as "hh:mm", one can now use the format "dawn+mm" or "dawn-mm" or "dusk+mm" or "dusk-mm" (or just "dawn" or "dusk"). Heyu calculates the times of Dawn and/or Dusk and makes the substitution. The "mm" represents the number of minutes before or after Dawn/Dusk when the macro will be executed. "mm" can have any value, _except_ that the resulting time after resolving the times of Dawn/Dusk must fall within the range 00:00 to 23:59 or Heyu will quit with an error message.

Dawn and Dusk are defined by default to be synonymous with sunrise and sunset. However this definition may be _globally_ changed to one or another of the standard twilight times, or to a user specified Sun position, with the configuration file directive DAWNDUSK_DEF. See man page x10config(5).

When Heyu processes Dawn or Dusk related events, it subdivides the programmed date range into a number of unequal-length subintervals, each of which is assigned a constant time approximating the time of Dawn or Dusk over the subinterval. The number and lengths of these subintervals are chosen by an iterative procedure which minimizes the deviation from actual Dawn/Dusk times subject to the constraint of available EEPROM memory in the CM11A. (As a result, if Dawn and/or Dusk related event times are programmed, the amount of free EEPROM memory displayed will generally be pretty small. If more timers are added to the schedule they'll fit - within limits of course - but the deviation in the Dawn/Dusk times will be higher.)

The Dawn or Dusk "error" reported by Heyu is the difference in minutes between the maximum and minimum times of daily Dawn or Dusk over the above-mentioned subinterval. Whether this error in the constant time approximation on any particular day is plus or minus or mixed is determined by the DAWN_OPTION or DUSK_OPTION configuration directive.

Heyu requires that every day have a Dawn and a Dusk, which is not the case in polar latitudes when the sun may be above or below the horizon all day, or when Dawn or Dusk is shifted into the previous or following day.
To compensate, Heyu uses a ficticious Dawn and/or Dusk at 00:01 or 23:58 hours Standard Time (not necessarily repectively) as the situation dictates. So for example in polar mid-summer, Heyu will represent the day as occurring between 00:01 and 23:58, while in polar mid-winter, the night will be considered to occur between those times.

To activate the so-called "security" feature of the CM11A, simply append the letter ´S´ to the programmed start or stop time in question. "12:00s", "dawn+5s", "duskS" are valid examples of this. The time of the event will then vary each day by some random amount within +/- 30 minutes of the programmed time. Note that the CM11A itself actually applies a variation of between +0 and +60 minutes to the programmed time. Heyu subtracts 30 minutes from the programmed event time to get the +/- 30 minute variation.

Heyu has to use a few tricks with the security feature when clock times around midnight are programmed, in particular when the programmed time is between 22:59 and 01:30 (assuming Daylight Time is in effect at some time during the year in your locality), since the CM11A must be allowed to add a random time between 0 and 60 minutes at any time of the year without exceeding 23:59. To get around this, Heyu changes the programmed event time for the timer to 22:59 and creates an appropriately delayed macro.

But this solution has its own problem, namely that if a delayed macro does not execute until the following day, it will not be executed at all on the day the schedule is uploaded. To get around this, Heyu uses a non-delayed macro and creates a new one-day-only timer event with its own +/- 30 minute randomly generated variation around the user´s original programmed time.

In order to test the operation of a schedule without having to wait around all day, Heyu version 2.0 will acccept the construct "now" or "now+NN" (with NN in minutes) in place of a start time and/or stop time in a timer. It will then substitute the current system time rounded up to the next whole minute, with a minimum of 15 seconds allowed for uploading the schedule. NN must be >= zero, otherwise the only restriction is that the resolved value of "now+NN" must not exceed 23:59. The security feature may not be used with the "now+NN" construct. Note that the date range and DOW mask must include today if the macro is actually expected to be executed today. Example:
timer smtwtfs 01/01-12/31 now now+2 lights_on lights_off

Beginning with Heyu version 2.0, the reserved macro label "null" may be used as a "do-nothing" place holder in a timer, when neither of the timer concepts start or stop seem logically appropriate. (The null macro may be used liberally as required - it will take up no more space in the CM11A´s EEPROM memory than if the user manually rearranged timer start and stop events solely to have something to "fill in the blank".)

timer options
There are four timer options which can be used to restrict the execution of a timer only to days when the actual times of Dawn or Dusk during the year are less than (LT) or greater than (GT) the time specified with the option. The option keyword and time are appended to the end of the normal timer line.

DAWNLT hh:mm - Execute only on days when Dawn occurs before hh:mm
DAWNGT hh:mm - Execute only on days when Dawn occurs after hh:mm
DUSKLT hh:mm - Execute only on days when Dusk occurs before hh:mm
DUSKGT hh:mm - Execute only on days when Dusk occurs after hh:mm

where hh:mm is expressed as legal (i.e. wall-clock) time.

Example:
timer smtwtfs 01/01-12/31 dusk 21:00 light_on light_off DUSKLT 21:00

This would result in the light being turned ON at dusk, OFF at 9:00 PM, but only on days when Dusk occurs earlier than 9:00 PM. Thus in extreme latitudes when Dusk might occur later than 9:00 PM during the summer months, the situation is avoided where the light is turned ON at Dusk and remains ON all night and all the next day until 9:00 PM.

The timer options are not restricted to timers which involve Dawn or Dusk times. The above timer could just as well have been programmed as two separate timers:

timer smtwtfs 01/01-12/31 dusk 00:00 light_on null DUSKLT 21:00
timer smtwtfs 01/01-12/31 21:00 00:00 light_off null DUSKLT 21:00

The time argument for the option does not have to be the same as the execution time of the timer. In the above example it might seems silly to have the light come ON for only a few minutes on days when Dusk started to approach 9:00 PM, so one could use DUSKLT 20:50 to ignore the days when the light might otherwise be ON for less than 10 minutes.

More than one timer option can be used with a timer - all four in fact if deemed appropriate. Just string them together at the end of the timer line. The string ... DUSKGT 19:00 DUSKLT 21:00 would result in the timer being restricted to execute only on days when Dusk occurs between 7:00 PM and 9:00 PM.

Please note that the CM11A interface has no capability for conditional logic - Heyu merely compares the option time argument with the calculated Dawn or Dusk time for each day of the year and breaks up the date interval into multiple intervals.

The trigger unit is a combination of house code (a letter from a-p) and a unit number (from 1 to 16). An example is d12.

The command will be either the word on or the word off. The CM11A will not trigger on any other type of X10 signal.

The macro refers to a macro that will be executed. The macro must be defined somewhere in the file.

The macro line consists of 3 or 4 items. They are: the literal string macro, the label, an optional delay, and a semicolon-separated list of one or more commands or scenes.

The label is plain text of up to 32 characters which must be contiguous, and must be of printable characters. It must not begin with the characters ´+´, ´-´ or ´_´, and it must not contain the ´$´ character. The label is used by the timers and triggers to find the correct macro.

When Heyu uploads a schedule, it write the macro names and EEPROM memory locations in file "x10macroxref" in the Heyu base directory, i.e., the directory where the configuration file is located. This file is used by the Heyu monitor to translate macro memory location to readable macro names as they are executed, so should not be deleted.

The delay can be from 0 to 240 minutes long. It is represented by a simple cardinal number; no fractions, signs or decimals. However see the section "Problems with delayed macros" below.

The Commands can be of several types; on, off, dim or bright being the most commonly used. The on and off commands have one argument, that being the address of the modules to be controlled. The address can be in the format of house code (hc) followed immediately by the unit number or range of unit numbers. The following are valid: d1 d1,2,3,9 d1-4,6

A limited subset of configuration directives may appear in the schedule file when preceded by the word ´config´, and will override the values of those same directives in the configuration file (or their default values). This feature is intended for use if you upload schedules requiring different configurations on a frequent basis, so you don´t have to keep changing the configuration file every time. For most users however there´s less chance of confusion by relying only on the directives as specified in the configuration file.

The subset of directives includes only those which directly influence how Heyu processes the timers, triggers, and macros to create the uploaded EEPROM image, to wit: MODE, PROGRAM_DAYS, LATITUDE, LONGITUDE, COMBINE_EVENTS, COMPRESS_MACROS, DAWNDUSK_DEF, DAWN_OPTION, DUSK_OPTION, MIN_DAWN, MAX_DAWN, MIN_DUSK, MAX_DUSK, ASIF_DATE, ASIF_TIME, DATE_FORMAT, WRITE_CHECK_FILES, REPL_DELAYED_MACROS, FEB_KLUGE, RESOLVE_OVERLAP. See x10config(5) if necessary for an explanation of these directives. Heyu will quit with an error message if directives other than these are specified in the schedule file.

Configuration directive lines in the schedule file always apply to the schedule as a whole regardless of where they appear in the file. It´s good practise however to put them all at the beginning of the file so you won´t overlook them later on and get confused.

Example:
config program_days 90