CP290 Director

CP290 Director  V1.7 -- August 15, 2001 by John Woodward

Download

CP290 Director is Macintosh software that controls the 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. 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 it.  Click here for instructions on how to pay. Once you have paid, you will receive a registration 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 CP290 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 history. By using CP290 Director you agree that you 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.

Table of Contents Features Operation Macintosh Requirements Version History How To Pay

CP290 Director Features

CP290 Director supports standard features of the CP290 interface, as well as features not supported by other CP290 software.

Standard Features

CP290 Director supports the standard CP290 features (with the exception of the questionably useful getting the clock stored in the interface) including:

• Turning on and off modules immediately, including turning them on dimmed;
• Defining "turn on" and "turn off" events to be stored in 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 specified time today;
  • Turning a module on or off once at the specified time tomorrow;
  • Turning a module on or off every week at the 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 CP290;
• Setting the base house code of the CP290, which is the house code it uses when its 8 on/off buttons are pressed;
• Setting the clock in the CP290 to the clock in the Macintosh; and
• Performing a self test function.

Extended Features

In addition to the above, the CP290 Director supports the following additional features:

• The ability to specify that an event is to occur at sunrise or sunset (plus or minus a specified time interval);
• The ability to specify a specific date on which an event is to occur, and optionally the interval in days thereafter that the event should be repeated;
• The ability to specify that the event should occur only on even days or on odd days.

The CP290 by itself does not support any of these features 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 the above features 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 implements one 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 when you specify that a light is to turn on every day at Sunset (see below for how to specify this).  When you specify sunset, the current 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 features is to open your event file daily.

Improved Reliability

X10 systems usually work reasonably reliably, turning on or off the selected module when the CP290 commands it. However, occasionally 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 Operation

Integrated Help

CP290 Director has help integrated into its user interface. 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 or selecting it and typing command-o will start 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 will first 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 depressed (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).

The background 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... command of the File menu. Once you have specified 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 represent have names, 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 menu.

You can duplicate an existing module from the main window by selecting its icon and selecting the Duplicate Selected Icon command of the Module menu (command-d).

You can create new modules from the main window with the New Module command of the Module menu (command-n). This command with create a new module and open the Edit Module 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 turn any 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 control-clicking 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 over the icon. 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 other module.

The Edit Module Dialog

The Edit Module dialog appears as the result of a New Module command (command-n) or an Open Selected Module command (command-o). This dialog allows you to specify or change:

• the module's icon;
• the module's name (which defaults to "Untitled" for a new module);
• the module's house code (which defaults to "A" for a new module);
• the module's ID (which defaults to "1" for a new module);
• the module's type ("Light" or "Appliance"); and
• up to nine cycles, each containing an "on" event and an "off" event.

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 Module dialog.

You can change the name by typing up to a 31 character name 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".

When you select 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 nine cycles 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.

Specifying Events

To specify an event you must specify the time of the event 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 desired time into 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 occur.  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 three subfields 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 for editing.
• 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 that would yield an invalid value.  Invalid characters are ignored.
• The hour subfield can range from 1 to 12. If the subfield 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 the 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 "AM", whereas typing "p" sets the field to "PM".

Entering an offset from the sunset or sunrise time works similarly. 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 popup menu below the line--of four options:

• Specify Every... 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.
• Specify Date... 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 Days to schedule the event for days 2, 4, 6, ..., 30 of each month.
• Specify Odd Days to schedule the event for days 1, 3, 5, ..., 31 of each month.

These latter two options may be useful if you are controlling your sprinkler system while your town has water conservation in force.

Using Cycles

You can specify up to nine cycles of on/off events.  Just use the Cycle popup menu to choose the cycle you wish to change.  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 Cycle (command-v) commands of the Edit menu.

Turning The Module On and Off Now

From the Edit Module dialog box you can also specify direct 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 in the Edit 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

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 the 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 window.  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.

The Preferences Dialog

If you select the Preferences... command under the Edit menu, the Preferences dialog appears.

This 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 CP290 should 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 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.   If you correctly specify the type of all of your modules, then you may prefer turning this preference on.

Event Files

Each main window actually represents an event file.  When 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 commands to 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 while CP290 Director is not running causes the events in the file to be automatically sent to the CP290.

CP290 Commands

The CP290 menu contains the follow commands that allow you to manipulate the CP290 controller:

• Send Events To CP290 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.
• Display Events From 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 below.
• Save Events From CP290 To File... saves the events currently displayed (see Displaying CP290 Events below) in the file you specify.
• Display Events From CP290 prints the events currently displayed (see Displaying CP290 Events below).
• Set Base House Code 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 Clock 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.

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 Toolbox allows 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 Macintosh.   If you have trouble getting CP290 Director to communicate with your CP290, try with Use Communications Toolbox both on and off.   Select Use Modem Port if your CP290 is connected to the modem port, or to the single (combined) port on a Powerbook.  This is the default selection.  Select Use Printer Port 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.

Displaying CP290 Events

This 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 event.  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 light modules, 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 events you specified, 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.

Macintosh Requirements

CP290 Director runs on a black and white or color Macintosh 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 sucessfully under MacOS 9.  If you find that it does or does not work properly on some particular Macintosh model or MacOS version, please let me know (jplw@softhome.net).

Version History

1.7 - Added news icons.

1.6 - Fixed a bug with the "ALL LIGHTS ON" and "ALL" selections for module number:

• These number settings could not be saved in a module, though they appeared in the pull-down menu.  They now can.
• The "turn on now" and "turn off now" feature has been 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 registered users:

• While events are being sent to the CP290, a progress indicator is now displayed.
• While events are being displayed from the CP290, a 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 improvements, and bug fixes:

• To change the "AM" or "PM" designation for times, you can now use either upper or lower case letters.  Before only lower case worked.
• The sunrise and sunset times are now calculated each they are used.  Before they were calculated only upon startup.  This is useful for people who leave CP290 Director runing for long periods of time.
• A bug causing housecodes I, J, K, and L not to work was fixed.
• The error message produced when CP290 Director cannot communicate with the CP290 now has additional information in it useful in debugging problems.

1.3 - 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.  Previously only the Modem, Printer, or Combined ports could be used.

1.2 - Various feature additions, feature improvements, and bug fixes:

• The 4 Release 1.1 brightness levels (100%, 75%, 50%, 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 either "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 Brightness 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 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, 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 current icon selected.
• Minor improvements in the Help function were made.
• An obscure bug in displaying events from the CP290 was fixed.
• Support for the Communications Toolbox and its Serial 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 Events From CP290" command and fixed some bugs.

1.0 - Beta version, not released.

How to Pay for CP290 Director

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 it. 

You can pay with a credit card via PayPal by clicking on the button to the left.

Once you have paid, you will receive a registration 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.

Acknowledgments

I would like to acknowledge David Baldauf for his creative suggestions for features, and his testing of CP290 Director.

You may distribute CP290 Director unmodified via any media, as long as you keep it together with this documentation.