V1.7 -- August 15, 2001
CP290 Director is Macintosh software that
original X10 home automation computer controlled interface, model
number CP290. It completely replaces the Macintosh software that comes
with the CP290, and has unique features not found in other
Macintosh-based CP290 controllers.
CP290 Director is shareware.
can try it out for 30 days, but if you still use it thereafter, you
must register it. The price is very reasonable--$10. After 30 days,
CP290 Director will no longer communicate with your CP290 unless you
have registered it. Click here
for instructions on how to pay.
Once you have paid, you will receive a
code via email. You can enter this code into CP290 Director
as follows. Start CP290 Director, then select Register... from the Apple menu,
and enter your name and the code.
If you have purchased a previous release of
Director, then you may use this one at no additional charge (I will
send you a registration code upon request). If you want to
know what is new in this release, see the version
By using CP290 Director you agree
are responsible and liable for the results of such usage. If
you do not agree to accept this responsibility, don't use CP290
Director. The X10 system is not 100% reliable, so there can
be no assurance that a module will turn on, off, or dim as you have
specified. CP290 Director offers an improved
reliability feature, but even with that feature there can be
no assurance that the commanding of a module will work in all instances.
CP290 Director supports standard features of the
as well as features not supported by other CP290 software.
CP290 Director supports the standard CP290
exception of the questionably useful getting the clock stored
in the interface) including:
- Turning on and off modules immediately,
them on dimmed;
- Defining "turn on" and "turn off" events to be
the CP290 and executed by the CP290 even if the Macintosh is shut down.
Such events include:
- Turning a module on or off once at the
- Turning a module on or off once at the
- Turning a module on or off every week at
specified time and day(s) of the week;
- Turning a module on or off every week
within an hour
of the specified time and day(s) of the week;
- Displaying the events currently stored in the
- Setting the base house code of the CP290, which
house code it uses when its 8 on/off buttons are pressed;
- Setting the clock in the CP290 to the clock in
- Performing a self test function.
In addition to the above, the CP290 Director
- The ability to specify that an event is to
sunrise or sunset (plus or minus a specified time interval);
- The ability to specify a specific date on which
is to occur, and optionally the interval in days thereafter that the
event should be repeated;
- The ability to specify that the event should
on even days or on odd days.
The CP290 by itself does not support any of these
for events stored in the CP290 for future execution. However,
if you are willing to make sure that your Macintosh is booted
periodically (once a day is best), then these additional features
can be supported. CP290 Director supports these extended features
in the following manner.
CP290 Director allows you to store events using
in an file. You then arrange for the file to be opened (preferably)
daily. When the file is opened, CP290 Director analyzes the events
in the file to determine which ones should be executed today or
tomorrow by the CP290, and sends to appropriate "today"
and/or "tomorrow" events to the CP290. Thus, if you
willing to assure that your file of events gets opened daily,
you can take advantage of the above extended features. You can
assure that the event file is opened by placing it, or an alias
to it, in the "Startup Items" folder or the "Shutdown
Items" folder in your "System Folder".
As a concrete example of how CP290 Director
of the extended features, consider the following case. Assume
you have specified an event indicating that a particular module
should turn on at a particular time on 2 July 1998 and then every
3 days thereafter. You then store this event in a file, and put
an alias to the file in your Startup Items folder. Each time the
event file is opened, CP290 Director checks the current date to
determine whether any events stored in the file are scheduled
to be performed later that day or the next day. On 1 July 1998,
CP290 Director will determine that the event is to occur tomorrow
, and therefore store a "Tomorrow" event in the CP290.
Then, on 2 July 1998, CP290 Director would again check the current
date and time, and if the specified event is to occur later in
the day, then CP290 Director will send a "Today" event
to the CP290. CP290 Director will also store "Tomorrow"
events on July 4, 7, 10, ... and "Today" events on July
5, 8, 11, ... Note that in this particular case you would only
need to open your event file every 3 days...on the day before
the event is to occur (or on the same day the event is to occur
but earlier in the day).
As another concrete example, consider the case
that a light is to turn on every day at Sunset (see below
for how to specify this). When you specify sunset, the
day's sunset time is shown. However, what is saved when
you store the event in a file is an indication that this event
is to occur at sunset...not today's sunset time. Then, each
time the event file is opened, CP290 Director computes the current
sunset time and sends an event with that time to the CP290.
Thus, by specifying a single event as sunset, CP290 Director
will compute the proper sunset time in the future, for each day
that you open your event file.
The best way to take advantage of these extended
to open your event file daily.
X10 systems usually work reasonably reliably,
turning on or
off the selected module when the CP290 commands it. However,
noise or interference in your wiring can cut reliability whereby
a module is not turned on or off at the requested time. The best
solution to this problem, if acute, is to install noise filters.
However, you may find that CP290 Director solves the problem for
you. CP290 Director allows you to optionally specify (via the Preferences function)
that each "on"
event should be sent more than once to the module, and/or that
each "off" event should be sent more than once. Thus,
if the first command to turn off doesn't work, the second or third
one might. If you specify that an event should be sent more than
once, it will be sent the specified number of times (two to four)
at one minute intervals.
CP290 Director has help integrated into its user
It does not support or rely on balloon help, but supports help
that works in all MacOS versions. You can get help on almost every
menu item by holding down the option key while selecting the menu
item. If you do so, the menu item is not performed, but a help
screen explaining its function is displayed instead. Help is also
available for all mouse button clicks that have meaning within
CP290 Director. Thus, clicking on a check box or in a text field
with the option key depressed displays a help message.
Starting CP290 Director
Opening CP290 Director by double clicking its icon
it and typing command-o
the application and present the user interface. Its is very important
to note that opening an event file will cause CP290 Director
to send the events in the file to the CP290 and then quit,
rather than presenting the user interface. To edit the events
you have previously stored in an event file, you have two options.
First, you can open the event file while holding down the command
key until the user interface appears. Second you can open the
event file while the CP290 Director application is already running.
In this latter case, you can either open the event file using
the Open command in the File menu, or by opening the file via
the MacOS Finder with CP290 Director already running.
The Main Window
When presenting the user interface, CP290 Director
display the main window. The main window operates much like the
MacOS desktop or a folder window, displaying icons that represent
X10 modules to be controlled. Icons in the main window can be:
- moved by dragging them with the mouse button
(as with MacOS);
- selected by single-clicking them;
opened (allowing them to be edited) by double clicking them or with the
Open Selected Module command of the Module menu (command-o);
or deleted with the Delete Selected Module command of the Module menu (command-k).
Only one icon can be selected at a time. Clicking on the background
of the main window unselects the selected icon (if any).
of a new main window
is white. You can optionally specify a PICT file to be used as
the background of the main window. For example, you could draw
a floor plan for your house using a drawing program, save it is
a PICT file, then use it as the background for your module icons.
Each icon can then be dragged to the location of the module in
or around the house. You can specify the background file with
the Select Background...
the File menu. Once you
a background, you can later clear it (to white) using the Clear Background command of the File
menu. The figure below shows an example main window with a house
diagram and a few modules.
Modules that the icons in the main window
house codes, and module IDs associated with them. You can optionally
display module names below the icons by selecting the Display
Module Names option in the Module
menu. Similarly, you can optionally display module house codes
and IDs above the icons by selecting the Display
House Code/IDs option in the Module
You can duplicate an existing module from the main
selecting its icon and selecting the Duplicate
Selected Icon command of the Module
You can create new modules from the main window
with the New Module
command of the Module
menu (command-n). This
create a new module and open the Edit
dialog box to allow you to specify the icon, name, house code,
ID, type of module (light or appliance) and events for the module.
From the main window, you can command the CP290 to
module on or off by control-clicking the module icon. Each icon
has on "off" appearance and an "on" appearance.
When you initially create a module its icon displays the "off"
appearance. If you then control-click the icon, the module will
be turned on, and the icon will display its "on" appearance.
If you control-click an icon with its "on" appearance
displayed, the CP290 will turn off the module and its "off"
appearance will be displayed. Note that since the CP290 cannot
report the state (on or off) of the modules it controls, the "on"
appearance merely means that the CP290 has turned the module on.
If you manually turn off the module via the keys on the CP290
or via a wall switch module, the icon will continue to display
the "on" appearance.
There are two special types of modules for which
acts slightly different than described above. If you select "All
Lights" as the ID of a module, the module (representing all
light modules on the specified house code) can only be turned
on. Thus, control-clicking such an icon always sends a turn on
command. Conversely, if you select "All Modules" as
the ID of a module, the module (representing all modules on the
specified house code) can only be turned off. Thus, control-clicking
such an icon always sends a turn off command. You can select
"All Lights" only for light modules.
In the main window, inactive modules have an X
An inactive module is one with no events defined, or with only
events that have expired. A non-repeating event set to occur in
the past is expired. Such modules are considered inactive because
they don't cause any events to be sent to the CP290. They can
be made active again by editing them. Inactive modules can be
selected, edited, duplicated, moved, or controlled just as any
The Edit Module dialog appears as the result of a New
Module command (command-n)
or an Open Selected Module
(command-o). This dialog
to specify or change:
- the module's icon;
- the module's name (which defaults to "Untitled"
for a new
- the module's house code (which defaults to "A"
for a new
- the module's ID (which defaults to "1" for a
- the module's type ("Light" or "Appliance"); and
- up to nine cycles, each containing an "on"
event and an
To change the module's icon, click on the default icon displayed
in the upper left corner of the Edit Module dialog to display
the Select Icon
dialog. All other aspects
of the module are edited from within the Edit
You can change the name by typing up to a 31
in the Name field. You can change the house code via the popup
menu to a value from "A" to "P". You can change
the ID via a popup menu to a value from "1" to "16"
or to "All Lights" or "All Modules".
You cannot select "All Lights" for a module designated
as type "Appliance".
an icon for the module,
the type of the module is set to "Light" or "Appliance"
based on the icon you chose. If you want to to later change
the type, you can do so via the popup menu. The brightness
selections shown in the dialog are not shown for appliance modules.
The on/off events for each module are grouped into
each containing one "on" event and one "off"
event. To specify an "on" event, click to turn on the
Turn On At... checkbox. The result will be a display of various
menus, checkboxes, and text fields that you can use to specify
the time, date, and brightness level of the "on" event.
Similarly, you can specify an "off" event by clicking
to turn on the Turn Off At... checkbox. The result will be a display
of various menus, checkboxes, and text fields that you can use
to specify the time and date of the "off" event. Note
that an "off" event does not have a brightness.
To specify an event you must specify the time of
and a date for the event. For "on" events you can also
specify a brightness level via the popup menu.
To specify the time you can either enter the
the text field, or you can turn on a checkbox to indicate that
you want the event to occur at sunset or sunrise. If you choose
sunset or sunrise, you can additionally specify an amount of time
before or after sunset or sunrise that you want the event to
The sunset and sunrise times are computed based on the location
set in the MacOS Map control panel and on the date and time specified
in the appropriate control panel.
The main time text field is actually made up of
for the hour, the minute, and AM or PM. Entering the time in this
field works like entering time into MacOS control panels:
- Clicking in any subfield selects that subfield
- Tabbing moves the selection to the next
subfield, or to
the first subfield if the entire field is selected (as it would be the
first time you tab into it).
- Within each subfield, you can't type anything
yield an invalid value. Invalid characters are ignored.
- The hour subfield can range from 1 to 12. If
contains "1" and you type "2", the hour becomes "12". However, if the
subfield contains "2" and you type "1", the hour becomes "1", because
"21" would be an invalid hour.
- The minute subfield can range from 00 to 59. If
subfield contains "03" and you type "4", then the minute becomes "34".
If the subfield contains "07" and you type "4", then the minute becomes
"04", because "74" would not be a valid minute. If the subfield
contains "34" and you type "5", the minute becomes "05" because "345"
would be too large.
- Typing "a" in the AM/PM field sets the field to
whereas typing "p" sets the field to "PM".
Entering an offset from the sunset or sunrise time
You can enter only "+" or "-" in the first
subfield, with the hour and minute subfields operating as above.
To specify the date, you have your choice--via the
below the line--of four options:
if you want the event to occur weekly on the days you specify. As shown
in the "on" event in the figure above, you can change the value of the
checkboxes for each day of the week. You can also optionally check the
Security checkbox to indicate that the event should occur randomly
within an hour of the time you specified.
if you want to specify a specific date for the event to occur, with an
option repeat interval. As shown in the "off" event in the figure
above, you can enter a date into the text field, click on the Today
button to fill today's date into the date field, click on the Tomorrow
button to fill tomorrow's date into the date field, and turn on the
Repeat every XXX days checkbox to specify a repeat interval for the
event. The date field operates similarly to the time field (above),
with the major difference being that the up and down arrow keys are
used to change the year. The repeat internal text field is a three
digit number that ranges from 1 to 999, and operates similar to the
time and date numeric subfields. Thus, to change it from its default of
"1" to "2", you must type "002". Typing just "2" will change the
interval to "12".
- Specify Even
to schedule the event for days 2, 4, 6, ..., 30 of each month.
- Specify Odd
to schedule the event for days 1, 3, 5, ..., 31 of each month.
These latter two options may be useful if you are
your sprinkler system while your town has water conservation in
You can specify up to nine cycles of on/off
use the Cycle popup menu to choose the cycle you wish to
There is no requirement that you use cycles in order; you can
use any cycles you wish. You can copy and paste complete
cycles using the Copy Cycle
(command-c) and Paste
of the Edit menu.
Turning The Module On and Off Now
From the Edit Module dialog box you can also
control of the module via the Now section of the dialog, turning
it on with the On button, off with the Off button, and specifying
a brightness when turning on the module. As with control clicking
the icon in the main window, turning a module on via the Edit
Module dialog changes the Icon in the dialog to its on state,
and turning it off changes the icon to its off state.
OK and Cancel Buttons
The OK and Cancel buttons have their usual meaning
Module dialog, except that Cancel does not undo the effect of
any direct module control you have performed...it only cancels
any changes you made to the icon, name, house code, ID, or events.
The Select Icon dialog appears when you click on
the icon in
the upper left-hand corner of the Edit
Module dialog. This dialog shows the "off"
state of each available icon. Click on any icon to select
it. The selected icon has a box around it. While
mouse button is down over the icon, it will change to is "on"
state. The icon you select will appear in the Edit Module dialog
and in the Main Window if you choose OK in the Edit Module
The icon you select also selects the type of the module to be
either "Light" or "Appliance". You can
change this type selection; see above.
If you select the Preferences...
command under the Edit
menu, the Preferences
dialog allows you to specify, via the
popup menus, whether you want "on" events to be sent
to the CP290 more than once and whether you want "off"
events to be sent more than once. If you specify that an
event should be sent more than once, it will be sent the specified
number of times (two to four) at one minute intervals.
This dialog also allows you to specify how the
turn on light modules. Modules designated as type "Light"
have brightness specifications, and can be dimmed (if they really
are light modules!). When a light module is turned on with
"Full" brightness, the default behavior of CP290 Director
is to use the CP290 "Turn On" command to turn on the
module. However, you can specify that light modules turned
on with "Full" brightness should be turned on with the
CP290 "Dim 100%" command instead. The advantage
of specifying this preference is that light modules can be changed
from being on with brightness less than 100% to being fully on
without turning them off first. The disadvantages of
this option are 1) Dim 100% is not quite as bright as ON (though
most people will not notice any difference); and 2) if you specify
this preference, then any appliance modules designated as type
"Light" cannot be turned on, because they don't support
the "Dim 100%" command. If you correctly
specify the type of all of your modules, then you may prefer turning
this preference on.
Each main window actually represents an event
you start CP290 Director (without opening an event file), a new,
empty Main Window is created. The complete contents
of a Main Window can be saved in an event file. The File menu contains the usual
manipulate event files: New File, Open File, Close, Save, Save As..., Revert To Saved.
It also contains
the Select Background...
and Clear Background
commands, as mentioned above.
Remember that opening an event file from MacOS
Director is not running causes the events in the file to be
sent to the CP290.
menu contains the follow
commands that allow you to manipulate the CP290 controller:
- Send Events
sends the events specified in the topmost main window to the
CP290. This is the same command that is performed
automatically when you open an event file from MacOS while CP290
Director is not running.
CP290 reads the events currently stored in the CP290 and
displays them in a window, sorted by increasing time. To
understand how to interpret the information you find in this window,
see Displaying CP290 Events
- Save Events
To File... saves the events currently displayed (see Displaying CP290 Events
below) in the file you specify.
CP290 prints the events currently displayed (see Displaying CP290 Events
- Set Base
allows you, via its submenu, to set the house code that the CP290 will
use when its 8 on/off buttons are pressed. Note: Setting the
base house code clears all events from the CP290.
- Set CP290
sets the clock internal to the CP290 to the time and day of week
specified by your Macintosh's clock.
- Self Test
initiates a self test program in the CP290. The test will
erase all events stored in the CP290.
menu also contains three
other commands that allow you to specify how the CP290 is connected
to your Macintosh and how CP290 Director should communicate with
it. Use Communications
you to specify whether or not CP290 Director should use the Macintosh
Communications Toolbox and its Serial Tool to communicate with
the CP290. Using the Communications Toolbox is the preferred
(though not the default) option if you have the Communications
Toolbox and the Serial Tool installed on your
If you have trouble getting CP290 Director to communicate with
your CP290, try with Use
both on and off. Select Use
Port if your CP290 is connected to the modem port, or to
the single (combined) port on a Powerbook. This is the
selection. Select Use
if your CP290 is connected to the printer port. If you are
using a Macintosh with only one port and are using the Communication
Toolbox, then either port specification will use the combined
port. When the communications toolbox is enabled, your system
is scanned for all available serial devices, and you are allowed
to choose any of them to communicate with the CP290. The
device names will appear in the CP290
menu after Use Communications Toolbox
is turned on.
window shows an example display of events.
All events are displayed in five fields. The first field
is "Today", "Tomorrow", or the days of the
week that the event is to occur. The second field, which
is visible in the above sample only for module A-1, is an "S"
to indicate that "Security" was specified for the event,
or blank otherwise. The third field is the time of the
The fourth field is "ON", "OFF", or the brightness
of a light module. The brightness is shown as "FULL"
for full brightness, and fractions for the other 7 brightness
levels (7/8, 3/4, 5/8, 1/2, 3/8, 1/4, 1/8). The fifth field
is the modules to which the event applies.
In this example, modules A-2 and A-3 are
and hence have a brightness level shown. Modules A-1 and A-4 are
appliance modules, and hence show as "ON".
To understand how this display relates to the
you need to understand how CP290 Director stores events in the
CP290. CP290 Director stores as few events as possible in
the CP290 to implement the events you have specified. Thus,
you specify that multiple modules with the same house code should
go off at the same time on the same days, then only one event,
specifying multiple modules, will be sent to the CP290.
You can see this in the next to the last line above, where modules
A-1 and A-2 are specified to go off at 11:01. Also, remember
that CP290 Director stores only events that occur on the same
day every week, or that occur today or tomorrow. Thus, if
you have specified an event to occur at some date beyond tomorrow,
don't expect it to show up in the CP290 until the day before the
event (assuming that events are sent to the CP290 hat day).
In this example, note that the Preferences
were set to send events multiple times, and to use full brightness
for turning on light modules.
CP290 Director runs on a black and white or color
with 4MB or greater and MacOS System 7 or greater. I have
tested it with a Performa 550 and several PowerPC machines, including
a Powerbook 2400. It may work on older models, but I have
not tested it. I run it regularly under MacOS 7.5.3 and
8.6 and, others run it successfully under MacOS 9. If you
find that it does or does not work properly on some particular
Macintosh model or MacOS version, please contact John Woodward.
1.7 - Added news icons.
1.6 - Fixed a bug with the "ALL LIGHTS ON" and
selections for module number:
- These number settings could not be saved in a
though they appeared in the pull-down menu. They now can.
- The "turn on now" and "turn off now" feature
disabled for module numbers of "ALL LIGHTS ON" or "ALL". I
cannot get the CP290 to accept these commands for immediate
execution. This feature is disabled in the module dialog, and
is also disabled if you control-click on a module icon.
1.5 - Various feature additions requested by
- While events are being sent to the CP290, a
indicator is now displayed.
- While events are being displayed from the
progress indicator is now displayed.
- Once you have displayed the events from the
CP290 in a
window, you can then save them in a file or print them.
1.4 - Various feature additions, feature
- To change the "AM" or "PM" designation for
can now use either upper or lower case letters. Before only
lower case worked.
- The sunrise and sunset times are now
they are used. Before they were calculated only upon
startup. This is useful for people who leave CP290 Director
running for long periods of time.
- A bug causing housecodes I, J, K, and L not
to work was
- The error message produced when CP290
communicate with the CP290 now has additional information in it useful
in debugging problems.
1.3 - When the communications toolbox is enabled,
is scanned for all available serial devices, and you are allowed
to choose any of them to communicate with the CP290.
only the Modem, Printer, or Combined ports could be used.
1.2 - Various feature additions, feature
- The 4 Release 1.1 brightness levels (100%,
and 25%) have been replaced with 8 brightness levels: Full, 7/8, 3/4,
5/8, 1/2, 3/8, 14, and 1/8. Also, a bug whereby brightness
levels 25% and 75% were swapped has been fixed.
- Modules can now (optionally) be designated as
"Light" or "Appliance". All modules in Release 1.1 files
opened by this release have all modules defaulted to "Light".
Newly created or edited modules have a default type based on the icon
chosen, but the type can be changed in the Module dialog. This ability
to designate the type of the module is provided in conjunction with a
change in the way light modules are turned on when Full (or 100%)
brightness is specified. In Release 1.1, all modules with a
brightness of 100% specified were turned on with the CP290 Turn On
command. However because of a bug in the CP290, if a light
module was already on with a brightness of less than 100%, then CP290
Director had to turn off the module before being able to turn it on
fully. This behavior was objectionable and has been changed
in this release as follows:
- Modules designated as "Appliance" have no
specifications in the Module dialog, are ALWAYS turned on
with the CP290 Turn On command and cannot be dimmed.
- Modules designated as type "Light" have
specifications, and can be dimmed (if they really are light
modules!). When a light module is turned on with "Full"
brightness, the default behavior of CP290 Director is to use the CP290
"Turn On" command to turn on the module. However, a new
preference has been added in the Preferences dialog that allows you to
specify that light modules turned on with "Full" brightness should be
turned on with the CP290 "Dim 100%" command instead. The
advantage of specifying this preference is that light modules can be
changed from being on with brightness less than 100% to being fully on
without turning them off first. The disadvantages of
specifying this option are 1) Dim 100% is not quite as bright as ON
(though most people will not notice any difference); and 2) if you
specify this preference, then any appliance modules designated as type
"Light" cannot be turned on, because they don't support the "Dim 100%"
command. It's your choice.
- The Select Icon dialog now starts with the
- Minor improvements in the Help function were
- An obscure bug in displaying events from the
- Support for the Communications Toolbox and
Tool was added. The option to turn on this support is under
the "CP290" menu. Using this option may make your connection
to the CP290 more robust.
1.1 - First release. Added "Display
CP290" command and fixed some bugs.
1.0 - Beta version, not released.
How to Pay
CP290 Director is shareware.
You can try
it out for
30 days, but if you still use it thereafter, you must register
it. The price is very reasonable--$10. After 30 days, CP290 Director
will no longer communicate with your CP290 unless you have registered
You can pay by clicking here.
Once you have paid, you will receive a
via email. You can enter this code into CP290 Director as
follows. Start CP290 Director, then select Register...
from the Apple menu, and enter your name and the code.
I would like to acknowledge David Baldauf for his
suggestions for features, and his testing of CP290 Director.
� 1998-2001 John Woodward. All rights reserved.
You may distribute CP290
unmodified via any media, as long as you keep it together with