ipx10: X10 client / server

Written by Kim Vandry <vandry@TZoNE.ORG>

Project information and download available on Sourceforge


X10 is a method for transmitting commands over household power lines. The typical use of X10 is to send commands to Lamp Modules or Appliance Modules to switch power on or off, or dim (in the case of lamps) electrical loads.

This is a suite of programs that implement the ability to send and receive X10 commands with a computer. There are three components:

Clients

Clients send and receive commands via UDP/IP. Some clients are designed to give the user an interface to X10 (gtk-x10, x10c). Other clients implement automated functions (w800rf32).

Server

The server passes X10 commands between the clients (via UDP/IP) and the X10 interface. Currently, there are 3 servers:

X10 Interface

The X10 interface is a piece of hardware that connects the computer to the power line and implements actual sending and receiving of X10 commands.

Currently the best supported interface is Smarthome's 1132 device that talks to the computer on a serial port.

This interface is a good choice because it has the following features:

The X10 Firecracker (aka bottlerocket) is also supported but its usefulness is severely limited as a general purpose X10 computer interface:

Getting Started

After compiling the code, you can get started right away with:

x10d-1132s file:/dev/term/a
gtk-x10 localhost:12010

Substitute your serial port for /dev/term/a

If you don't have a working X10 interface module but want to try the software anyway, try:

x10d-loopback
gtk-x10 localhost:12010

SECURITY WARNING: The server doesn't implement any authentication or access controls. (I run the server behind a firewall, and everything behind my firewall is allowed to talk to the X10 server by choice).

TODO

Clients

gtk-x10

gtk-x10 is a graphical user interface and is the flagship client.

It has applets for:

x10c

Small client written in Perl that can be used to send x10 commands from the command line. Also useful to watch X10 commands received in a terminal or send them to a log file ("x10c monitor")

This is the best client to look at as an example for writing new ones.

gtk-x10.pl

Perl implementation of gtk-x10's tiny-window applet. This client is superceded by gtk-x10's functionality.

To make gtk-x10 behave similarly, run:

gtk-x10 server:port tiny=forcemap,nodeco,-162,0

w800rf32

The most popular receiver for X10 wireless commands is an appliance module with a built in wireless receiver sold by X10. This receiver is convenient because it is a standalone unit that converts X10 wireless directly into X10 PLC, convenient for applications where a computer is not available, but it has the following problems:

The W800RF32 by WGL Designs is an excellent X10 wireless receiver which solves all of the above problems.

The w800rf32 program listens for commands sent by the W800RF32 via a serial port, decodes them, and sends them to a Perl script for processing. The Perl script, w800rf32_action, supports sending the commands received to x10d directly, or it can do the following translation first:

The most popular model X10 wireless remote control that has 18 buttons (8 to turn units on, 8 to turn units off, plus a dim button and a bright button). This remote supports only turning units on or off and then dimming or brightening them. It lacks the ability to dim or brighten a unit without turning it on or off first.

I wanted to make something more powerful possible with this remote control. w800rf32_action implements that. It does so at the expense of simplicity though (you generally have to press two buttons instead of one to get something done).

With w800rf32_action, the remote control works like this: The lefthand side of the remote control (the 8 buttons labelled on) select an available unit from 1 to 8. The righthand side of the remote control (the 8 buttons labelled off) set the currently selected unit to various brightness levels. The first button on top is off (0%) and the last button on the bottom is 100% (full on). You can also press DIM (directly below the button for full intensity) to send an On command for the currently selected unit. Use this to turn on a unit to its default brightness level or to turn on any unit that doesn't support preset dim commands.

As an additional feature, w800rf32_action supports multiple banks of 8 units each. When you switch to a different bank, the meaning of units 1 to 8 changes. To change banks, press one of the buttons in the left column (the On column) and then press BRIGHT. This will select the bank number corresponding to the unit number pressed just before BRIGHT, and leave unit 1 selected in the new bank.

The Protocol

Commands are send to the server in ASCII in the payload of UDP datagrams. The server will respond to each command sent. Multiple command can be sent in a single UDP datagram by seperating them with CRNL. In this case the server will send back a response to each command, seperated by CRNLs.

commands

x10-command helloThis is a ping command. The server will respond with x10-hello
x10-command preset n Issue a preset dim command to level n (range: 0..31)
x10-command house unit Issue the X10 command house unit
x10-command house function Issue the X10 command house function
x10-command house unit function Shorthand to issue both a unit X10 command and a function X10 command
x10-command query Request to report the current status of each unit. The server will respond with x10-status
x10-command monitor Request that the server copy all transmissions received to this client. This command should be sent approximately every two minutes to make sure the server keeps sending transmissions.

responses

x10-hello sent in response to x10-command hello
x10-ok command acknowledged
x10-syntax-error command not understood
x10-monitor-ok command acknowledged, will begin echoing X10 messages received
x10-received A copy of an X10 transmission received. Sent by the server to clients that have requested monitoring.
x10-state

Sent by the server to clients that have requested monitoring to indicate that the server's idea of the current state of a unit has changed. The state is represented as a single ASCII character:

0%                          100%
0123456789abcdefghijklmnopqrstuv

0 means that the unit is off, v means that the unit is at full intensity (preset 31 or 100%), characters in between are the other preset levels.

? means unknown (the server was started too recently for it to aquire any information of the status of the unit).

= means on, but the server doesn't know what the unit's default on level is so it is unable to report an actual preset level

- means that the unit was on and that there have been subsequent dim or bright commands, so the current brightness level could be different from the unit's default on level or could even be off (if it was dimmed all the way down)

x10-status Sent in response to x10-command query, the server reports 256 status characters, one for each unit in each house code. Each character is as in x10-state
x10-end Server response appendedto the end of every packet sent in response to commands.