DragonFly On-Line Manual Pages
X10CM17A(5) DragonFly File Formats Manual X10CM17A(5)
NAME
x10cm17a - 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
signal 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 emulate 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
commands.
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
transceivers 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
feature 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
transceiver (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 commands 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
website) 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
milliseconds. 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
configuration 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'
commands include both the housecode and unitcode. So although for
convenience 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
convert 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
transceiver 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 individually calibrated for each system. To do this, run 'heyu
utility calibrate' and follow the instructions. (Kernel timers in
Linux running kernel 2.6 and later appear to have finer resolution and
the timing 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
parameter.
The audio/video control functions of remotes like the X-10 UR81A
Universal 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
monitor and log file is determined by the configuration directive
DISPLAY_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
hardware 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
continuous 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
reception 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
'flightsoff' 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 modules like the LM465, but is supported by wall switches and
2-way lamp modules. The RR501 sends powerline dims at increments of
6-7%, allowing 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
mentioned 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
usually 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
correspondence 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
controlled 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.
Transceiving 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 powerline 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
available 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)