FreeBSD Manual Pages
X10CM17A(5) 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 in- cluded 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 "En- tertainment 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" in- cluded 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 de- lay. 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 ap- pliances (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 ac- tuation 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 or- der). 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 in- clude 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 al- lowed 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 in- volve 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 re- ceiving 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 prop- erly interleaved. The only workaround for this would be to set an un- reasonably 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 re- ception 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 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 trans- ceives 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 in- ternal 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 nu- merous problems evident with both the software and the CM15A firmware.) The CM15A can both send and receive RF signals. Transceiving is dis- abled 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-housec- ode 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 lev- els 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 re- mote 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)
NAME | DESCRIPTION | CM17A COMMANDS | TRANSCEIVERS | RF RECEIVERS | AUTHORS | SEE ALSO
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=x10cm17a&sektion=5&manpath=FreeBSD+Ports+15.0>