Abstract:

This document is a specification of the TimeCommander Protocol(tm) format -- a defined command language for computer interface and control of home automation systems, such as TimeCommander, TimeCommander-Plus and Stargate.

(c) 1995 IHS.

Printed in USA All rights reserved.

This document may be reproduced or copied -- provided that this document is reproduced in its entirety and all copyright notices are intact. This document is believed to be accurate at the time of publication, however, JDS Technologies and IHS makes no claim that this document is error-free.

Please direct any inquiries to:

JDS Technologies

Phone: (858) 486-8787

FAX: (858) 486-8789

Note: Numeric values in this document may appear with or without a suffix character:

254 No suffix: decimal

254d 'd' suffix: decimal

10110001b 'b' suffix: binary

6FC5h 'h' suffix: hexadecimal

69bcd "bcd" suffix: binary-coded-decimal (hex, without the A-F values)

TimeCommander, TimeCommander-Plus and Stargate are trademarks of JDS.

WinEVM, Event Manager and MegaController are trademarks of IHS.

Visual Basic and Windows are trademarks of Microsoft Corporation.

X-10 is a registered trademark of X-10 (USA), Inc.

Upon reset the TimeCommander will do the following:

The TimeCommander uses buffered serial I/O for communicating to the host computer. Both the input and output buffer are 250 bytes in length. There is a 2 second serial port timeout. When a serial port timeout occurs, a carriage return is automatically inserted into the input buffer. This is done to keep spurrious serial port activity from hanging up the system. This means that there can be no more than 2 seconds between characters sent to the TimeCommander.

The serial port parameters are as follows:

Baud: 2400

Parity: None

Bits: 8

Stop Bits: 1

Pin 2: Transmit data

Pin 3: Receive data

Pin 5: Signal Ground

TimeCommander keeps internal variables. These are:

After a powerup condition, TimeCommander sets the Powerfail flag and clears it after the first pass through the schedule loop. TimeCommander also logs the PowerFail message in the message log.

When the schedule is first started, the Firstpass flag will be set, and cleared at the end of the eval loop. This can be used in a schedule to provide an initialization event.

This flag will be set when the X10 zero crossing is lost.

The X10Status Array is a 16 x 16 array that holds the status of the X10 device, ON, OFF, or IDLE as well as other parameters.

There is a corresponding 16x16 Dim Status array using the same structure as the X10 Status array. This array keeps track of the Dim/Bri level of each X10 device. The Dim/Bri levels are shown in Figure 4: X10 Dim Status Values.

The reason the OFF commands set the status to 21, is that when the dim level command is issued, the current level is looked at to determine how many dim or bright commands to issue. If a lamp module is OFF, a dim or bright command will turn the module ON, before it will dim. With this in mind, if a lamp module is issued an OFF command, the dimstatus is set to 21, when a dim level command is issued, say to level 8 (of 20), if the dimstatus was 0, it would issue 8 bright commands. By setting it to 21, it will issue 3 dim commands, the first one will turn on the lamp, the next 2 to reduce the level to 8.

The SetLevel feature for Dim/Bri of X10 lamp modules disables reception of DIM/BRI commands while it is sending. This is due to the TW523’s inability to receive properly. It will update the dimstatus directly.

* The X10dimstatus will only be updated by DIM and BRIGHT commands only when these commands are issued by the TimeCommander. This is due to the TW523's inability to accurately decode DIM/BRI commands that are sequential with no quiet periods between transmissions.

TimeCommander can log any type of text message. The data log is 8000 bytes in size. Each message that is logged must be NULL terminated. The data log is a circular buffer that has a head and tail pointer. If the log fills up, it will start to overwrite the oldest data. Reading the log is done by starting with the tail pointer and 'puts()' until the head pointer passes the head pointer.

The Log_head will always point to the next location where a data message will be stored. The Log_tail will always point to the beginning of the oldest message. If the Log_head goes past the Log_tail during a data message store, the Log_tail will increment until it points to the next complete message that is past the Log_head, null filling the buffer as it increments.

During a data log read, the Log_tail will be copied into a temp tail pointer, the temp_tail will be used as the index of the buffer until it is equal to the Log_head pointer.

Command Format:

##%01[cr]

TimeCommander will respond with text output showing status.

Default States

Refresh Interval 30

Security Interval 30

X10 Status bytes 0x01

X10 Retry 5

X10 3 Phase enabled

Answeronring 0

ModemInitString "AT"

X10 History cleared

Message Log cleared

Direct command will allow an X10 command to be sent. After the command is sent an acknowledge will be returned. The format for direct command is:

##%04xxxx[cr]

where xxxx is an X10 command in hex format. The bit pattern is as follows :

zzzzzbbk kkkkhhhh

