Citation: X10 Ltd.


Contents; Communications Bridge
Communications Bridge

The communications bridge provides the link between the interface and the PC, allowing commands to be both transmitted and received. It will also track the current status and adjust commands accordingly.

There are two methods of passing data to the communications bridge, via command line sending Windows messages.

Command Line.

This always takes the form:

X10Comm <command>[<, delay>]

Windows Messages.

The communications bridge will accept the WM_COMMAND Windows message with the following parameters:

WORD parameter (wParam)	Ordinal Value

IDC_REGISTER	300

IDC_UNREGISTER	301

IDC_TXDATA	302

IDC_REGISTER:

This is sent with the LONG parameter (lParam) providing a far pointer to a REGMESSAGE data structure containing the handle of the window to notify, the message to transmit and also a WORD identifier to specify uniquely identify the message.

On receiving the IDC_REGISTER message, the communications bridge will add the parameters to it's current notification list. Subsequent reception of X-10 functions will then cause the current device status to be posted to the registered windows. The LONG parameter of the posted message will contain a far pointer to an array of bytes identifying the current device status. This pointer should be copied to the local memory immediately as it is volatile.

The array of bytes is segmented into four groups of 256 bytes and a group of 14 bytes detailing the following information:

Group 1:

Lamp brightness level (0 for off, 100 for full brightness and 254 for an undefined brightness level.

Group 2:

Appliance status (0 for off and 255 for on).

Group 3:

Number of 'On' commands that have been received for the indexed device.

Group 4:

Number of 'Off' commands that have been received for the indexed device.

Group 5:

14 bytes detailing device specific information received from the interface.

This data may be expressed in a REGDATA structure.

IDC_UNREGISTER:

This message should be sent before the application terminates. The message must not be posted as the application may terminate before the message is received causing invalid data to be received.

As for the IDC_REGISTER message, the LONG parameter should contain a far pointer to a REGMESSAGE structure that defines the application's parameters.

IDC_TXDATA:

This message is used to send a command on the power line.

The LONG parameter of the message may contain a far pointer to a buffer containing the command that is to be sent, or if the high word is null, the parameter may contain a command index to cause a configuration command to be transmitted to the interface.

Accepted Commands

The commands accepted by the interface are typically structured as follows:

<housecode and device code list> <function>, <delay>

The housecode and device code list is comma delimited, and each device must be of the same housecode (i.e. A1,B2,C3 is illegal). There should not be any spaces following the comma, nor at the beginning of the string.

After the housecode and device code list, there should be a single space followed by the function and any additional data associated with the function. Accepted functions are:

All Units Off

All Lights On

All Lights Off

Hail Request

Hail Acknowledge

Status On

Status Off

Status Request

These two functions must be prefixed by a housecode and device code (i.e. "A1" for "A All Units Off"), although the unit addressed is un-addressed after the completion of the function.

On

Off

Dim

Bright

Dim and Bright are both followed by three digits and a percentage sign (i.e. 009% for 9%, 050% for 50%). If the unit should be brightened to 100% prior to dimming, then the most significant bit of the brightness level must also be set. For example, to dim lamp B10 by 50%, the command would be:

B10 Dim 050%

To brighten the lamp to 100% first, and then dim to 50%, the command would be:

B10 Dim 178%

The value of 178% is obtained by a logical OR between 50 (0x32) and 0x80 (i.e. the most significant bit) to give a value of 178 (0xb2).

Extended Code

Extended Code transmissions must be followed with a space and then the command and data bytes in hexadecimal without any spaces, i.e.:

C7 Extended Code 5A12

This will address device C7 and send the extended command 0x5A and data 0x12. Note that the housecode and device code list for extended code must only address a single device due to the implementation of the protocol.

There are two additional commands that may be transmitted to the interface:

Dim To

The Dim To command is a pseudo-X10 command that relies upon the communications bridge tracking the current brightness levels. The software will use the knowledge of the current levels to brighten or dim the lamps addressed within the device list to the final level specified in the command, i.e.:

A2,A3,A9 Dim To 090%

As before, the devices within the list must all have the same housecode. If the illumination level is unknown, then the associated lamp will be automatically brightened to 100% and then dimmed to the requested level.

Ring

This command simply specifies whether the interface should assert the serial ring (RI) signal whenever an X10 command is received. This does not require a housecode or device code, and will not accept a delay setting.

Ring 1	This turns the ring signal on.

Ring 2	This turns the ring signal off.

Delays.

The commands may be delayed (using the internal scheduler) to occur a number of minutes after the command is transmitted. This is achieved by entering a delay time after the command:

A3,A7 Dim To 080%, Delay 025

The number after the delay must always be three digits, and identifies the delay time in minutes. This command will therefore dim lamps A3 and A7 to 80% after 25 minutes.

The delay command must be separated from the command with a comma followed by a single space exactly as described above.

Command Indices

The following is a list of commands that may be sent via the IDC_TXDATA message to cause a configuration message to be sent to the interface (note, in each case, the top eight bits of the long parameter must be zero):

Display the advanced COM configuration window:

X10_DRIVERSETTINGS	0x01

Display the basic COM configuration and test window:

X10_BASICCOMSETTINGS	0x02

Request the current X-10 module status from the communication driver:

X10_UPDATESTATUS	0x03

Request a status update from the communication bridge.

X10_NEWCM10MACRO	0x04

Cause a macro to be downloaded to a CM10 interface:

X10_CHANGECOMPORT	0x05

Change the COM port (note, the high byte of the low word - bits 4 to 7 - must contain the port identifier, which may be any value from 1 to 255):

X10_WAKEUPTIMER	0x06

Download the wake-up timers from the registry (Windows 95) or .ini file (Windows 3.x) to a CP10 power-strip interface:

X10_MODULECODE	0x07

Download the CP10 power-strip interface's device code and housecode from the registry (Windows 95) or .ini file (Windows 3.x):

X10_EEPROMDOWNLOAD	0x08

Download the new EEPROM data to a CM11 interface or CP10 power-strip interface:

X10_REQUESTSTATUS	0x09

Cause the communication driver to request the current device status from the interface (CM11 or CP10):

X10_BATTERYLEVEL	0x0a

Poll the interface for the current battery usage timers (CM11 and CP10):

X10_SETCLOCK	0x0b

Cause the current system time to be downloaded to the interface and clear the current address mask if high byte of the low word - bits 4 to 7 - are set:

X10_CHANGEBATTERY	0x0c

Inform the interface that it should reset the battery counters:

X10_MACROTIMERPURGE	0x0d

Purge all outstanding macro timers:

The communications bridge will also accept the WM_COPYDATA message to provide the same functionality as the WM_COMMAND message. The parameters for the WM_COPYDATA message are as follows:

wParam	Handle of the window sending the message

lParam	Far pointer to a COPYDATASTRUCT structure.

The dwData parameter of the COPYDATASTRUCT structure defines the action that is to be taken by the communication bridge, and the cbData and lpData parameters define any additional data that is required. Possible values for dwData are:

CDM_REGISTER	0x0001

CDM_UNREGISTER	0x0002

Messages used to register and unregister the client application to receive status updates whenever a change of state is detected. The cbData and lpData parameters should be 0.

CDM_TRANSMIT	0x0003

Used to initiate an X-10 transmission. The cbData should indicate the length of the data string that identifies the transmission (ie A1 On, Delay 000) and the lpData contains a FAR pointer to the data string.

CDM_STATUS_REQUEST	0x0004

Sent to the communications bridge to request the current device status (with cbData and lpData equal to 0). The communications bridge will then return the status data via a WM_COPYDATA message with the members of the structure set as follows:

wParam	Communication bridge window handle.

lParam	Far pointer to the WM_COPYDATA structure:

The WM_COPYDATA structure members will be defined as follows for this message:

dwData	CDM_STATUS_REQUEST.

cbData	size of the REGDATA structure.

lpData	Far pointer to the REGDATA structure.

CDM_DRIVERSETTINGS	0x0005

Display the basic COM configuration and test window:

CDM_BASICCOMSETTINGS	0x0006

Request the current X-10 module status from the communication driver:

CDM_NEWCM10MACRO	0x0007

Download a new CM10 style macro to the interface.

CDM_CHANGECOMPORT	0x0008

Change the COM port. The lpData parameter of the COPYDATASTRUCT must point to the new COM port identifier, which may be any value from 1 to 255.

CDM_WAKEUPTIMER	0x0009

Download the wake-up timers from the registry (Windows 95) or .ini file (Windows 3.x) to a CP10 power-strip interface:

CDM_MODULECODE	0x000a

Download the CP10 power-strip interface's device code and housecode from the registry (Windows 95) or .ini file (Windows 3.x):

CDM_EEPROMDOWNLOAD	0x000b

Download the new EEPROM data to a CM11 interface or CP10 power-strip interface:

CDM_REQUESTSTATUS	0x000c

Cause the communication driver to request the current device status from the interface (CM11 or CP10):

CDM_BATTERYLEVEL	0x000d

Poll the interface for the current battery usage timers (CM11 and CP10):

CDM_SETCLOCK	0x000e

Cause the current system time to be downloaded to the interface and clear the current address mask if the lpData parameter of the COPYDATASTRUCT is non zero.

CDM_CHANGEBATTERY	0x000f

Inform the interface that it should reset the battery counters:

CDM_MACROTIMERPURGE	0x0010

Purge all outstanding macro timers:


REGMESSAGE:

This structure is defined to pass application specific data between applications, and it is defined thus:

typedef struct tagREGMESSAGE

{

HWND	hWnd;

UINT	uiMessage;

WPARAM	wParam;

} REGMESSAGE;


REGDATA:

This structure is defined to pass device specific data between applications, and it is defined thus:

typedef struct tagREGMESSAGE

{

BYTE	bStatus[4][256];

BYTE	bDeviceData[14];

} REGMESSAGE;

Note the device data is defined as follows:

Bit range	Description
111 to 96	Battery timer (set to 0xffff on reset)
95 to 88	Current time (seconds)
87 to 80	Current time (minutes ranging from 0 to 119)
79 to 72	Current time (hours/2, ranging from 0 to 11)
71 to 63	Current year day
62 to 56	Day mask (SMTWTFS, bit 56 = Sunday)
55 to 52	Monitored house code
51 to 48	Firmware revision level 0 to 15
47 to 32	Currently addressed monitored devices
31 to 16	On / Off status of the monitored devices
15 to 0	Dim status of the monitored devices

where bit 0 is defined as bit 0 of bDeviceData[13] and bit 111 is defined as bit 7 of bDeviceData[0].


COPYDATASTRUCT:

This structure is defined to pass data between applications (16 bit and 32 bit), and it is defined thus:

typedef struct tagCOPYDATASTRUCT

{

DWORD	dwData;

DWORD	cbData;

LPVOID	lpData;

} COPYDATASTRUCT;