Linux X10 universal device driver

with unified device interface

(aka Project Unidev)

Introduction

Let's start out with a short "why do I want this".  The normal /dev/x10/* interface to the X10 network uses up 2 major character devices out of the total of 256.  Some consider that excessive.  So, this version of the device interface gives you the same access with the tested line discipline and protocol translators with a new interface that minimizes the number of devices used up.  This interface accepts commands like "A1 ON" and "E ALL_UNITS_OFF" which are identical to what is logged by the standard interface to WiSH.  Logging is identical in form and function and x10logd works without modification.  All functionality provided in the native interface is provided through this interface with the exception of extended code, extended data, and simulated status of the X10 network.  And, if people like the unidev interface better, it may become the default.

Please read through this document completely before installing.  If you are in a terrible rush, at least read the sections on Installation and Usage.  This reads like bicycle instructions so it isn't for the faint of heart.  This document contains the installation instructions and supercedes INSTALL.txt and README.txt in the event that there is a discrepancy.

One final word on why this might prove useful:  If you think you have an idea that can improve the interface to the X10 network, this code provides a very straightforward example of how to write a new interface.  

Index

• Introduction (why bother)
• Downloading
• FAQ
• Installation
  • Compiling the driver
  • Create the Devices
  • Install the Drivers
  • File Locations
• Usage
  • User Space commands
  • Example Usage
  • Log and Status output
• Contacting the author
• References

FAQ

Beyond the basic introduction to the project, this section is intended to explain more of how this project came about and why certain choices were made.  This is an extension of the standard WiSH FAQ.

1. Q:  What the heck is x10_unidev and the unidev directory?
   A:  One of the advantages of the way the project was designed is that the user interface is completely separate from the line discipline which is completely separate from the protocol translator.  The PowerLinc and CM11A prove the theory that you can reuse the line disciipline.  But, what about creating a completely new interface?  Unidev is short for Unified Devices and is a version of the device interface which utilizes a single /dev device. Why would I do that?  Quite simply, I have received a couple of suggestions that I need to stop using up so many device entries and move the state machine/status management to the userspace.  After putting some thought into it, I decided that it might be worthwhile to create a device interface that was as minimal as possible but which retained complete x10 control.  unidev is exactly that and it took me about 6 hours to write, test, and debug for all 4 transceivers.  To create it, not a line of code was changed in any other file except x10_unidev.c.  Read more about how to compile and use this in the Unidev guide.
2. Q:  Can I write my own user interface for the project?
   A:  You most certainly can and I will consider adding it to the distribution.  But, you need to be prepared to answer questions and do fixing on it if there are any bugs.  Unidev is provided as an example of how easy it is to put a new front end on the drivers.  I still like the original interface better, but Unidev has some potential.
3. Q:  What are the advantages of the Unidev interface over the standard interface?
   A:  The unidev interface utilizes fewer major character devices.  This would make the interface applicable to become a subcomponent of the input system such that it would be assigned a minor number and share a major number with other drivers.  It also provides user language that is more natural to individuals that have been working with X10 for a long time.  The language of the interface isn't very natural from the command line, but from a programming language like Java, Perl, or C, it is much cleaner to have only one file open and to be able to write a string like "E15 ON".  With the standard approach, C, Java, and Perl have to open up a different device for each switch they want to talk to.  It also make the device driver act like an unintelligent device driver.  Arguments have been made that the standard interface puts to much intelligence into the driver by maintaining the status of the devices.  Indeed, the guides to writing device drivers push for the driver to be as simple as possible and to do as little as possible so that the userspace program can create the robustness for the system.  Since the userspace program must be written to understand the device types to truly understand what the network status should be, having the status in the driver is redundant and a system resource loss.
