x10 Firecracker message format and a C++ class to use it

• Download source and demo project - 44.5 Kb
• Download latest from my website

Introduction

The Firecracker(C) is a product by X10 industries. It is a matchbox sized unit that plugs into a serial port and transmits commands wirelessly one-way to a receiving unit that's plugged into an AC outlet, which then sends the same signal through the home's AC wiring to all other x10 control modules. There are several types of modules, the two main ones being a light controller and an appliance controller. This system can accommodate 16 house codes, with 16 controllers in each house code, for a total of 256 devices. The individual controllers can be set to a particular house and unit code by rotary switches. There are several different commands that can be sent out; On, Off, Dim, Brighten, All lights on, All lights off and All controllers off. The On and Off signals are sent to a house and unit code. This causes that controller to go into a listen mode after which it will respond to dim and brighten commands which aren't provided with a target. Each dim or brighten command causes about a 5% difference. The All lights on and All lights off are targeted to only a house code which would cause all light controllers (up to the max of 16) with that house code to respond appropriately. Finally, the All units off will turn off all light and appliance modules on that house code.

Background

The Firecracker does not rely on normal serial communications, instead it is driven by the RTS & DTR signal lines which also provide its power. The command frame is pretty simple, consisting of only 5 bytes. Refer to table 4 for the message layout. A couple of tricky areas are initialization of the device and clocking out the signals to the RTS/DTR lines with appropriate delays between bits. Initializing the device is achieved by setting the RTS/DTR lines low for a short time and then bringing them both high with another delay before commencing a message. Sending out bits consists starting out with both lines high and setting DTR low for an on bit and setting RTS low for an off bit. In both cases, there must be a delay of at least 500 microseconds before setting that same line high again. This process continues until the entire 5 bytes are sent out. Table 1 lists the house codes. Notice that the house code is a bit different depending on which bank the target controller is on. Table 2 lists the byte to send to turn a controller either on or off. Note that controllers 9-16 have the same code as 1-8. Bit 2 of the house code is what ultimately decides which bank the command is for. Table 3 lists the all-on-off commands. These are sent in place of a code from table 2. Finally, table 4 shows the format of each message. The 2 header bytes and 1 footer byte are always the same.

Table 1 - House codes

Code	Units 1 - 8		Units 9 - 16
	Hex	Binary	Hex	Binary
A	0x60	01100000	0x64	01100100
B	0x70	01110000	0x74	01110100
C	0x40	01000000	0x44	01000100
D	0x50	01010000	0x54	01010100
E	0x80	10000000	0x84	10000100
F	0x90	10010000	0x94	10010100
G	0xA0	10100000	0xA4	10100100
H	0xB0	10110000	0xB4	10110100
I	0xE0	11100000	0xE4	11100100
J	0xF0	11110000	0xF4	11110100
K	0xC0	11000000	0xC4	11000100
L	0xD0	11010000	0xD4	11010100
M	0x00	00000000	0x04	00000100
N	0x10	00010000	0x14	00010100
O	0x20	00100000	0x24	00100100
P	0x30	00110000	0x34	00110100

Note that the house code has bit 2 turned on when addressing units 9 - 16.

Table 2 - Unit codes and function

Unit	On		Off
	Hex	Binary	Hex	Binary
1	0x00	00000000	0x02	00000010
2	0x10	00010000	0x12	00010010
3	0x08	00001000	0x0A	00001010
4	0x18	00011000	0x1A	00011010
5	0x40	01000000	0x42	01000010
6	0x50	01010000	0x52	01010010
7	0x48	01001000	0x4A	01001010
8	0x58	01011000	0x5A	01011010
9	0x00	00000000	0x02	00000010
10	0x10	00010000	0x12	00010010
11	0x08	00001000	0x0A	00001010
12	0x18	00011000	0x1A	00011010
13	0x40	01000000	0x42	01000010
14	0x50	01010000	0x52	01010010
15	0x48	01001000	0x4A	01001010
16	0x58	01011000	0x5A	01011010

Note that the code for units 8 - 16 are the same. As explained in table 1, the house code indicates if we're addressing units 9 - 16.

Table 3 - Commands

Command	Hex	Binary
Dim	0x98	10011000
Brighten	0x88	10001000
All lights on	0x90	10010000
All lights off	0xA0	10100000
All units off	0x80	10000000

Note that commands have bit 7 turned on.

Table 4 - Message format

Header	House code	Unit code, Function / Command	Footer
0xD5,0xAA / 11010101,10101010	Refer to table 1	Refer to tables 2 and 3	0xAD / 10101101

Using the code

Just a handful of functions are needed to surface the functionality of the FireCracker. Open the COM port by calling Open() with desired COM port as a string as in "COM1". Demo projects for both VC6 and VS.NET are included.

• void Open(LPCSTR pszComPort); // "COM1", "COM2", etc...
• void Close(); // Releases the COM port
• void TurnOn(char cHouseCode, int nUnitCode); // Turns on a unit. House code is the letter from A thru P
• void TurnOff(char cHouseCode, int nUnitCode); // Turns of a unit
• void Dim(); // Dims the last unit turned on by about 5%
• void Brighten(); // Same as Dim() but brightens instead
• void AllLightsOn(char cHouseCode); // Turns all lights on in a house code. Up to 16 controllers
• void AllLightsOff(char cHouseCode); // Turns all lights off
• void AllUnitsOff(char cHouseCode); // Turns all light and appliance controllers off

History

• 5/7/2004 - Initial release.