|comment||As of version 2.0, anything on a line following a pound sign (#) is treated as a comment and is ignored by Heyu. Note that for versions of Heyu earlier than 2.0, a pound sign anywhere other than as the first character on a line was treated as a normal character and NOT treated as beginning a comment.|
|section||Any line beginning with the keyword section is totally ignored by Heyu, just as if it were a comment line. It is provided to enable user-defined breakpoints for external programs or scripts which might be devised by the user to reorganize a schedule file, and where use of ordinary comment lines for this purpose might be confusing.|
|blank||Blank lines are skipped over.|
The timer line consists of 7 required items. They are: the literal string
timer (which is not case-sensitive), a day of week mask, the begin
and end date range, the start time, the stop time,
the start macro and the stop macro. In addition to these, there are
several timer options which can be appended to the line.
The trigger line consists of only 4 items. They are: the literal string
trigger, the trigger unit, the command and the macro.
In addition to the on, off, dim, and bright commands, Heyu version 2 adds others which can be used for uploadable macros in schedules, including Extended commands for modules like the X-10 LM14A 2-way lamp module. Run 'heyu help' for a complete list of commands implemented in the current version of Heyu. All the native X10 commands _except_ the Preset command may be used for uploaded macros. (The command 'mpreset' implements the very limited support for Preset in uploaded macros provided by the CM11A firmware.)
Heyu version 2 includes built-in synonyms for many of the commonly used commands. Run 'heyu syn' to see these synonyms.
Heyu version 2 also includes the ability for users to define their own synonyms ("usersyns") and/or compound commands ("scenes") in the configuration file, and use them in macros.
X10 commands are generally transmitted over the power line in two "chunks", a series of address bytes, one for each unit, followed by one or more function bytes. Both the address byte and the function byte reference the housecode (except for the 'preset' command, which has a peculiar function byte format).
For some commands, the unit information contained in the address byte is superfluous and the address byte will normally be omitted. Examples of commands in this category include the "all" commands like 'lightson', and 'alloff', the 'hail' command, and any of the Extended commands (which include the unit code within the function structure).
No unit codes need be appended to the housecode for the "all" commands, e.g.,
are sufficient. If a unit is specified with the housecode, it will normally be ignored. However if for some reason it is desireable for the command to be issued along with an address byte, prefix the housecode with a '+' sign and add the unit string suffix, e.g.,
An address byte is not normally sent with the Extended Code commands like 'xpreset' even though the unit must be specified. But again, prefixing the Housecode|Units with a '+' sign will instruct Heyu to include an address byte in the transmission.
For the opposite effect, i.e. to suppress transmission of the address byte for any command, prefix the Housecode|Units with a '-' sign and omit the units. E.g.,
A few commands warrant additional description:
xfunc <T/F> HU <xx> - general extended command.
The 'xfunc' command will transmit any arbitrary extended function <T/F> and data byte <xx>, where both are assumed to be hexadecimal bytes (0-0xff).
Example: 0x31 is the function code for the extended preset command, and the following commands for setting the extended preset level for module c3 to level 26 (decimal) are equivalent:
xpreset c3 26
xfunc 31 c3 1a
The extended command code functions are described in X-10's document xtdcode.pdf (a replacement for the older XTC798.DOC) which is available for download from their website. The only extended code Types known to be applicable to existing modules are the Type 3 for extended code lighting and appliance modules and Type 0 for the Marmitek SW10 Shutter controller.
Macro commands can be strung together by separating them with a semicolon ';'. 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 macro command string would do it.
on d1; off d3; dim c1-4 11.
As of Heyu version 2, macros can include scenes defined in the user's configuration file as if they were standard Heyu commands. Macros can also reference aliases defined in the configuration file in place of the Housecode|Units parameter.
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, and then only if it falls on a Friday.
timer .....f. 12/11-12/11 23:34 23:35 d6off d6off
This timer sounds a chime (perhaps a Universal Module UM-506) every day at Noon, legal (wall clock) time, Monday through Friday, regardless of whether Standard or Daylight Time is in effect (Heyu ver 2.0 and later):
timer .mtwtf. 01/01-12/31 12:00 00:00 lunch_chime null
This one sounds a chime at 7 AM and 7 PM 3 days in a row before the expiration date and on the final date itself (a total of 4 days) to remind the user that the uploaded schedule will shortly become invalid and need to be reloaded. (Heyu ver 2.0 and later only):
timer smtwtfs expire-3 07:00 19:00 chime chime
The following two timers turn on an inside hall light 30 minutes before Dusk, dim it after 11 PM, and turn it off 15 minutes after Dawn (Heyu ver 2.0 and later):
timer smtwtfs 01/01-12/31 dusk-30 23:00 hall_on hall_dim
timer smtwtfs 01/01-12/31 dawn+15 00:00 hall_off null
The following timer operates decorative lighting between Dusk and 10 PM during the holiday season without quitting on Jan 1st during non-leap years (Heyu version 2.0 and later):
timer smtwtfs 12/15-01/02 dusk 22:00 xmas_on xmas_off
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 directs will be done too.
trigger c1 off c5off
In the following, E4 is a dusk sensor (MS13A) outside. It turns on the living room lamps (via the livinroom_on macro), but it 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; dim d7 8
Since the delay is optional, the above can also be written as:
macro c5on on d7; dim d7 8
If the Multiple Transmissions box is checked for a timer in X10's ActiveHome software, the timer is duplicated with the same macros but with the execution time set 1 minute later. This is simple enough to do manually (and with more flexibility) in the schedule file that no attempt has been made to automate this feature in Heyu.
If a new schedule is uploaded between the time a timer or trigger is activated and the time a delayed macro is executed, the macro will never be executed because pending delayed macros are purged when a schedule is loaded. This is the nature of the hardware and is unavoidable. It should never be necessary for the user to program a delayed macro for a timer, and if Heyu finds one it by default attempts to adjust to this situation by creating a non-delayed macro and increasing the time of the timer to compensate. To change Heyu's behavior, see the REPL_DELAYED_MACROS directive in x10config(5). (If the same macro is associated with a trigger, the original delayed macro is uploaded for the trigger in addition to the new macro for the timer.)
X10SCHED - Points to a fully qualified file name of your schedule file (timers, and macros).
Daniel B. Suthers (firstname.lastname@example.org)
Charles W. Sullivan (email@example.com)
date(1), x10config(5), heyu(1), x10.sched.sample