4. Q:  What are the advantages of the standard interface over the Unidev interface?
   A:  The standard interface is much easier to use from a command line.  It also allows for file system links to be made to the /dev/x10/* devices so that you can have more naturally named devices to write to.  Being able to type "echo on > /automation/foyer" was one of the first reasons that I went down the path to writing the drivers.  The standard interface also does the work necessary to know the status of a device or what the status should be if it were a light.  This simplifies both scripting and programming because the userspace program does not have to read the log and interpret the states to determine what action to take.  The standard interface use of /dev/x10/status also makes it easy for a programming language to create a matrix display of all 256 devices in the network without having to do any work.  
5. Q:  Why are both interfaces provided?
   A:  Over time, one interface will be favored over the other by the user community.  At some point, one of them will be dropped.  It is also possible that someone else will develop a better interface which will replace both interfaces.  By developing unidev, the development community is given an example of how to replace the user interface.  It also proved that it could easily be done without a single change to the line discipline or the protocol translator.
6. Q:  Can the drivers for the standard and unidev interface be loaded at the same time?
   A:  No.  Both utilize the same resources so they cannot coexist.

Installation

1) Compiling the drivers

To use the drivers, you will must have a working kernel source tree installed even if you already have a working kernel.  The reason is that to compile the drivers, information about the kernel has to be known. This comes from the .config in the /usr/src/linux top directory, and from the dependencies that are created when the "make dep" command is run.

Note that the drivers will only compile for kernel version 2.4.x.  Kernel 2.2.x does not support some features required by the drivers.  Kernel 2.5.x has substantially changed the system call interfaces and the drivers will not compile with 2.5.x.  Note that I will be working on porting to 2.5 very shortly.

Compiling as a standalone set of drivers (e.g. not installing in the kernel source tree):

You likely already have a working kernel and you don't want to recompile the entire kernel just to use the drivers.  You can still compile the modules without reinstalling your kernel by only performing the steps necessary to run "make dep" in the kernel top level directory. There are a couple of prerequisites to compiling the drivers.  

• The kernel source tree must be accessible from /usr/src/linux.  For example, under RedHat for kernel 2.4.18-19.7.x, link the kernel source directory to /usr/src/linux by typing "ln -s /usr/src/linux/linux-2.4.18-19.7.x /usr/src/linux).
• You must have a valid .config file that matches your running kernel in the top level directory of the kernel source tree.
• Remove all of the files in /usr/src/linux/include/linux/modules/ with the command "rm -f /usr/src/linux/include/linux/modules/*".
• Alternately:  You will need to recreate your .config file after running these commands so backup your .config first
  • Type "make mrproper" (without the quotes) in the top level directory of your kernel source.
  • Type "make symlinks" (without the quotes) in the top level directory of your kernel source.
• You have to have run "make dep" in the top level directory of the kernel source to create the necessary headers.  If you are using RedHat, the config files for the compiled kernel are in /usr/src/linux/configs.  Choose the appropriate one and copy it to /usr/src/linux/.config.  

Once you have the kernel sources set up properly, you can compile the drivers.

1. Type "make unidev" (without the quotes) in the top level directory of the WiSH source code.  Do not proceed if any errors occur.
2. To automatically install the drivers and the utilities, type "make installall" (without the quotes) in the top level directory of the WiSH source code.  This will copy the modules to your /lib/modules/<running kernel version>/kernel/drivers/char/x10 directory.  It will also copy the utilities to /usr/sbin.
3. Create the devices and load the appropriate module to start using your transceiver.

Compiling with the kernel (e.g. installing in the kernel source tree):

The unidev version of the interface will compile with the kernel but the Config.in and Makefiles have not been created.  Therefore, this option is not readily available at this time.

2) Create the devices (Note, this only applies to a system which does not have DEVFS.  If DEVFS is in use, the devices will be created automatically when x10.o loads):

There is only one device to create so I haven't created a script to do it for you.  To create the device, type:

# mknod /dev/x10 c 120 0

That's it.  If you want to load multiple drivers simultaneously, change the name of the device to be created and the major device number and then specify the parameter "major=#" when the driver is loaded.

3) Load the modules (Note that the drivers are loaded identically as they are for the standard interface)

Now that you have the the devices created, you need to load the modules to respond to the devices.  Scripts have been provided in the example_scripts/ directory to automate starting and stopping the drivers.  Copy the appropriate script to /etc/rc.d/init.d/x10 for for a RedHat system or call the appropriate script from /etc/rc.d/rc.local on a Slackware system.  On a RedHat system, you can run chkconfig to install in the appropriate runlevels.  For example, "chkconfig --level 35 x10" will cause the drivers to be loaded for run levels 3 and 5.

To load the modules by hand (recommended when testing for the first time), load the driver for your specific transceiver (ref the table below), and load the userspace program if needed.  The syntax of the action would be as follows:

Below is the table of drivers and the required helpers:

For example, to load the driver for the PowerLinc transceiver and connect to /dev/ttyS0, use the following sequence of commands:

# insmod x10_pl.o
# x10attach -pl /dev/ttyS0 &
# x10logd

The parameters that can be specified for the modules are:

• If running DEVFS
  • devroot:  the top level directory for the device files (default=x10 which results in /dev/x10)
• If NOT running DEVFS
  • major:  the major device number for accessing the driver (default=120)
• Independent of DEVFS
  • debug: setting to 1 will write tons of stuff to the console to trace the API (default=0)
  • timeout: the amount of time to wait for a response from the transceiver when expecting something (default=1000 which is 1 second)
  • delay: amount of time to delay between transmissions (measured in ms) (default=1000 which is 1 second)
  • retries: the number of times to try to retransmit when timeout expires while waiting to receive data (default=2)
  • fakereceive: causes the driver to simulate receiving what it sends.  The default depends on the driver being used.  Most transceivers do not hear what they send at the time that they send it.  However, transceivers like the PowerLinc Serial hear their own signals.  The default for the driver can be overridden on the command line.  Note that the log file will have a different format for any data that has been artificially logged due to fakereceive.  
  • syslogtraffic:  when this flag is set to 1, all traffic on the X10 network will be written to syslogd as kern.notice messages.  These will typically go to the console, /var/log/dmesg, and /var/log/messages.  If you have a busy network, the traffic on the X10 network could easily fill up your network.  Setting this to 0 stops the driver from logging traffic to the syslogs.  (default=0 which is off).
• Specific to the FireCracker
  • port:  This applies only to the FireCracker/CM17A.  The port can be specified as a hex address.  The standard IBM port locations for the PC are: com1=0x3f8, com2=0x2f8, com3=0x3e8, and com4=0x2e8.  (default=0x3f8)

Specific driver loads:

PowerLinc serial:
#insmod x10_pl
#x10attach -pl /dev/ttyS0 &
#x10logd -i /dev/x10

CM11A serial:
#insmod x10_cm11a
#x10attach -pl /dev/ttyS0 &
#x10logd -i /dev/x10

FireCracker radio transmitter:
#insmod x10_cm17a port=0x3f8
#x10logd -i /dev/x10

PowerLinc USB
#rmmod hid
#insmod x10_plusb
#x10logd -i /dev/x10

Note that for the PowerLinc USB, it may be necessary to unload the HID driver using the command "rmmod hid".  This is because the PowerLinc USB is a HID device, and the USB helper programs default to load both hid.o and x10_plusb.o.  hid.o intercepts all HID devices and prevents x10_plusb.o from gaining access to the transceiver if hid.o is loaded first.

If everything has been done correctly, you should now have the drivers loaded and you should have a line in your kernel log indicating that they have started.  Move on to the userspace usage for actually sending commands and watching the status of the network.

4) File locations

Once you know that the drivers are working properly, you can install the files into their permanent homes for the system.  install.sh has been provided to automate but there may be reasons that administrators prefer to install the drivers by hand.  

1. Copy utils/x10attach to /usr/sbin/x10attach (cp -f utils/x10attach /usr/sbin/x10attach)
2. Copy utils/nbread to /usr/bin/nbread (cp -f utils/nbread /usr/bin/nbread)
3. Copy utils/x10logd to /usr/sbin/x10logd (cp -f utils/x10logd /usr/sbin/x10logd)
4. Copy the drivers to the /lib/modules area (cp -f x10_pl.o x10_plusb.o x10_cm11a.o x10_cm17a.o /lib/modules/<kernel ver>/kernel/drivers/char/x10)
5. Copy the appropriate startup script from the example_scripts directory to automate the startup of the drivers when the computer is booted.  Copy the appropriate x10.*.sh file to /var/rc.d/init.d/x10 on a redhat system or to /var/rc.d/x10.sh on a slackware system (and edit /etc/rc.d/rc.local to call x10.sh).  For a redhat system, you can then specify which runlevels require the drivers using "chkconfig --level <levels> x10" where <levels> is usually "35" to start the drivers for run levels 3 and 5.

Userspace Usage:

Once the device has been created and the module has been loaded, /var/log/messages should show "x10 Transciever module v<version> (wsh@sprintmail.com)" to indicate that all went well.

At this point, normal userspace programs can be used to access the X10 network. The commands that are sent to the device must be of the following format:

<housecode>[<unitcode>] [<functioncode>]

Either the unitcode or the functioncode or both may be specified.  There is no space between the housecode and the unitcode, and there must be a space before the functioncode. All commands may be any combination of uppercase or lowercase.

The <housecode> field may be any letter from A to P.  The <unitcode> may be any number from 1 to 16.

The <functioncode> may be anything from the first column of the following table.  The BOLD characters are required and the remainder is optional.

Example usage:

Preset Dimming requires some extra work on the users part.  The way the protocol specifies all operations for X10 is that you first address a unit in one transmission, and then you send the command.  Normally the command is sent to the same housecode as the addressed unit so the driver can accept both the command and the housecode in one transaction; however, Preset Dim uses the housecode as the dim level.  Rather than requiring the userspace program to understand the sequence and mapping, the driver will accept the command "ps#" where # is a value between 1 and 32 inclusive. The following table shows the mapping of the housecodes to dim levels:

Alternately, to accomplish sending PRESET DIM 32% to E15, the command would be:
# echo e15 ps11 > /dev/x10

Script Examples

Scripting is considerably more complicated because there is no mechanism in the driver to track the status of an individual device.  To get the same functionality that is provided in the standard interface the userspace program needs to read the x10 device to capture events. It is still possible to write scripts that can watch for activity.

Activity logs

The driver also maintains a short circular log of traffic on the network which can be captured and decoded to store in a human readable log file.  All other information is written to the system log the syslogd facility.  The actual location of the logs is defined in /etc/syslog.conf.  All messages are logged to the console by default.  Below is a description of the classes that the driver uses for logging information to the system.

kern.info: this class of information is typically written to the console, /var/log/messages, and /var/log/dmesg.  This type of information is benign data being reported by the driver.  At startup the driver will write the version of each of the files in the module and indicate that it successfully started.  

kern.warning: this class of information is typically written to the console, /var/log/messages, and /var/log/dmesg.  This type of information warns of some activity that failed to complete but which is not fatal to the driver.  Typical uses of the warning messages are when the transceiver prematurely stops transmitting data due to a collision on the line.  Most bi-directional transceivers also require a handshaking protocol for proper communications and if that protocol times out while waiting for a message from the transceiver, a warning message will be produced.

kern.error: this class of information is typically written to /var/log/messages, the console, and /var/log/dmesg.  This type of information indicates that a catastrophic error has occurred in the driver.  As a result, the driver will usually try to unload itself.  In many cases the driver is unable to unload and the driver will be unusable or unstable.  It is highly recommended that the machine be rebooted to eliminate potential crashes of the entire system if the error text indicates an unstable situation.

kern.debug: this class of information is typicaly written to /var/log/messages, the console, and /var/log/dmesg.  This information is only generated when the debug parameter is passed to the driver.  It is recommended that the driver not be run with debugging turned on unless you are troubleshooting a problem and need to send the output of the driver for analysis.  Debugging the driver produces an enormous about of data and will quickly fill up system log files.

In addition to the system logs which are written to the hard drive, the driver maintains a log in memory.  The log is cleared whenever the driver is loaded or unloaded.  The log contains all transactions that occur on the X10 network as well as the virtual status of all devices on the network.  

Traffic log:  Whiles the driver attempts to maintain a virtual status of the X10 network, the logic for the status updates makes assumptions about the features of devices.  For flexibility, the driver also maintains a circular log of all commnds received from the network.  Each event is also timestamped with a double long value representing the time value in seconds.  This number can be imported directly into a userspace program and stuffed into a timeval structure to use standard library routines to manipulate teh time.  The log is accessed through /dev/x10/log blocks on read if no data is available.  The format of the data in the log follows the following 3 formats:

• <timestamp> <dir> <housecode><unitcode> - X10 unit address packet.  <timestamp> is the number of seconds since epoch.  <dir> is the direction and will be either "T" for transmit or "R" for receive.  The data will be capitalized.  For example, if a the address for A1 is transmitted on the network, the log will show "0123456789 T A1".  Similarly, if E15 is received from the network, the log will show "0123456789 R E15".
• <timestamp> <dir> <housecode> <functioncode> - X10 command packet.  <timestamp> is the number of seconds since epoch.  <dir> is the direction and will be either "T" for transmit or "R" for receive.  The data will be capitalized. For example, if the ON command is sent to devices addressed on housecode A, the following will show in the log:  "0123456789 T A ON".  Note that there is a space between the housecode and the functioncode.  The following table lists the valid commands that can appear for the functioncode:
  

  Function	Text
  ALL_LIGHTS_ON	Turns on all X10 devices on a single housecode that fall into the category of "light".  Devices such as wall outlets or relays will not respond to this command.
  ALL_LIGHTS_OFF	Turns off all X10 devices on a single housecode that fall into the category of "light".  Devices such as wall outlets or relay controller generally do not respond to this command.
  ON	Turns a device on.  All X10 devices respond to this command.
  OFF	Turns a device off.  All X10 devices respond to this command.
  DIM	Dim the X10 device by 1/16.  Not all X10 devices respond to this command.  Fluorescent lighting, wall outlets, and relay controls are examples of devices that do not respond to this command.
  BRIGHT	Brighten the X10 device by 1/16.  Not all X10 devices respond to this command.  Fluorescent lighting, wall outlets, and relay controls are examples of devices that do not respond to this command.
  EXTENDED_CODE	Currently not supported in the drivers.  This is used to allow non-standard codes to be put on the line to allow new devices that aren't specifically supported by the standard to be managed.
  HAIL_REQUEST	This command allows a transceiver to send a request for other transmitters to identify themselves.  The driver takes no action when this command is received.  A user space program should intercept this command and send a HAIL_ACKNOWLEDGE if implementing the hail protocol.
  HAIL_ACKNOWLEDGE	This command is sent in response to a HAIL_REQUEST to implement the hail protocol.  The driver does not take Action on this command.  A user space program should intercept and implement the hail protocol if desired.
  PRESETDIMHIGH	Used to dim or brighten a light to a specific dim level.  The level is determined by the housecode that is sent with the preset command.  The protocol simulator will properly update the status to reflect the dim level set for the unit.
  PRESETDIMLOW	Used to dim or brighten a light to a specific dim level.  The level is determined by the housecode that is sent with the preset command.  The protocol simulator will properly update the status to reflect the dim level set for the unit.
  EXTENDED_DATA	Only the Powerlinc Serial driver supports this function at this time.  This function is used to allow non-standard data to be put on the X10 line for communication with devices that were not anticipated when the protocol was written.
  STATUS=ON	This command is typically sent by a two-way X10 device in response to a STATUS request to indicate that the device is currently on.  The driver supports sending and receiving this command.
  STATUS=OFF	This command is typically sent by a two-way X10 device in response to a STATUS request to indicate that the device is currently off.  The driver supports sending and receiving this commnd.
  STATUS	This command is transmitted by a device to request that an X10 device respond with its current status.  Only two-way devices support this command.
  ALL_UNITS_OFF	Turns off all X10 units on a single housecode regardless of their type.

x10logd:  To make x10logd work with the unified drivers, the -i option must be specified to identify the location of the x10 device.

Contacting the author

My contact information is:

wsh@sprintmail.com

I am happy to answer questions regarding problems compiling and using the drivers. I am also happy to help explain the X10 protocol and how to use the drivers to manage the X10 network.  I am fully open to suggestions on how to improve the drivers but I may not accept all suggestions.  Please do not be offended or insulted if your suggestion is not incorporated.  Please read the Frequently Asked Questions (FAQ) prior to sending a request.  Also, at times the email can become overwhelming, so do not be insulted if it takes me time to respond to requests.  Bug reports will always get the highest priority.  

This project is hosted on Sourceforge and has the following resources:

• Mail list
• Homepage
• Project Summary Page

Enjoy!

Scott Hiles

Reference:

1. Phil Kingery's X10 Technical Series. A great deal of information for the X10 protocol.
2. Linux Device Drivers, 2nd Edition, By Alessandro Rubini, Jonathan Corbet. (online)
3. USB Sniffer, a free, software-only tool for monitoring USB traffic.
4. PowerLinc Serial Programming Manual