X10UTILS V3.00
A SET OF TOOLS FOR THE X10 CP290 HOME CONTROL COMPUTER INTERFACE








November 22, 1990


Thomas E. Salzmann















































PREFACE





X10UTILS is a set of utility programs for the X10 Powerhouse CP290 Computer
Interface. The intent of this package is to totally fill the need for decent
software to control the CP290. X10UTILS provides the capabilities of
event specification and download, direct commands, time maintenance, single
event download, and upload of all CP290 events. Migration from other
X10 software packages may be accomplished through the use of X10UPLD.
X10UPLD creates a nicely formatted file suitable for download to the
CP290 with X10DNLD. The file created by X10UPLD may be used as a basis
for your own customized event file.

The program used for event specification and download is X10DNLD. X10DNLD
provides many features which make the task of maintaining your X10 CP290
much easier. Some features of X10DNLD are:

o Event file creation with your favorite text editor.
o English language specification of events.
o Macro definitions which allow you to define your own constants and event
specification language.
o Conditional event processing based on time, day, date, or whatever string
constants or macros you care to base it on. IF and WHILE statements are
supported.
o Time arithmetic which allows you to add offsets to times.
o Random time generation.
o Sunrise and Sunset time calculation. Based on your latitude and
longitude coordinates, X10DNLD calculates these times for you.
o 'Include' file processing. This allows you to modularize your events
into different files.
o PRINT and INPUT statements for user interaction.
o Ability to send direct commands to the controller.
o Ability to 'append' events to the controller.

See the sections 'Usage of the Tools' and 'Event File Format' for more of
what X10UTILS is all about.

X10UTILS contains six programs, X10DIR, X10TIME, X10DNLD, X10UPLD, X10MON,
and X10EVENT. The programs are written in C. The source is far less than
perfect, but I'll be happy to provide the source files for an additional fee.

I hope these programs prove to be useful for you. Please let me know of any
bugs or suggestions you may have.

Good luck,
Tom Salzmann
[email protected]
prodigy: cgvs24a





Preface ii









CONTENTS





RELEASE HIGHLIGHTS 1
New function for v2.80 1
New function for v2.7x 1
New function for v2.61 3
New function for v2.56 (X10DNLD) 5
New function for v2.55 (X10DNLD) 5
New function for v2.50 through v2.53 (X10DNLD and X10TIME) 6
New function for v2.01 and v2.10 (all in X10DNLD) 8
How X10DNLD Handles Time Zones 9
New function for v1.5 9

USAGE OF THE TOOLS 11
X10DIR, Direct Command Utility 11
X10TIME, Set and Query Time 12
X10EVENT, Send a Single Event 13
X10UPLD, Receive All Events 14
X10DNLD, Send Events 15

EVENT FILE FORMAT 17
Event Specification Keywords 17
Interpreter Directives (X10DNLD only) 18
Exit Codes (ERRORLEVELs) set by ALL UTILITIES 20
Event Coding Guidelines 21

NOTES AND CHANGE HISTORY 26
Notes 26
Change History 26























Contents iii









RELEASE HIGHLIGHTS


VERSION 3.00 is the first external shareware release. Prior versions were
for beta test users only.

NEW FUNCTION FOR V2.80

o X10MON PROGRAM.

X10MON is a program which runs on a PC that is attached to a CP290
controller. Each time the controller executes an event, the event
information is displayed on the PC screen. An event may be a timer event
or an event caused by pressing one of the eight buttons on the CP290.
X10MON may be cancelled via Control-Break or by pressing any key.

I am taking suggestions for future releases of this program.

o CONTROL-BREAK HANDLING IN ALL PROGRAMS.

It is now totally acceptable to hit the control-break key without fear
that your system will suddenly die. The new control break handler in all
six program handles the situation and lets the user decide whether to
abort. If the user wants to abort, the program terminates cleanly,
closing the COM port before exiting.


NEW FUNCTION FOR V2.7X

o EVENT_LIMIT KEYWORD.

Specifying an event limit instructs X10DNLD to stop sending events when
it reaches the limit. The CP290 limit is 128 events, but EVENT_LIMIT may
be any number from 1 to 128. For example:

EVENT_LIMIT 100 ; Only send up to 100 events to the CP290

o FILL KEYWORD.

Specifying 'fill' at the end of an event specification line will cause
that event to be repeated at equal time increments throughout the day(s)
specified. The number of times the event is executed is equal to the
number of available event locations in the CP290 at the time the 'fill'
line is executed. For example:

; A lamp we ALWAYS have on, but blink to show us the CP290 is
; ok.
house c unit 1 off 12:00 on 12:00 normal everyday fill

o APPEND MODE FOR X10DNLD.

X10DNLD can now be run in append mode by specifying '-a' on the command
line. Append mode will take the contents of an event file and ADD the
events to the CP290 storage without wiping out the events which are


Release Highlights 1









already stored there. This is useful for adding 'today' and 'tomorrow'
mode events without reprogramming the box. For example:

>X10DNLD -a xtraevnt.X10

Append mode locates available event addresses and uses them until event
storage is exhausted. A 'BASE x' statement in the event file is ignored
in Append mode.

This feature makes the X10EVENT program less useful since X10EVENT does
not take advantage of many of X10DNLD's features such as sun times,
RANDOM, if-then-else, etc. Previously, X10EVENT was the only way to add
events to an already programmed CP290.

