X10CM17A(5)X10CM17A(5)NAMEx10cm17a - HEYU support for the X-10 CM17A "Firecracker"
DESCRIPTION
Heyu is a program primarily intended for controlling an X-10 CM11A home
automation computer interface, however optional support is also
included for the X-10 CM17A "Firecracker". The CM17A is a small serial
dongle which can transmit X10 commands via RF signals to a transceiver
plugged into the power line. The CM17A and CM11A coexist on the same
serial port - no additional serial port is required.
The combination of a CM17A and transceiver may be useful as an X10 sig‐
nal bridge between two or more disjoint AC power lines. Inclusion of
support within Heyu allows the CM17A commands to utilize Heyu aliases
for module addresses and also allows these commands to be used in Heyu
scenes and usersyns. With Heyu support, the CM17A can be used to emu‐
late standard X-10 RF remotes and also the RF signals from X-10´s
"Entertainment Anywhere" universal remotes. Unfortunately the CM17A
doesn´t seem to be capable of transmitting the X-10 RF Pan & Tilt com‐
mands.
As far as can be determined there is no version of the CM17A which
transmits at an RF frequency other than the 310 MHz used for X10 trans‐
ceivers in North America. Therefore an option is provided to compile
Heyu without CM17A support for users outside North America or simply
those who have no interest in this device. (See the file "INSTALL"
included in the Heyu distribution directory.)
CM17A COMMANDS
As with the CM11A, a design objective for Heyu is to support every fea‐
ture of which the hardware is capable. In the case of the CM17A, Heyu
provides more precise control over the RF output than other software.
This plus the differing response of different transceiver types to RF
signals leads to a degree of complexity which may be confusing to the
uninitiated.
There is no way of detecting the presence or absence of a CM17A on the
serial port other than by observing the power line signal from a trans‐
ceiver (like an X-10 TM751 or RR501) which receives the RF transmission
from the CM17A and converts it to a power line signal. The CM17A com‐
mands will have no effect if the CM17A is absent other than a short
delay. All the CM17A commands may be used in Heyu scenes and usersyns.
freset Reset the CM17A device.
fon HU Transmit RF On
foff HU Transmit RF Off
fbright H[U] <count> Transmit RF Brights [after On]
fdim H[U] <count> Transmit RF Dims [after On]
fdimbo HU <count> Transmit RF Dims after Off
flightson H Transmit RF All Lights On
flightsoff H Transmit RF All Lights Off
falloff H Transmit RF All Units Off
farb xx xx <count> Transmit RF Abitrary two hex bytes
farw xxxx xxxx ... Transmit one or more 2-byte hex words.
flux <parameters> Special for the LUX17 and LUX23 front ends.
The following "fast" commands are coded a little differently and on
most systems require calibrating a timing loop by running the ´heyu
utility calibrate´ command to work correctly.
ffbright H[U] <count> Transmit RF Brights [after On]
ffdim H[U] <count> Transmit RF Dims [after On]
ffdimbo HU <count> Transmit RF Dims after Off
ffarb xx xx <count> Transmit RF Arbitrary two hex bytes
ffarw xxxx xxxx ... Transmit one or more 16-bit hex words.
fflux <parameters> Special for the LUX17 and LUX23 front ends.
The LUX17 and LUX23 front ends for Heyu (available from the Heyu web‐
site) allow programming and operating respectively the X-10 UX17A and
UX23A RF-to-IR converters in the mode for controlling up to three
appliances (TV, VCR, DVD, Cable box, and/or Satellite receivers) using
the cable with three IR emitters shipped with those converters. The
<parameters> for ´flux´ and ´fflux´ are <count> <post_delay> followed
by one or more 16-bit hex words.
A few technical details about the CM17A operation:
The CM17A draws its power directly from the serial port and requires no
separate power supply. It is actuated - triggered - by toggling the
serial port´s RTS and DTR control lines 80 times with a specific bit
pattern for the particular command. Following each actuation, the
CM17A by default responds by retransmitting the same RF signal 5 times
- what we´ll call 5 "bursts" - spaced at intervals of about 110 mil‐
liseconds. There are two significant bytes of information encoded in
each burst. The action performed by a transceiver in converting the RF
bursts to a power line signal depends on the type of transceiver, the
number of bursts, and the timing between bursts, but differences are
normally of consequence only for dimming and brightening commands.
Heyu can increase or decrease the number of bursts by repeating the
actuation and/or by cutting off power to the device at the appropriate
time between bursts, and thus is able to force the CM17A to transmit
any arbitrary number of bursts from one on up. This differs from other
CM17A control software like BottleRocket and Flipit which don't attempt
any special timing and merely transmit the default five bursts one or
more times. Unfortunately, multi-tasking operating systems like Linux
and Unix cannot always provide the timing accuracy required, especially
when heavily loaded, so some of Heyu´s burst control features may not
be reliable on all systems.
RF burst control in the range 1 to 5 is provided by the RF_BURSTS con‐
figuration directive for CM17A commands other than ´fdim´, ´fbright´,
and ´farb´. When thus configured, each actuation of the CM17A will send
that many bursts. The default is 5 bursts.
The RF signals transmitted by the CM17A for the ´fon´ and ´foff´ com‐
mands include both the housecode and unitcode. So although for conve‐
nience Heyu supports a units list, the signals will be transceived as
successive individual pairs of address and function codes (in X10
order). E.g., the CM17A command ´heyu fon A1-3´ will be transceived as:
addr A3; func A On; addr A1; func A On; addr A2; func A On
whereas sending the direct command ´heyu on A1-3´ via the CM11A results
in the power line code sequence:
addr A3; addr A1; addr A2; func A On
The ´fdim´ and ´fbright´ CM17A commands on the other hand do not
include the unit code. So in order that a particular unit is
addressed, Heyu first executes a single ´fon´ command, then follows it
with the dim or bright command, transmitting as many bursts as are
specified by the "count" parameter.
To omit the ´fon´ signal from an RF dim/bright sequence, simply omit
the unit number, or if more convenient in a scene or usersyn, prefix
the HU with a ´-´.
With the normal ´fdim´ and ´fbright´ commands, sufficient time is
allowed between each actuation of the CM17A for the transceiver to con‐
vert the RF signal and send it out on the power line. The transceiver
will normally send a separate dim/or bright power line signal for each
actuation and this will be evident in the Heyu monitor.
With the "fast" ´ffdim´ and ´ffbright´ commands, Heyu attempts to space
repeated actuations of the CM17A close enough together that the trans‐
ceiver will consider the RF bursts to be arriving in one continuous
stream - similar to holding down the button on a RF remote - and send
the power line dims or brights in a continuous stream. The resolution
of the standard kernel timer functions in a multitasking OS like Unix
or Linux is usually not fine enough, so a timing loop has to be indi‐
vidually calibrated for each system. To do this, run ´heyu utility
calibrate´ and follow the instructions. (Kernel timers in Linux run‐
ning kernel 2.6 and later appear to have finer resolution and the tim‐
ing loop calibration may or may not be required.) The CM11A can mis-
report the X10 power line dim/bright signals sent by some transceivers
with the fast commands; see the transceiver section below.
Note that the dim/bright count specified for CM17A commands is not
equivalent to the level specified for direct commands to the CM11A.
The actual power line dim/bright signal varies with the varies with the
type of transceiver used and the number of RF bursts - with an RR501
transceiver and the ´ffdim´ command, a count of about 31-32 is required
to span the range of fully bright to fully dim.
Also note that the number of power line dims/brights transmitted by a
transceiver usually increases in steps, i.e., the number of RF bursts
has to be increased by more than one for the next higher number of
power line dims/brights to be transmitted. The transition points are
dependent on both the transceiver and on the number of bursts - you'll
have to generate a table for your particular transceiver by using the
Heyu monitor. Here's a short table generated with the ´ffdim´ command
for some transceivers I have:
Transceived Dim/Bright (Percentage)
Bursts RR501 CM15A TM751
1 6% 6% 12%
2 6 12 12
3 6 12 12
4 12 15 12
5 12 18 12
6 17 22 12
7 22 25 12
8 22 28 24
9 27 30 24
10 27 34 24
The ´fdimbo´ and ´ffdimbo´ commands work by first transmitting an
´foff´ RF signal followed by the specified count of RF bursts. (A
standard X-10 Lamp Module in the Off state responds to power line dims
by first turning on to full brightness before dimming.) If the lamp is
initially on, this method results in a very noticeable blinking of the
lamp off then on again, but it is appreciably faster than first sending
a suffient high count of bright signals to guarantee the lamp is at
full brightness before dimming.
The ´farb´ command allows sending any two arbitrary hex byte codes
(0x00-0xFF) and specifying the number of of bursts in the third parame‐
ter.
The audio/video control functions of remotes like the X-10 UR81A Uni‐
versal Remote in PC mode can be emulated with this command. (The UR81A
transmits 2 bursts of its RF signal in PC mode.)
As previously mentioned, Heyu inserts a delay following each standard
RF transmission to allow time for the transceiver to respond with the
power line signal. The default delay of 850 milliseconds can be
changed with the RF_POST_DELAY directive in the Heyu configuration
file.
Since the desired action from a ´farb´ or ´farw´ RF signal may not
involve a transceiver and power line signals, the delay following this
command is separately specified, with a default of 850 milliseconds.
It may be changed with the RF_FARB_DELAY configuration directive. (The
´heyu pause N.NNN´ command can be used to insert a delay on a command-
by-command basis.)
The ´freset´ command will reset the CM17A to a power-up state in case
of lockup or other malfunction. I've personally never found this to be
necessary, but the command is available "just in case".
Whether or not the CM17A commands themselves are displayed in the moni‐
tor and log file is determined by the configuration directive DIS‐
PLAY_RF_XMIT, which is set to YES by default. One quirk is that
there´s a delay of a second or two in the CM11A before it reports
receiving the power line command from the transceiver. So with
repeated CM17A commands the monitor/log entries for the CM17A commands
and the resulting power line commands sent by the transceiver may not
be properly interleaved. The only workaround for this would be to set
an unreasonably long RF_POST_DELAY.
TRANSCEIVERS
Note: Transceiver firmware revisions may be made at any time by the
manufacturer, usually without notice, so the comments below may or may
not not be valid for any particular transceiver unit. The older TM751
and RR501 transceivers evaluated were acquired about 1997. The newer
ones and the CM15A and V572A were acquired in 2004 and 2005.
The X-10 TM751 is the transceiver most commonly included in X-10 hard‐
ware bundles. It receives a single house code and has a medium RF
reception range. Older models exhibit erratic responses to
dims/brights and depending on the installation location and antenna
orientation may be susceptible to "runaway" dims - a feedback effect
whereby any RF dim signal results in the transceiver sending a continu‐
ous stream of dims over the power line for some period of time or until
it is unplugged from the power line. Newer models seem resistant to
this phenomenon but send a separate 12% power line dim for every so
many RF dim signals received in a stream. This works OK insofar as the
lamp modules are concerned, but a CM11A with firmware version 1 will
report a maximum of three such 12% dims in a row and the dim level
maintained by the Heyu engine can be incorrect. The 12% dim steps
allow about 9 different brightness levels in a standard lamp module.
The X-10 RR501 receives a single housecode and has a medium RF recep‐
tion range. The runaway dim phenomenon has been reported for some
older models, but not to the extent of the TM751. The RR501 seems to
handle well the RF streams transmitted by the "fast" ffdim and ffbright
commands. Older models of the RR501 may not transceive the ´flight‐
soff´ command, but the RF signal for this has never been defined by
X-10 or implemented in any of their remotes. Note that the LightsOff
power line signal is not supported by standard 1-way plug-in lamp mod‐
ules like the LM465, but is supported by wall switches and 2-way lamp
modules. The RR501 sends powerline dims at increments of 6-7%, allow‐
ing about 16 different brightness levels in a standard lamp module.
The V572A transceiver by WGL Designs is an all-housecode transceiver
with an exceptionally long RF receiving range. By default it
transceives all housecodes and units. Transceiving may be disabled for
housecodes and units in ranges 1-8 or 9-16, but to date the software to
do this is available only for MS Windows.
Update: Based on our feedback, WGL Designs has fixed the problems men‐
tioned immediatly below.
The V572A works fine for RF on and off commands but unfortunately I
have found it to be problematic for transceiving RF dims and brights
sent under computer control. The power line dim/bright level it sends
for any given RF dim/bright command is not reproducible and can vary by
a big factor either way. (Manual dimming control with a remote is usu‐
ally not as much of a problem because of the visual feedback from the
lamp.) Update: Fixed in units manufactured after late 2007.
The V572A does not support the on or off RF signal encoding for units
5-8 and 13-16 transmitted by the older 2 and 4 button X10 wireless wall
switches, or any of the switches where the housecode is set with an
internal dial and the unit range with an internal slide switch.
Update: Fixed in units manufactured after late 2007.
The V572A mis-transceives the flightsoff command as if it were the foff
command for unit 1. RF audio/video control signals sent by X-10´s
UR81A "Entertainment Anywhere" universal remote are mis-transceived as
power line commands for housecode ´I´ although not in a one-to-one cor‐
respondence which would allow them to be useful. Update: Fixed in
units manufactured after late 2007.
The CM15A is X-10´s intended replacement for the CM11A. It is con‐
trolled via USB rather than RS232 Serial and support for any OS other
than MS Windows is in its infancy. (Even under Windows there are
numerous problems evident with both the software and the CM15A
firmware.) The CM15A can both send and receive RF signals. Transceiv‐
ing is disabled by default for all housecodes and the ActiveHome Pro
Windows software is required to (selectively) enable them, but once
enabled the CM15A can be disconnected from the computer and used as an
all-housecode transceiver. Its RF receiving range is fairly low, but
some users have improved it with a hardware modification to replace the
short built-in antenna with an external antenna. The CM15A works very
well with all RF commands. After the first few steps it sends power‐
line dims at increments of 3-4%, allowing about 30 different brightness
levels in a standard lamp module. Were it not for the short receiving
range it would be an excellent choice for a transceiver.
RF RECEIVERS
If you have an X-10 MR26A or a WGL W800RF32A RF receiver and an avail‐
able serial port, the RF bytes transmitted by the CM17A (or an RF
remote like the HR12A PalmPad) can be viewed directly by running one of
the following shell scripts in a terminal window. Update: Heyu now
supports these two receivers to input RF data directly. See man page
x10aux(5). The scripts may still be useful if you want to see the raw
RF bytes.
------------ mr26a.sh --(cut here)--------
#! /bin/sh
# Display output (hex) from an X-10 MR26A RF receiver
# Significant bytes are bytes 3 and 4, i.e., XX and YY
# in the displayed sequence "d5 aa XX YY ad"
if [ $# -ne 1 ] ; then
echo "Usage: $0 <serial port>"
exit
fi
echo "Reading MR26A on port: "$1
stty -F $1 9600 cs8 raw cread clocal -parenb -cstopb -echo
cat $1 | xxd -g1 -c5
--------------(cut here)-----------------
------------ w800rf32a.sh --(cut here)---
#! /bin/sh
# Display output (hex) from a WGL W800RF32A RF receiver
# Significant bytes are bytes 1 and 3, i.e., XX and YY
# in the displayed sequence "XX ~XX YY ~YY"
if [ $# -ne 1 ] ; then
echo "Usage: $0 <serial port>"
exit
fi
echo "Reading W800RF32A on port: "$1
stty -F $1 4800 cs8 raw cread clocal -parenb -cstopb -echo
cat $1 | xxd -g1 -c4
--------------(cut here)-----------------
AUTHORS
Charles W. Sullivan (cwsulliv01@heyu.org)
SEE ALSO
http://software.x10.com/pub/manuals/cm17a_protocol.txt
heyu(1), x10config(5), x10scripts(5)
local X10CM17A(5)