zzzzz = New Dim/Bri level *( unused if normal command)

if bb = 00, normal x10 type command

if bb = 01, the module will be set to IDLE.

if bb = 10, the module will be set to the dim/bright level that is specified in zzzzz

if bb = 11, reserved

kkkkk = keycode (hex)

hhhh = house code(hex)

[cr] carriage return

* to repeat a command, such as sending 3 DIM commands, the X10 command format is different:

zzzzbbbk kkkkhhhh

zzzz = Number of repeats - 1

bbb = reserved, set to 000

kkkkk = keycode (hex)

hhhh = house code(hex)

[cr] carriage return

House and unit codes used by the TimeCommander are coded as follows:

Below are some examples:

##%0400a6[cr] // command for A-7

##%040146[cr] // command for A-ON

##%04002d[cr] // command for L-15

##%04412d[cr] // command for ‘5’ L-DIM commands

For PCS modules only

to set B3 to 40%,

##%040047 // first send out B-3

##%042447 // then send out B-3 set level 40%

The set time command will set the time and date of real-time clock inside of the unit. It will set the local clock as well as changing the time in the clock chip. When the unit receives this command, it will update the RTC with the time given, zeroing the seconds. The command for setting the clock is:

##%05AAAALLLLTTSSYYMMDDRRHHMMCC[cr]

where:

· AAAA - Latitude (hex)

· LLLL - Longitude (hex)

· TT - Timezone (hex)

· SS - Daylight savings time flag

bit 0 - Daylight Savings time Enabled

bit 4 - Set if Daylight savings time is in effect

· YY - Year (0-99 bcd)

· MM - Month (1-12 bcd)

· DD - Date (1-31 bcd)

· RR - Day of week (1-7)

· HH - Hour (0-23 bcd)

· MM - Minute (0-59 bcd)

· CC - checksum

The TimeCommander will respond with an acknowledge after receiving the command and setting the time.

Read time will read the time and date of the TimeCommander. The command format is as follows:

##%06[cr]

The TimeCommander will respond with:

>YYMMDDRRHHMM[cr] (see Set time for description)

This command will prompt the TimeCommander to return the system information. The information consists of ROM version, amount of RAM available, last download date and file, etc.

##%07[cr]

The TimeCommander will return a text based data dump on the internal states.

The clear memory command will wipe out all of the TimeCommander schedule information. After the TimeCommander receives the command and clears the memory, it will respond with an acknowledge.

The command syntax for memory clear is:

##%08[cr]

This command will download the refresh value interval that the TimeCommander uses to update the selected X10 devices. Any X10 device with it’s REF bit set will be refreshed at the end of the interval period.

##%09xx[cr]

where xx is the refresh interval in minutes (hex).

This will download the X10 status to initialize the TimeCommander's receive status array with pre-defined module status and identify whether it is a lamp module, frozen or plays catch-up after a power failure. After downloading the X10 status and before the schedule is started, TimeCommander will send the X10 command that will set the each defined device to the state specified in the status byte.

The command syntax for Timer download is:

##%0e[cr]

The TimeCommander will respond with: (using same bit format as download)

XXXX[cr] /* timer 0 */

XXXX[cr]

XXXX[cr]

...

XXXX[cr] /* last timer*/

The command syntax for Flag download is:

##%0fXX ... XX[cr] /* flag 0 being the first character */

The command syntax for Flag upload is:

##%10[cr]

The TimeCommander will respond with:

###%10XX...XX[cr] /* flag 0 being the first character */

The command syntax for Variable download is:

##%11[cr]

XX[cr] /* variable 0 in hex*/

XX[cr]

XX[cr]

...

XX[cr] /* last variable */

The command syntax for Variable upload is:

##%12[cr]

XX[cr] /* variable 0 in hex*/

XX[cr]

XX[cr]

...

XX[cr] /* last variable */

The Security Offset is the outer limits that the security variation can be. For example, if the seed was 60 minutes, the security offset would be +/- 30 minutes from the compare time specified. The security seed has a legal range of 120 minutes, or +/- 60 minutes.

The command syntax for Message download is:

##%13xx[cr]

where xx is the security seed (hex)

This command will dump the message log. Each message has a time/date stamp as well as the message. The messages will be dumped starting with the oldest message in the log, ending with the newest. The command syntax for Dump Message Log is:

##%15[cr]

TimeCommander will respond with:

>##0 /* acknowledge */

MMDDYYHHMMSSxx..xx[cr] /* last message in que, cr terminated*/

MMDDYYHHMMSSxx..xx[cr]

MMDDYYHHMMSSxx..xx[cr]

...

MMDDYYHHMMSSxx..xx[cr] /*first message in que*/

##0[cr] /* acknowledge, signifies end of log */