o X10UPLD ENHANCEMENTS.

- X10UPLD now reports its version number, X10TIME, and X10DAY in the
event file it creates. This information is put in a comment block at
the top of the file.
- A new quiet option (-q) has been added.


o BUG FIXES.

- X10DNLD will no longer report an error for bad time calculations that
exist within the false leg of an IF statement.

o BEEP STATEMENT.

BEEP n will beep the speaker at frequency n. This is useful for alerting
the user while processing an event file.

beep 440; Sounds a tone at 440 hz.

o ERRORLEVEL 4.

X10DNLD exits with ERRORLEVEL 4 if any syntax errors or invalid time
calculations are found in the event file(s).

o NEW RANDOM TIME GENERATOR.

A new random time keyword 'RANDOM' may now be used to generate random
offsets or random times. The purpose of this is to supply a means of
replacing the SECURITY mode of the X10 CP290 for those folks who prefer
to do frequent event downloads to their controller. RANDOM should
generate a different value each time it is used. RANDOM must be followed
by a valid time constant. The time generated by RANDOM is between 0 and
the number of hours and minutes specified. Some examples:

define r1 random 4:00 ; Generate a time between 0 and 4 hours.
define lights_on sunset + random 1:30 ;
unit 3 on random 2:00 + 1:00 everyday ; Turn computer on between 1 am
; and 3 am everyday.

NOTE: RANDOM may be used anywhere a time value may be used.


Release Highlights 2









o SUPPORT FOR MORE COM PORTS

By setting the DOS environment variable 'X10PORT', you may now specify
other ports besides COM1 and COM2. To do this, however, you must know
the base hardware address of the port (for example, COM2 is 2f8) and the
IRQ line used (COM2 is 3). This is supported in such a manner due to the
non-standard nature of COM ports other than COM1 and COM2. The following
example specifies COM2, although it is overkill to do this since COM2 can
be specified by setting X10COM to 2 or by the '-c2' command line switch.

C> SET X10PORT=2f8,3

o SELECTABLE HANDLING OF TIME CALCULATIONS.

This feature was added due to a few requests concerning the fact that
X10DNLD did time calculations even if specified in a DEFINE statement.
By using a new set of directives (eval_off and eval_on) you may select to
turn off the evaluation of time calculations in DEFINE statements. The
default is 'eval_on' to maintain compatibility with the prior release.
This feature allows you to do the following:

eval_off
define pm +1200
define am
house a unit 1 on 8:00 pm normal weekdays
house a unit 1 off 7:00 am normal weekdays
eval_on ; This is not necessary for most users. An example
; of where it would be necessary is as follows:
define sunrise 06:00 + 01:00
print sunrise ; This would print '07:00'
; but, look at this:
eval_off
define sunrise 06:00 + 01:00
print sunrise ; THIS will print '06:00 + 01:00'


NEW FUNCTION FOR V2.61

o IMPROVED ERROR HANDLING IN ALL PROGRAMS.

- All programs now pass ERRORLEVELs back to DOS consistent with the
table in this document (See Exit Codes set by all Utilities).

- The longest communication timeout should now be 15 seconds.

- X10EVENT should no longer hang when talking to a com port not
connected to the CP290.

o WHILE STATEMENT. X10DNLD now supports WHILE ... ENDWHILE blocks which
may be nested within each other or within an IF block. For example:






Release Highlights 3









print "Enter a day of the week : "
input day
while day !== (sun mon tue wed thu fri sat)
print "\nInvalid day,",DAY,", try again : "
input day
endwhile

o ENHANCED COMPARISON OPERATORS.

- EXACTLY equal comparisons. Using '==' and '!==', you may now compare
strings for exact equality. This is in addition to the 'fuzzy'
comparisons that are also supported. In a fuzzy comparison, strings
are considered equal based on strings of length equal to the shorter
of the two being compared. In an exact comparison, the two strings
must be identical. See the WHILE example above. == and !== operate
on sets in the same fashion as = and !=.

- < and > expanded to operate on sets. For example:

define fall 09 10 11
if dosdate < fall ; This will test if the DOS month is less than
; 09, 10, AND 11
*do pre-fall things.
endif

- Enhanced 'fuzzy' comparisons. You may choose to ignore this somewhat
bizarre feature. The default is for things to work the way they
always have. Currently, a fuzzy comparison means that two strings
are compared up to the length of the shorter string. If you specify
FUZZY n, however, comparisons are done up to n characters in the two
strings with the shorter string padded with blanks if necessary.
FUZZY 0 resets the fuzzy behavior to the default. In the following
example, SUN or SUNDAY is valid, while in the example above (the
WHILE example) only SUN was valid. The main difference being the use
of an exact equality comparison above and the use of a fuzzy (set to
3) equality comparison below (!== vs. !=). Note that a default
(fuzzy 0) comparison would have considered 's' equal to 'sun' or
'sat'.

print "Enter a day of the week : "
input day
fuzzy 3; Look at only the first 3 characters.
while day != (sun mon tue wed thu fri sat)
print "\nInvalid day,",DAY,", try again : "
input day
endwhile
fuzzy 0

