X10SCHED(5)

NAME
x10sched - file layout of x10sched.conf for the X10 CM11A serial interface

DESCRIPTION
heyu supports sending schedules to your CM11A interface. The x10sched file allows you to specify when you want X10 commands to be sent to X10 modules throughout your home. It also allows you to translate some X10 codes to other codes. More on that below.

The X10 CM11A connects to a computer with an RS232 interface. It can store about 128 events; each event can turn on, turn off, or dim up to sixteen X10 modules . The CM11A box has a battery backed clock which the computer can read. The data is also battery backed.

There are three important concepts used in the x10sched file. They are timers, triggers and macros. They all work together, in fact, the timers and triggers execute macros.

The TIMER determines the date and time that a macro will be executed. Once a minute the CM11A looks at it's internal table (frequently referred to as the EEPROM) to see if it's time to do anything. Timers can be restricted to certain days of the week or ranges of dates, or both.

The TRIGGER represents real time actions. When the CM11A sees a powerline signal it compares the command with its table of triggers (also known as "macro initiators") and executes the appropriate macro. Triggers can be used to cause many actions when one remote control button is pushed.

The MACRO consists of a label, an optional delay and a list of commands. Each macro can have up to 16 commands. The delay can be from 0 to 240 minutes. Macro labels can be significant. They can remind you of what it is supposed to do or it can remind you what triggers it. The label turn_c5_on_now leaves nothing to be imagined.

The heyu program is currently set for a maximum of 127 macros, timers and triggers.

As of version 1.28, heyu will load events into the CM11A. I have established that there is no command that will dump the contents of the CM11A to the serial port. This makes it impossible to alter discrete events or macros unless the entire table is known. This means that we can't set the macros using another program (Activehome, for instance) and then add a new macro from heyu.

The timers and macros are stored in a file. The default is $HOME/.x10sched.conf. If that file is not accessible, the program will try /etc/x10sched.conf. You can over-ride the defaults by putting a fully qualified path in the environmental variable X10SCHED.

The macro load function will not work without the x10sched format file.

Comments and blank lines are allowed in the file to make it more readable. White space is normally ignored.

FILE FORMAT
Refer to the sample file (sched.conf.sample) that came with the source code to help in understanding this section.

comment
    A line that begins with a pound sign (#) is a comment. The whole line is ignored. Pound signs that are not at the start of the line do not represent comments.

blank
    Blank lines are skipped over.

timer
    The timer line consists of 7 items. They are: the literal string timer, a day of week mask, the start and end date range, the on time, the off time, the on macro and the off macro.
    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 time 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 instance, to activate a timer for Monday, Thursday and Saturday, you'd use the following string: .m..t.s
    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 start-end range is a pair of dates separated by a hyphen '-'. The first date represents when to start. The second represents when to stop. The dates are in mm/dd format (month/day, two characters each). The range is inclusive. A single date can be specified by using the same values for the start and stop dates.
    You would use 01/01-12/31 to indicate a timer that should be used daily.
    The on and off 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. it just doesn't look right to me :-)
    The on macro and off macro will be executed when their respective time is reached. Note that these are really unrelated timers and that the on macro is not restricted to turning things on and that the off macro does not have to affect the same X10 modules as the on macro. The macros mentioned in the timer must be defined somewhere in the file. The schedule load will abort if a macro is missing or mis-typed.

trigger
    The trigger line consists of only 4 items. They are: the literal string trigger, the trigger unit, the command and the macro.
    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. An alias from the config file may be used.
    The command will be either the word on or the word off. The CM11 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.

macro
    The macro line consists of 4 items. They are: the literal string macro, the label, the delay and one or more commands.
    The label is plain text of up to 31 characters. It must be contiguous, and must be of printable characters. The label is used by the timers and triggers to find the correct macro.
    Heyu will report the macro names and memory locations as it loads. These memory locations can be used when the monitor command output shows something like: "macro executed at eeprom address 996".
    The delay can be from 0 to 240 minutes long. It is represented by a simple cardinal number; no fractions, signs or decimals.
    The Commands can be one of several types; on, off, dim or bright. The on and off have one argument, that being the unit(s) in question. The units 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
    The commands can be strung together by separating them with a semi-colon ';'. This allows one macro to affect several devices. Consider the commands needed to turn on the TV (d1) turn off the stereo (d3) and dim the 4 lights in the living room by half( c1, c2, c3 and c4 dim 11). This command string would do it.
    on d1;off d3;dim c1-4 11.

EXAMPLES

In this timer, the macro c5on will be executed once a day at 2:58 PM. The macro c5off will execute at 2:59 PM.
The timer is active every day of the week from 2/1 through 12/12.
timer smtwtfs 02/01-12/12 14:58 14:59 c5on c5off
The next one only runs on Dec 11 but only if it falls on a Friday.
timer .....f. 12/11-12/11 23:34 23:35 d6off d6off
This trigger runs macro c5off when 'c1 off' is received. The net effect would be that the device with the code c1 will be turned off AND whatever the macro c5off will be done too.
trigger c1 off c5off
E4 is the dusk sensor (ms13a) outside. It turns on the living room lamps (via the livinroom_on macro), but is does not turn them off. I use a timer to do that long before midnight. If I waited for the ms13a they'd turn off at dawn even if I'm reading my paper then.
trigger e4 on livinroom_on
This next macro is labeled c5off. It waits 5 minutes, then turns off d6 and d7 and turns on e2
macro c5off 5 off d6,7;on e2 And this macro includes dimming. macro c5on 0 on d7; bright d7 22

ENVIRONMENT
X10CONFIG - Points to a fully qualified file name of your configuration file. See x10config(5) for more information on it's makeup.
X10SCHED - Points to a fully qualified file name of your schedule file (timers, and macros).

FILES
 .x10config - X10 unit description file
 .x10sched.conf - CM11A schedule information for timers and macros.
 /var/lock/LCK..heyu.mon - lock file for monitor process
 /var/tmp/heyu.out - fifo file for relay process
 /var/tmp/heyu.write - lock file for processes that write to the CM11A

BUGS
Macros should be able to handle commands like all lights out, all units off, etc. I haven't figured out what the impact on the CM11A is. The format for using those commands in a macro are not listed either.

AUTHORS
 Daniel B. Suthers (dbs@tanj.com).

SEE ALSO
ftp://www.x10-beta.com/ftp
http://heyu.tanj.com/heyu/ (faq)
http://heyu.tanj.com/heyu/protocol.txt
date(1), x10config(5), heyu(1), sched.conf.sample