MM = month, DD = day, YY = year, HH = hour, MM = mins, SS = sec, xx..xx = message string.

This command will clear the message log, resetting the que pointers.

##%16[cr]

This command will stop the Schedule.

##%1a[cr]

This command will start the Schedule.

##%1b[cr]

This command will disable the Echo mode.

##%1c[cr]

This command will enable Echo mode. Any X10, flag, variable, etc., activity will be echoed through the serial port. The format of the Enable Echo Mode command is:

##%1d[cr] /* Echo enabled */

The format of the echoed command is:

!!mm/ddttttttjklm[cr]

where mm is the month(bcd), dd is the day(bcd), tttttt is the number of seconds since midnight (in decimal 10) and jklm is the TimeCommander activity(in hex) that was received. jklm can be decoded as follows:

j k l m (hex)

jjjj kkkk llll mmmm (bin)

jjjj = Echo command

hex binary

0x0 or (0000) == X10 activity

0x2 or (0010) == Timer

0x3 or (0011) == Flag

0x4 or (0100) == Variable

0x5 or (0101) == Relay Output

0x8 or (1000) == IR Output

0xa or (1010) == DI Input 1-8

0xc or (1100) == DI Input 9-16

kkkk, llll, mmmm are described below:

House and unit codes used by the TimeCommander are coded as follows:

Figure 6: House and Unit Hex values

Examples:

!!03/240336980064 // C1 received

!!03/2403369801C4 // C-OFF received

!!03/240336980833 // P-16 transmitted

!!03/240336980923 // P-DIM transmitted

This command will start the X10 Signal Test. It will send out Unit/On/Off, Unit/On/Off sequences until it is stopped with the Stop X10 Signal command. The syntax for this command is:

##%1euuhh[cr]

where uu is the unit code, hh is the house code. See Figure 5: House and Unit Hex values, for the house and unit code hex values.

Example:

##%1e0603 /* uses P1 */

This command will stop the X10 Signal Test.

##%1f[cr]

This command will instruct the TimeCommander to upload the X10 status using a condensed format to speed up the transfer. Note that only the device’s state is uploaded.

##%20[cr] /* Upload Command */

...

This command will instruct the TimeCommander to activate the specified Then Macro.

The format for this command is:

##%22xx[cr]

where xx = Then Macro number (position in database list)

This command will instruct the TimeCommander to dump out the contents of the X10 buffer.

The format for this command is:

##%23[cr]

The X10 buffer holds the last 200 X10 transmissions. The output from this command is in the same format as shown in the Echo mode.

This command will store the schedule name. The schedule name will be shown when the system info is used. The format for this command is:

##%24ss...ss[cr]

where ss...ss is the schedule name.

Example: ##%24SUMMER[cr] // Store schedule name 'SUMMER'

The TimeCommander will respond with:

##0

This command will instruct the TimeCommander to set/clear the specified flag.

>##%25xxyy[cr] /* Direct flag Command */

where xx is the flag number (hex)

where yy is the state to change the flag to. 00 = clear, 01 = set.

The TimeCommander will respond with:

##0

This command will instruct the TimeCommander to modify a particular variable.

>##%26aabbcc[cr] /* Direct Variable Command */

##%28aaxx[cr]

##%29aabb[cr]

bb is the number of bytes to receive is hex format.

##%2a[cr]

##%2c[cr]

##%2dxx...xx[cr]

where xx....xx is the phone number with any delays, etc. Consult the Hayes command set for a list of modem commands.

##0

##%2fxx[cr]

where xx is the Ringcount in hex.

##%30ss..ss[cr]

where ss...ss is the Modem Init string.

##%31xx[cr]

##%33xxiimmdd[cr]

dd is the data byte, any bit with it’s mask bit set will be changed to the value in the data byte.

(See here for examples and descriptions of the IO structures).

##%34xx[cr]

dd: days Bitvalue

##%36hhuu[cr]

Invalid commands will not have any status sent back, because a modem echoes any text back, this causes an endless loop.

TimeCommander keeps shadow registers of the dedicated I/O. This is needed to reduce the network bus traffic as TimeCommander does a read and write only once per pass through a schedule. Since all of the IO’s inputs are buffered, transitions at the inputs will not be missed.

At the beginning of the schedule, TimeCommander reads the Inputs and the A/D converters and stores the results into the shadow registers. The schedule then references the registers instead of sending out network read commands. At the end of the schedule pass, the Outputs are written to the I/O devices with relays if a change was made in a schedule.

1.1.1    Get Controller Type

1.1.2   Advanced X10 Command (Version 2.40 and higher)

House and unit codes used by the TimeCommander are coded as follows:

Figure 1: House and Unit Hex values

1.1.3   Return firmware version