Let me stress that you may choose to ignore this feature if you don't
care to mess with it. It is an attempt to gloss over one big hole in
X10DNLD, the inability to do SUBstringing.





Release Highlights 4









NEW FUNCTION FOR V2.56 (X10DNLD)

o DIRECT COMMANDS. You may now specify direct commands within your event
file(s). Direct commands and timer events may be freely mixed in a file
or you may create a file with only direct commands. If your file has
only direct commands, the event storage in the controller is not altered.
Event storage is only changed when events are specified. A direct
command is specified by using the mode 'NOW'. This is what a direct
command line looks like. Note that I specify a time of 00:00 on the
line. This is done to satisfy the parser who has no idea of the mode as
the line is being parsed.

house a unit 1 on 000 now ; Turn it on now.
define off_now off 000 now ; shorthand macro
house a unit 1 off_now

o -P SWITCH. Specifying '-p' on the X10DNLD command line allows you to
pass a value to a macro called 'DOSPARM'. This is handy for passing a
value from DOS for use in conditional event processing without altering
your event file(s). For example:

x10dnld -p parm_value_from_dos myevents.X10

o @ SUPPORT. Like a DOS batch file, placing @ at the beginning of any line
in your event file causes it NOT to be echoed if running in debug mode.
For example:

@debug_off
@print "\n"

o NOT EQUAL SUPPORT. You may now compare for not equal in an 'if'
statement. For example:

if x10day != mon wed fri
;events for sun, tue, thu, and sat
endif


NEW FUNCTION FOR V2.55 (X10DNLD)

o -Q SWITCH. Specifying '-q' on the X10DNLD command line causes X10DNLD to
run in a quiet mode. In quiet mode, event progress information (the
little dot that runs across the screen) is not displayed. This is
valuable if your event file(s) display their own progress via print
statements.

o PRINT STATEMENT. The X10DNLD language now supports a print statement.
You may print a mixture of quoted text and previously defined macros and
constants. The characters '\n' within the quoted text cause a newline to
be generated. For example:






Release Highlights 5









define say print "\n\n"
define water_heat_on house c unit 1 normal everyday on
define x10rc 10
print "\nTo turn on the water heater: ",water_heat_on,"\n"
print "Sunrise is at ",sunrise,".\nSunset is at ",sunset,".\n"
say "Event processing complete, exiting with code: ",x10rc
say
exit x10rc

o INPUT STATEMENT. The input statement defines a macro from user input.
In the following example (used on a PC without real time clock) DOSDATE
is set to whatever is typed in by the user.

print "\nEnter today's date in the form MM/DD/YY : "
input DOSDATE

o CHARACTER MASKING IN 'IF' COMPARISONS. Using '?' you may mask characters
not pertinent or extraneous to your comparison. For example, the
following tests if a date falls on the 15th of the month:

if dosdate = ??/15/??
* do events for the 15th
endif


NEW FUNCTION FOR V2.50 THROUGH V2.53 (X10DNLD AND X10TIME)

o DEBUG SWITCH. Given that X10DNLD is running with the debug (-d) switch,
you may now use debug_on and debug_off to control whether the debug
statements are displayed.

o REDEFINITION OF MACROS. You may now redefine a previously defined macro.
For example, define sunrise sunrise+DST

o CLEANUP OF X10DNLD ERRORLEVELS. See the section on 'Event File Format'
for a table explaining the ERRORLEVELs returned to DOS.

o NEW CONSTANTS. X10DNLD now pre-defines the following constants for you:

- DOSTIME - This is the current time known to DOS. The format is
HH:MM.
- DOSDAY - Current day known to DOS. The format is one of Sun, Mon,
Tue, Wed, Thu, Fri, or Sat.
- DOSDATE - Current DOS date. The format is MM/DD/YY. A future
version may support national date formats.
- X10TIME - Current time known to the X10 CP290 computer interface.
The format is HH:MM.
- X10DAY - Current day known to the X10 Powerhouse. The format is the
same as DOSDAY above.
- SUNSET and SUNRISE are defined as before once both latitude and
longitude have been specified. The format of these is HH:MM.

o CONDITIONAL PROCESSING. Using 'if', 'else', and 'endif', you may now
conditionally control what events in your event file are sent to the X10


Release Highlights 6









Powerhouse CP290 interface. The operators '>', '<', and '=' may be used
in comparisons. '=' means 'are these two strings equal?' or 'does this
string exist in the following set?' depending upon how you use it. All
strings must not contain blanks, commas, parenthesis or other X10DNLD
string delimiters. Here are a few examples:

if DOSDAY = tue wed thu fri * Test for set membership
*
* any valid X10DNLD events or directives go here
*
else
*
endif
if DOSDATE > 04/05 * Test for greater than April 5.
*
endif
if DOSTIME = 03:0 * Test equality with 3:00 thru 3:09
*
endif

o EXIT DIRECTIVE. You may now cause an early exit from your event file
based on certain conditions. The following example is used in a scenario
where the PC is turned on each morning at 3 am solely for the purpose of
downloading an event file. For this reason, X10DNLD is run out of
AUTOEXEC.BAT but processing will only occur when the system is booted at
3am. The 'EXIT 5' directive sets the DOS ERRORLEVEL to 5. The following
lines could be in a small file called myevent1.

if DOSTIME = 03:0
include myevents.X10; myevents.X10 is the 'main' event file
else
exit 5
endif

o In AUTOEXEC.BAT:

X10DNLD -c2 -G -d myevent1.X10 > myevent1.out
if errorlevel 5 goto over
x10dir -c2 b1 off ; Turn off the computer
:over

o SET DOS TIME FROM POWERHOUSE TIME. This function can be thought of as
the opposite of the -s and -S switches. '-g' and '-G' may be specified
on the X10DNLD and X10TIME command lines. '-g' simply sets the DOS time
from the CP290 time. '-G' does the same but waits for a change of minute
to guarantee synchronization on seconds. For example, X10TIME -c2 -g










Release Highlights 7









NEW FUNCTION FOR V2.01 AND V2.10 (ALL IN X10DNLD)

o MACRO DEFINITION CAPABILITY. Using the 'define' keyword, you may now
redefine any or all of the X10DNLD keywords. In addition, 'define' is
extremely useful for 'symbolic times'. For example, a single define at
the beginning of your event file can save you lots of editing when times
may change. ie, define dinner 18:00 This statement allows you to later
do something like: unit 1 on (dinner+1:00) off (dinner + 200)

Other macros can just save typing, such as:

define water_heater_on house c unit 1 normal everyday on
define water_heater_off house c unit 1 normal everyday off
define wakeup 5:30
define showertime 3:00

allows you to do this:

water_heater_on wakeup
water_heater_off wakeup + showertime

o FILE INCLUSION IN MAIN EVENT FILE. Using the 'include' keyword, you may
include a file in your main event file or from a file included by your
event file (includes may be nested). This is especially nice for placing
all 'defines' in one file and then simply including them. For example,
include mydefine.X10 This may also be useful for keeping all events
for a particular house in one file.

o TIME ARITHMETIC. As I have shown above, you may now add and subtract
times from either a macro which has been defined as a time or from a
constant time. sunrise+1:00 1:00+2:00+3:00 sunset-0:15 Note that
times must have a minimum of three numbers. That is, ':15' is NOT valid,
but '0:15' or '015' IS valid.

o AUTOMATIC SUNRISE AND SUNSET CALCULATION. To have X10DNLD define time
for sunrise and sunset, all you must do is specify your latitude and
longitude in your event file. Once X10DNLD sees that you have defined
both latitude and longitude, it will define sunset and sunrise based on
latitude, longitude, and the date obtained from DOS. For example:

latitude 35
longitude 78 ;these are for Raleigh

The preceding two statements will cause the definition of sunrise and
sunset. Note that X10DNLD only accepts DEGREES. More precise
specification using minutes and seconds is not supported.

Once defined, the keywords 'sunrise' and 'sunset' can be used anywhere in
your event file where a time would have been expected. For example:

unit 1 on(sunset) off(sunrise) normal everyday; flood lights

For shorthand, you may also do the following:



Release Highlights 8









define ss sunset
define sr sunrise

One restriction worth noting is that X10DNLD knows nothing about Daylight
savings time. For this reason, manual intervention in the event file
will be required after setting the Powerhouse clock to DST or back to
standard. The following technique will make this less painful:

define DST 0:00 ; change this to 1:00 during DST.
latitude 35 longitude 78 ; cause definition of sun times.
define ss sunset + DST ; shorthand defn of sunset
define sr sunrise+ DST ; shorthand defn of sunrise

Now use only ss and sr for your sunrise and sunset events. For example:

unit 1 on(ss+0:15) off(sr-0:15) normal everyday; porch lamp


HOW X10DNLD HANDLES TIME ZONES

Some background information concerning how time zones are handled needs to be
explained. The USA is divided into 4 zones centered at longitudes of 75, 90,
105, and 120 degrees. Time zone breaks are made at 69, 84, 99, and 114
degrees. For example, Augusta Maine (44,69) is in the same time zone as
Flint, Michigan (43,83). The zone breaks are wrong in many cases (cities
near the zone boundary). This is because the USA generally draws time zone
lines on political (not geographical) boundaries.

An example 'problem area' is Lexington, Kentucky at (38,84). Since longitude
84 is in the Central time zone, Lexington users need to adjust for this. One
way is to specify latitude of 38 and longitude of 83. The times will be
slightly off. The following approximates a correction to the problem:

define DST 0:00 ;Daylight savings time offset
latitude 38 ;Lexington, KY. This is correct.
longitude 83 ;Lexington, KY. This is one degree off.
define sr sunrise + DST + 0:05 ; 0:05 adjusts for the one degree.
define ss sunset + DST + 0:05 ; ditto

Latitudes and longitudes may be found in the World Almanac.


NEW FUNCTION FOR V1.5

o All programs give short help when invoked with a question mark (?).

o Support of a 'rep' keyword in the event file. 'Rep' on any line causes
the event(s) for that line to be repeated once, one minute after the
original event(s).

Example: unit(4) on(300) normal everyday REP





Release Highlights 9









o Support of a 'base' keyword in the event file. This keyword, if
specified, must come before the first event line in the event file. This
keyword overrides the '-b' switch on the X10DNLD command line.

BASE H *set the base housecode (code for PH switches) to H

o All programs now support a '-c' command line switch to specify the COM
port. The X10COM environment variable is still supported, but '-c' will
override it. COM1 remains the default.

X10DNLD -c2 myevent.X10

o X10TIME and X10DNLD now support '-s' and '-S'. These switches tell the
programs to send the current DOS time and day to the Powerhouse. The
only difference with '-S' (capital S) is that the programs will wait to
synchronize the time at zero seconds.

X10TIME -s

o X10DNLD now has an optional test mode. The '-n' switch (N for No
download) tells X10DNLD to read the event file but to not send any data
to the Powerhouse. This is useful for syntax checking the event file.
For extensive debugging, this may be used with the '-d' switch.

X10DNLD -n -d myevent.X10

o New program! X10UPLD. This program takes as a parameter a file name.
X10UPLD will read the events from the X10 Powerhouse memory and create an
event file suitable for download with X10DNLD. This is essentially the
reverse of X10DNLD. BE CAREFUL - If you give a file that already exists,
it will be destroyed. X10UPLD is ideal for migrating from the original
X10 software or for creating a neatly formatted event file.

X10UPLD -c2 X10DUMP.X10

o New program! X10EVENT. X10EVENT downloads a single event from the
command line to the Powerhouse. The event specified may contain any
keywords compatible with X10DNLD except for 'base'. The purpose of this
program is to add an event to the Powerhouse memory without destroying or
replacing the events that are already there. X10EVENT is particularly
useful for 'today' and 'tomorrow' mode events.

X10EVENT -c2 house a unit 4 on 1300 off 1500 today rep













Release Highlights 10









USAGE OF THE TOOLS





X10DIR, DIRECT COMMAND UTILITY

X10DIR is a command invoked from the DOS command line for the purpose of
sending direct commands to various X10 modules throughout a home. X10DIR was
the first of the X10 utilities. For this reason, X10DIR does not use the
same convention as the other programs for specifying housecodes and modules.
The syntax is, however, quite simple.

The format of the command is:

X10DIR <-C COMPORT> <-W> HOUSEUNIT COMMAND

-W Tells X10DIR not to wait for the command to be echoed from
the X10 PH after command execution. If -w is NOT specified,
X10DIR will wait for this echo. Waiting takes longer, but
allows multiple X10DIR commands in a BAT file without
worrying about timing problems.

-C COMPORT Tells X10DIR what COM port to use. This overrides the X10COM
environment variable.

HOUSEUNIT The house and unit code for the particular module, eg A1, B5,
etc. If only the house code is specified, all modules with
the specified house code will execute the given command, eg
X10DIR A ON turns on all A modules.

COMMAND ON, OFF, FADE, DIM, or UP

LEVEL Only for the DIM and UP commands, an integer from 0 thru 15.
Any greater number will result in (number mod 16) being used.
DIM uses this as the amount of dimness. UP uses this as the
amount to brighten a previously dimmed light. UP will simply
turn on a light that is off (not dimmed).

? OR NOTHING Help

NOTE: FADE and UP are undocumented 'features' of the Powerhouse.













Usage of the Tools 11









X10TIME, SET AND QUERY TIME

X10TIME is a command invoked from the DOS command line for the purpose of
querying and optionally setting the time and day in your Powerhouse. With no
options, X10TIME acts much like the DOS TIME command.

The format of the command is:

X10TIME <-C COMPORT> <-g|G> <-s|S>

-C COMPORT Tells X10TIME what COM port to use. This overrides the
X10COM environment variable.

-g Set the DOS time from the Powerhouse.

-G Same as '-g' but synchronizes at zero seconds.

-s Sends the current DOS time and day to the Powerhouse.

-S Same as '-s' but synchronizes at zero seconds.

NOTHING Causes X10TIME to query the user for time and day.

? Gives a short help message.
































Usage of the Tools 12









X10EVENT, SEND A SINGLE EVENT

X10EVENT is a command invoked from the DOS command line for the purpose of
sending one event specification to the Powerhouse. Unlike X10DNLD, this
program does not send a base housecode and does not erase previously stored
events. X10EVENT adds the specified event(s) to the X10 Powerhouse event
memory.

X10EVENT pauses when first invoked. During this pause, the program is
uploading all event data from the Powerhouse for the purpose of locating
empty event addresses. Once it knows where to put the events, X10EVENT then
decodes the event data you have specified and transmits the event(s) to the
Powerhouse memory.

An ideal use of X10EVENT is to specify 'one shot' events (those with mode of
TODAY or TOMORROW) without disrupting the status of the events currently in
the Powerhouse memory.

The format of the command is:

X10EVENT <-C COMPORT> EVENTDATA

-C COMPORT Tells X10EVENT what COM port to use. This overrides the
X10COM environment variable.

EVENTDATA Specify event(s) in the same format used in an X10DNLD event
file.

? OR NOTHING Help




























Usage of the Tools 13









X10UPLD, RECEIVE ALL EVENTS

X10UPLD is a command invoked from the DOS command line for the purpose of
receiving event data from the X10 Powerhouse. The event data is stored in
the specified file in a format compatible with X10DNLD.

X10UPLD is ideal for migrating from other X10 software. It is also extremely
useful for making sure your Powerhouse has in its memory the correct set of
events.

The format of the command is:

X10UPLD <-C COMPORT> <-Q> FILENAME

-Q Run Quietly.

-C COMPORT Tells X10UPLD what COM port to use. This overrides the
X10COM environment variable.

FILENAME File to be created by this program. This file will be in a
format suitable for download by X10DNLD. If 'filename'
already exists, it will be destroyed and replaced with the
event data.

? OR NOTHING Help
































Usage of the Tools 14









X10DNLD, SEND EVENTS

X10DNLD is a command invoked from the DOS command line for the purpose of
downloading events from an event specification file. This program is uses a
syntax which incorporates keyword based specification, macro capabilities,
'include file' processing, Sunrise/Sunset calculation, and conditional event
processing based on time, day, sunrise, sunset, and date constants.

X10DNLD <-A> <-B> <-C> <-D> <-g|G> <-N> <-P> <-Q> <-s|S> <-T> EVENTFILENAME

-A Tells X10DNLD to run in 'APPEND' mode.

-B BASE Allows you to optionally give X10DNLD a base house code to
download to the Powerhouse. If this is not specified, the
house code of A will be used. Specifying 'base x' in the
event file will override this switch.

-C COMPORT Tells X10DNLD what COM port to use. This overrides the
X10COM environment variable.

-D The -d option will cause X10DNLD to create output on the
screen consisting of debug and trace type of information.
This is useful if you suspect something may not be working
properly. One way to use this is to redirect the program's
output to a file, eg, x10dnld -d filename > logfile. It is
often handy to use -d with -n (see below). Do not use -t if
redirecting output because you will not see the time or day.

-g Set the DOS time from the Powerhouse.

-G Same as '-g' but synchronizes at zero seconds.

-N X10DNLD will process the event file but not send any data to
the Powerhouse. This is useful for syntax checking your
event file.

-P Specify a string value for the macro DOSPARM. If not
specified, DOSPARM will not be defined. (eg, X10dnld -p
my_value)

-Q Run in 'quiet' mode. X10DNLD will not display event progress
information (the dot that runs across the screen).

-s Sends the current DOS time and day to the Powerhouse before
sending any event data.

-S Same as '-s' but synchronizes at zero seconds.

-T This option will cause X10DNLD to allow you to view and
optionally modify the time and day.

EVENTFILENAME The name of the file containing the event information to be
sent to the Powerhouse. See the section below on event file
format.


Usage of the Tools 15









? OR NOTHING Help























































Usage of the Tools 16









EVENT FILE FORMAT





The format of the event file is somewhat free form. The only real
restriction is that unlike C or Pascal, each 'statement' must be on only one
line. A statement may not span or continue on to the next line. The
following are keywords which may be freely mixed on a line. The only
requirement is that those keywords which require operands must be followed by
operands which make sense. Such keywords include: on, off, dim, fade, up,
level, house, and base. You may use parenthesis, commas, brackets, or braces
as you see fit to give the language more expression. Times must be military
and a colon is optional. The only defaults are for NORMAL mode, HOUSE A,
BASE A, and LEVEL 0. Everything else should be specified. See the files
SAMPLE.X10, X10EVENT.X10, X10DEFIN.X10, X10WATER.X10, and CALCDST.X10 for
examples of event files.


EVENT SPECIFICATION KEYWORDS

ON Specify an 'on' time. on 300, on(3:00), on (0300), on 0300

OFF Specify an 'off' time. off 14:30, off(14:30), off 1430

DIM Specify a 'dim' time. dim(15:25), etc.

FADE Specify a 'fade' time. fade 17:21, etc.

UP Specify an 'up' time. up(100), etc.

LEVEL Set the level for all dims and ups on the current line.
Level 12, level(12), etc. For dim, 0 is bright, 15 is very
dim. For up, 0 is 'up a tiny bit', 15 is 'up alot'.

UNIT OR UNITS Specify the units for this line's events. units 1, units (1
2 3 12), units(1,4,3,9,2), etc.

ALLUNITS Tells X10DNLD to set the event(s) of this line for all units.

HOUSE Specify house code. May be on a line by itself. eg, House A
This house code will be used for all events until changed.

BASE Specify base house code. This must occur in the event file
before any event specifications. eg, Base H

REP 'rep' anywhere on a line will cause the event(s) for that
line to happen twice, separated by one minute. A side effect
of 'rep' is that multiple 'rep's on a line will in fact cause
the event(s) to be repeated once for each rep.

Use only one of the following modes per line (default is NORMAL):



Event File Format 17









NOW Do the event(s) now. This generates no timer events, but
causes an immediate direct command for each event on the
line.

SECURITY 'security' mode

NORMAL 'normal' mode

TODAY Do the event(s) today only. This is a mode.

TOMORROW Do the event(s) tomorrow only. This is also a mode.

The following day specifications may be mixed in any way:

WEEKDAYS Do the event(s) only on weekdays.

EVERYDAY Do the event(s) every day.

MON, TUE, WED, THU, FRI, SAT, SUN Days on which to do the events.

NOTE: FADE and UP are undocumented 'features' of the Powerhouse.


INTERPRETER DIRECTIVES (X10DNLD ONLY)

DEFINE Define a 'macro' to X10DNLD. The macro may contain any valid
combination of X10DNLD keywords and time arithmetic. For
example:

define wakeup 6:00
define sunrise sunrise + DST
define sunshine sunrise + 1:15
define garage house d unit(7 5 6)

INCLUDE Include another event file for processing. An example is to
put all defines in a separate file and include that file at
the beginning of your event file. INCLUDE files may include
other files and may be anywhere in the event file. For
example:

include mydefine.X10 * these are my define statements
include barnpowr.X10 * this is my barn event file

LATITUDE, LONGITUDE Specify the latitude and longitude for your city. Once
both latitude and longitude are defined, the keywords
'sunset' and 'sunrise' are available for use where ever a
time is expected. For example:

latitude 35 ; coordinates for Raleigh NC.
longitude 78

IF, ELSE, ENDIF Using >, <, =, and != you may control processing based on
conditions at download time. Comparisons are performed on
strings of length equal to the length of the shorter string


Event File Format 18









being compared. For example, 03: is considered equal to
03:42. This is useful for using only the portion of the
following constants which may be of interest to you. Note,
however, that since these are string and NOT integer
comparisons, 3:12 is NOT equal to 03:12. Be careful here.
You may do 'character masking' using '?'. With character
masking, for example, ??/15/?? is equal to DOSDATE on the
15th of any month. X10DNLD generates the following constants
for you. You may, of course, define any number of personal
constants using the 'define' directive.

o DOSTIME. The current time known by DOS. eg 04:03
o DOSDAY, today's day according to DOS. eg Sat
o DOSDATE, today's date according to DOS. eg 03/04/89
o X10TIME, the current time in the CP290. eg 04:05
o X10DAY, today's day according to the CP290. eg Sun
o SUNRISE, generated as a result of specifying latitude and
longitude. eg 06:02
o SUNSET, generated as a result of specifying latitude and
longitude. eg 17:42

You may test for 'set membership' using '='. For
example:

if x10day = mon wed fri
* events specific to these x10 days.
endif
if dosdate != 04 05 06 07
* events for when NOT in these months
endif
if dosdate = 03/21 07/08 11/15
* events for these dates (birthdays)
endif
if dosdate = ??/14 ??/15 ??/16
* events for the middle days of the months
endif


DEBUG_OFF Given that X10DNLD has been invoked with the debug (-d)
switch, debug_off may be used in your event file to suspend
the output of debug statements. You may also place an at
sign (@) in front of any line to suppress the echo of that
line when in debug mode. For example:

@debug_off

DEBUG_ON This is used to resume the output of debug statements which
was suspended by debug_off.

PRINT This is a print statement for displaying quoted strings and
previously defined constants or macros. Quoted strings and
macros must be separated by a delimiter such as a comma. Use
'\n' to specify a newline. There is no implied newline at
the end of the statement. For example:


Event File Format 19









print sunrise," is sunrise today, ",dosdate,"\n"
print "DOSDAY = ",dosday,"\nX10DAY = ",X10DAY,"\n"

INPUT This is an input statement for defining macros from user
input. In this example, 'kids_bedtime' is set to whatever
the user enters.

print "Enter the kids' bedtime: "
input kids_bedtime

RANDOM random hh:mm tells X10DNLD to generate a random time between
00:00 and the time specified.

unit(4) on(sunset + 01:00 + random(00:45)) everyday

BEEP beep n tells X10DNLD to beep the speaker at frequency n

beep 44 beep 440 beep 4400 ; three different tones.

EXIT EXIT n tells X10DNLD to cease processing and return to DOS
with return code (ERRORLEVEL) of n.


EXIT CODES (ERRORLEVELS) SET BY ALL UTILITIES

Upon certain conditions, a program will terminate and pass back to DOS a
value that may be tested using the DOS ERRORLEVEL value. The following are
the ERRORLEVELs set by X10UTILS:

0 Successful completion or execution of a user specified 'EXIT
0' statement in the event file.

1 Invalid command line parameter(s) or execution of 'EXIT 1'.

2 Failure to open the event file as specified on the command
line or execution of 'EXIT 2'.

3 Execution of 'EXIT 3' or general communications problems
including:

o Failure to download the base housecode to the Powerhouse.
o Failure to read the Powerhouse time.
o Failure to set the Powerhouse time.

4 Syntax and/or invalid time calculations found in the event
file(s) or execution of 'EXIT 4'.

N X10DNLD has executed a statement of the form 'EXIT n' as
specified by the user in the event file.







Event File Format 20









EVENT CODING GUIDELINES

There are some general guidelines worth noting when coding your event file.

o The event specification for a single event group must be on one line in
the file. The following, for example, is valid:

house a
unit(3,4,5) on(3:00) dim(4:00) level(10) off(5:00) normal everyday

The line above generates three events.

The following is NOT valid.

house a
unit(3,4,5)
on(3:00) dim(4:00) level(10) off(5:00) normal everyday

So, the specification of units, mode, day(s) and up to 16 commands (on,
off, dim, fade) must be grouped together on one line. The order of the
keywords is not important. HOUSE and BASE may be on a line by themselves
or on a line with the event data.

o Each interpreter directive should be on a line by itself. This is true
of all directives but latitude and longitude. When in doubt, however, it
is best to put things on separate lines.

o Time constants should be expressed as HH:MM. For example, 01:00 is 1
o'clock. It is OK to use 100 for 1 o'clock, but X10DNLD uses the HH:MM
format for the following generated constants:

- sunrise
- sunset
- dostime
- x10time
- Any result of time arithmetic, for example: (100+001) generates the
constant 01:01.

If you plan on doing any time comparisons, make sure you use the five
character time format.

o Date constants should be expressed as MM/DD/YY. For example, 01/01/89.
The reasoning is the same as above. X10DNLD creates the constant DOSDATE
for you in the MM/DD/YY format.

o Comparisons are done as string comparisons with a length equal to the
shorter of the two strings being compared. You may mask characters with
a '?'. Comparisons with a null string are considered false, with the
exception of 'not equal' which is considered true.

o Comparison for set membership or NON-membership is achieved with the same
'=' and '!=' symbols that are used for general equality and inequality.
Blanks or commas delimit the set members. For example:



Event File Format 21









if dosday != tue,wed,thu ; If today is not in the set (tue,wed,thu)























































Event File Format 22









* Some sample lines from an X10DNLD event file:
*--------------------------------------------------------------------
; Comments start with a splat or a semicolon. Blank lines are OK.
@debug off ; Turn off debug statements in debug mode.
;---------------------------------------------------------------------
; Find out if we have been invoked with a parm of 'AUTO'
;---------------------------------------------------------------------
if DOSPARM = AUTO ; Are we to run in AUTOboot mode?
; DOSPARM is set by the -p command line switch.
if X10TIME != 03:0 ; is it not 3am thru 3:09?
exit 5 ; dont process unless 3 am when in AUTO mode.
endif

endif
;---------------------------------------------------------------------
; Calculate Sunrise and Sunset, figuring for DST or EST
;---------------------------------------------------------------------
include calcdst.X10 ; Calculate the DST offset
latitude 44
longitude 69 ; we live in Augusta, Maine
print "Sunrise is ",sunrise,". Sunset is ",sunset,"\n"
define sunrise sunrise + DST
define sunset sunset + DST
if dst > 00:00
print "NOW, sunrise is ",sunrise," and sunset is ",sunset,"\n"
endif
;--------------------------------------------------------------------
; Macros for certain units in the house.
;--------------------------------------------------------------------

define water_heater_on house c unit 1 normal everyday on
define water_heater_off house c unit 1 normal everyday off
define hirate 6:00

base B * Set base housecode to B. This is the code used by the PH buttons

;--------------------------------------------------------------------
; Now, the general event specifications.
;--------------------------------------------------------------------

water_heater_on hirate - 2:00
water_heater_off hirate-0:05

house A ; Make sure we have the correct house code for events to follow

;--------------------------------------------------------------------
; The following line will set 2 events. Unit A1 on at 12pm, security
; mode on Monday thru Saturday. Unit A1 fades out at sunset, same
; days and mode.
;
; This event will be repeated in the Powerhouse due to the
; specification of the 'rep' keyword.

unit(1) on (12:00) fade(sunset) security weekdays,sat rep


Event File Format 23










; The same set of events could have read:
rep mon tue wed thu sat fri security on 1200 units 1 fade sunset
; or
units 1, on 1200, fade sunset, security, weekdays sat, rep

;--------------------------------------------------------------------
; the following 'if' compares the first two chars in DOSDATE to see if
; they are in the set (01,02,12), (03,04,05,06,07,08), or (09,10,11).
; Set comparisons work only for '='. When X10DNLD sees '=' followed by
; multiple strings, it 'knows' to simply determine if the constant exists
; as one of the strings in the set.

if dosdate = 01 02 12 * is this winter time?
include winter.X10
else if dosdate = 03 04 05 06 07 08
include spring.X10
else if dosdate = 09 10 11
print "Processing for Fall dates.\n"
include fall.X10
endif
endif
endif

if dosdate = 03/21/89
* do some special events for this day
endif

* -------------- OR, do the following ----------------

define winter 01 02 12
define spring 03 04 05 06 07 08
define fall 09 10 11
if dosdate = winter ; is this winter time?
include winter.X10
else if dosdate = spring
include spring.X10
else if dosdate = fall
include fall.X10
endif
endif
endif

; Now we'll do some direct commands
define on_now on 000 now ; Shorthand macros for direct commands.
define off_now off 000 now ; These can be put in X10DIR.X10 and
define dim_now dim 000 now ; then included by your event file
define fade_now fade 000 now

if DOSPARM != AUTO ; if running manually
if X10TIME > SUNSET ; is it 'dark' out?
house a unit 5 on_now ; Turn on the desk lamp for computing
endif
else ; Running automatically


Event File Format 24









house b unit 1 off_now ;Turn off the computer.
endif

* See the files *.X10 for more examples.
*-----------------------------------------------------------------------



















































Event File Format 25









NOTES AND CHANGE HISTORY





NOTES

1. The package is pkzipped. Use PKUNZIP to extract it.


2. There are now 3 ways to specify your COM port. This CAN be confusing, so
please forgive me for it. All of these methods are supported by all 5
programs.

a. Allow things to default. You'll get COM1 support.

C> X10TIME -s

b. Set X10COM to 2. This gives you COM2 support.

C> SET X10COM=2
C> X10TIME -s

c. Use the '-c2' command line switch. '-cn' will override whatever you
may have X10COM set to. 'n' must be 1 or 2.

C> X10TIME -c2 -s




























Notes and Change History 26