- a control program for the X-10 CM11A serial interface
Run 'heyu help' for a description of the Heyu options and commands available in the current version.
The CM11A can remotely control lights and appliances in your house by signaling over the AC house wiring. It can store lists of X10 signals and send them at scheduled times. It can respond to some X10 signals by sending out other X10 signals. With Heyu, it can respond to X10 signals by executing an arbitrary command or script selected by the user.
Limited support is provided for the IBM HD16A, an earlier version of the Home Director without clock or battery backup and known as the CM10A - see special CM10A configuration instructions in the TTY directive section of man page x10config(5).
Heyu supports an auxiliary input device on a second serial port for X10 RF signals. Supported devices are the WGL W800RF32A, the X-10 MR26A, and the RFXCOM X10 RF Receivers.
The W800RF32A is manufactured by WGL & Associates (http://www.wgldesigns.com). It is available in both a 310 MHz version for operation in the USA and Canada and a 433.92 MHz version (W800RF32AE) for European and other countries. It can receive signals from standard, entertainment, and security X10 transmitters.
The X-10 MR26A is usually bundled with a univeral remote in a package by X-10 but is also available individually. It can receive standard and entertainment X10 signals but not security X10 signals.
The RFXCOM X10 receiver is supported in W800RF32 emulation mode and has the same capabilities. It is a USB device but has a built-in FTDI USB-to-Serial converter and communication with it is the same as with a serial port (assuming your OS supports the FTDI chipset, as does Linux).
Heyu also supports the X-10 CM17A "Firecracker", 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.
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. A compile option is provided to compile Heyu without CM17A support for users outside North America or those who simply have no interest in this device. (See the file "INSTALL" included in the Heyu distribution directory.)
Heyu depends on a configuration file to tell it on what serial port the CM11A is connected and to provide it with various other user options. Heyu will not run without the configuration file. See x10config(5) for more information. The standard pathnames Heyu assumes for this file are either $HOME/.heyu/x10config or /etc/heyu/x10.conf, in that order, but the user can specify a non-standard pathname at the command line or with an environment variable. (Operating systems other than Linux may store the configuration file in a different directory by default.) The directory where Heyu finds the configuration file is Heyu's "base" directory. Heyu requires that this directory be writable.
The CM11A connects to a computer via an RS232 serial port (or a USB-to-Serial adapter for newer systems without an RS232 serial port). It can store about 128 events; each event can turn on, turn off, or dim one or more X10 modules. The CM11A box has a battery backed clock which the computer can read. The data is stored in an EEPROM.
You could just put a bunch of Heyu commands in your crontab, but this doesn't work if your system is down for backups, or has crashed, or if someone's tripped over the RS232 cable and unplugged it, and it clutters up the crontab. For most users, it's much easier to upload a schedule of events into the CM11A's EEPROM.
Special note: If you have chosen to locate the Heyu configuration
file under your home directory and then run Heyu commands in crontab,
Heyu won't be able to automatically find the configuration file since
it will be running as user 'root'. In this situation, specify the
full path to the configuration file with either the '-c' Heyu command
line switch or with the environment variable X10CONFIG.
Also, specify the full Heyu executable pathspec, e.g., /usr/local/bin/heyu, if your crontab path does not include the directory where the Heyu executable is located.
The timers and macros to be uploaded the the CM11A's EEPROM are stored in a file. The default is $HOME/.heyu/x10.sched or /etc/heyu/x10.sched. See x10sched(5) for the layout of the file.
X10 modules are identified by a one-letter housecode ranging from A to P (for 16 different codes) and a number from 1 to 16, for a total of 256 possible unit codes. The character '*' is interpreted to mean all units 1-16 (but must be escaped if entered on the command line).
Heyu spawns a relay daemon that gathers the CM11A output for any process that wants it. This allows running the monitor while sending on/off commands. Just as important is that it also catches power fail messages and responds to them immediately.
As of version 2, a state engine daemon may optionally be started which will maintain a record of the state of each module on the system, and which has the capability of executing scripts.
Heyu supports multiple CM11A units connected to different serial ports on the same computer. The configuration files for each CM11A must be stored in different directories - it's usually most convenient to store them in subdirectories /0 through /9 of the normal locations. Each CM11A operates independently of the others (except for communication via the house wiring) and has its own set of associated files.
-v Enable verbose mode
-c <pathname> Specify full configuration file pathname
-s <pathname> Specify full schedule file pathname
-0 ... -9 Look for config file in subdirectory /0 ... /9 of standard location, e.g., $HOME/.heyu/3/x10config
Heyu's commands are divided into Administrative, State, Direct, and CM17A "Firecracker" commands.
Administrative commands generally control some feature of the CM11A or display information from the CM11A, or display information about Heyu or about the user's configuration.
State commands return in various formats information about the state of modules on the user's system which has already been stored in the tables maintained by Heyu Engine. They don't attempt to update these tables. They are primarily intended to be called by scripts. Note however that scripts launched by the Heyu state engine (excluding heyuhelper) are passed an environment which already contains most all the state information. Any of the state commands require that the Heyu state engine daemon (heyu_engine) be running.
Direct commands are used to transmit specific module control instructions out over the AC power line through the CM11A interface.
CM17A "Firecracker" commands transmit X10 RF signals if there is a CM17A device connected to the serial port.
al[iases] Aliases defined in config file
ar[med] Armed status of Heyu
sc[enes] Scenes defined in config file
se[nsors] Sensor health report.
u[sersyns] Usersyns defined in config file
m[odules] H Module attributes, housecode H
l[aunchers] [H] Launcher attributes, all, or housecode H (or -p -s -r -t)
h[ousemap] [H] Overall system state, or details housecode H (*)
da[wndusk] Dawn and Dusk used for 'night' and 'dark' flags (*)
dim[levels] Dim levels of modules as percent brightness (*)
r[awlevels] Native levels of modules (0-210, 1-31, 0-63) (*)
f[lags] Software flags (*)
ti[mers] Countdown times for active timers (*)
ts[tamp] Hu Data and time of last signal to address Hu (*)
g[roups] H Extended code group assignments and levels (*)
x[10sensors] Tabular display of X10 Security sensors (*)
dig[imax] Tabular display of DigiMax sensors (*)
rfxs[ensors] Tabular display of RFXSensor sensors (*)
rfxm[eters] Tabular display of RFXMeter sensors (*)
or[egon] Tabular display of Oregon sensors (*)
ot[hers] Cumulative received address map (*) - clear with
'heyu initothers' or 'heyu initstate'
(*) Require the heyu state engine to be running
Upon successful completion, the following files are written to the
hard drive in Heyu's base directory.
x10record - Heyu's memory of the mode and time of the most recent
uploaded schedule. (This _must_ remain intact for Heyu to know how to
reset the CM11A clock when required.)
x10macroxref - A listing of the EEPROM addresses of uploaded macros for
use by Heyu's state engine and monitor.
x10image - The 1024 byte binary image of the EEPROM. It's also
used by Heyu's state engine and monitor
report.txt - The full details of Heyu's processing of data
uploaded to the EEPROM.
If there are errors in the schedule file, the load will abort without
The upload command with the check option (heyu upload check) will check
the config file and report any errors. The only file written to the
hard drive is the same 'report.txt' mentioned above. (A configuration
file directive can be used to force writing the other files with
a ".check" extension.)
The upload command with the croncheck option (heyu upload croncheck) is only applicable when Heyu is configured to operate in HEYU mode (see
The upload command with the status option (heyu upload status) or the
cronstatus option (heyu upload cronstatus) reports the number of days
before the currently uploaded schedule will expire. These options are
useful primarily when Heyu is configured to operate in HEYU mode,
where the period of validity of the schedule is variable at the user's
option. The difference between the two, i.e., status and cronstatus,
is that 'status' displays a human-readable message whereas 'cronstatus'
displays only the number of days (or an error code) for convenient
parsing in a cron script. The codes are:
>= 0 Number of days until expiration (0 = Today is last day)
-1 SCHEDULE_EXPIRED (Schedule must be reloaded)
-2 NO_EXPIRATION (Schedule contains no timers)
-3 NO_RECORD_FILE (No schedule has been uploaded)
-4 BAD_RECORD_FILE (File x10record is corrupted.)
(*) When that script is launched by the Heyu state engine daemon.
Whenever changes are made to the configuration file, the engine must
be restarted for the changes to be incorporated. (Run 'heyu restart'
to restart it.)
Warning: The record of module states maintained by the state engine can be in disagreement with reality for any number of reasons and should never be relied on for critical applications.
This command will not be needed if Heyu's background processes are initiated with the 'heyu start' command.
'heyu utility syscheck' displays clock/calendar/timezone information obtained
from the system by Heyu. Use this to make sure that your system's time
configuration is what you think it ought to be.
'heyu utility dawndusk' displays the times of Dawn and Dusk for today.
'heyu utility suntable [-r|-c|-n|-a -s -w] [yyyy]' writes a file to the
hard drive containing a daily table of Dawn and Dusk as computed by Heyu for
your Longitude, Latitude, and Timezone, for the current year or for year yyyy.
By default, Dawn and Dusk are as defined by the DAWNDUSK_DEF directive in your
configuration file, times displayed are Civil (i.e., wall-clock) times, and
the table is 80 columns wide.
Switches -r, -c, -n, -a direct Heyu to use the definition of Dawn and Dusk as Rise/set, or as Civil, Nautical, or Astronomical Twilight, respectively, and overriding the definition of Dawn and Dusk in your configuration file.
Switch -s displays times as Standard Time throughout the year instead of Civil Time.
Switch -w writes the table in wide (135 column) format instead of the default 80 columns. (Printing this table on US Letter or A4 size paper requires landscape orientation and an 8-point fixed font.)
'heyu utility calibrate' provides the timing loop calibration needed for
CM17A Firecracker "fast" commands and some experimental commands.
'heyu utility masks' displays the numerical value of the mask environment variables for Heyu and Xtend environments. (For use with 'heyu heyu_state', 'heyu heyu_rawstate', and 'heyu xtend_state'.)
The syntax is:
heyu launch [-e] [-L<n>] <script_label>
For a Normal or Address script, the -e switch instructs Heyu to ignore the functions and addresses and test only the global flags in the launch conditions, as if it were an -exec script.
Each set of launch conditions for a script is tested in the same order
as for a script launched by an X10 signal. For a script with multiple
launchers, the testing can be confined to a single launcher by providing
the launcher number <n> with the -L<n> switch. Launcher numbers start
at 0 for each script and are displayed in square "" brackets following
the script label in 'heyu show launchers' command when there is more
than one. (If there is only one set of launch conditions, the launcher
number will always be 0 and is not displayed.)
For the directive:
SCRIPT -l CheckLights A1-16 on notnight nosrc; B1-16 on notnight nosrc :: ...
heyu launch CheckLights
heyu launch -L1 CheckLights
These commands will display the various states of a module. The parameter is a single-unit housecode|unit string 'Hu' or just a housecode 'H'. (An alias is also accepted.) For the flagstate command, the parameter is just the number of the flag (1-N).
The format for some of the state commands has been changed to the following. See below for the older formats, which are still available.
enginestate State engine daemon is running (1) or not running (0)
armedstate Bitmap: 1 = Armed, 2 = Home, 4 = ArmPending, 8 = tamper
sensorfault Bitmap: 1 = Low battery, 2 = Inactive, 8 = tamper
flagstate n State of flag n as either 1 (set) or 0 (clear)
nightstate State of night flag as 1 (night) or 0 (notnight)
darkstate State of dark flag as 1 (dark) or 0 (notdark)
(Dark is defined by config directive ISDARK_OFFSET)
sunstate Bitmap: 1 = Night, 2 = Dark
In the following, specifying a housecode|unit (Hu) will display the
boolean value 1 or 0 representing that Hu is in or not in that state,
respectively. Specifying only the Housecode will display a unit bitmap
(as an integer) of the units which are in that state, with bit 0
corresponding to unit 1, bit 1 to unit 2, bit 2 to unit 3, etc.
onstate H[u] On state
offstate H[u] Off state (not On)
dimstate H[u] Dim state
addrstate H[u] Addressed state
chgstate H[u] Changed state
fullonstate H[u] Fully On state (On and not Dim)
alertstate H[u] Alert state
clearstate H[u] Clear state
auxalertstate H[u] AuxAlert state
auxclearstate H[u] AuxClear state
lobatstate H[u] Low Battery state for sensors
validstate H[u] Function processed state (*)
activestate H[u] Active state for sensors
inactivestate H[u] Inactive state for sensors
spendstate H[u] Status-pending flags (**)
statusstate H[u] Deprecated - same as spendstate H[u]
(*) validstate H[u] indicates that a signal supported by the module type at H[u] has been sent or received in the Heyu State Engine since Heyu was started.
(**) When Heyu sends or receives a status or xstatus signal, the Heyu
State Engine sets a status-pending flag for the addressed unit in its
state table. When it receives a StatusOn, StatusOff, or xStatusAck return
signal from a 2-way module, it resets this flag for the addressed unit.
If the status-pending flag remains set after an expected response time (which may be a few seconds), it's an indication that something is wrong - possibly a missed signal, a tripped circuit breaker or GFI, or a 2-way module unplugged or simply gone bad.
Note that most common modules are only 1-way and don't respond to a status request. The state of the status-pending flag is therefore meaningless for those modules. Note also that the status-pending flag will NOT be reset for 2-way modules (like many SwitchLinc and LampLinc modules) which return a brightness level rather than a StatusOn/StatusOff signal.
The 'sensorfault' command provides a quick check of sensors defined
by their module types in an ALIAS directive as being security sensors.
A displayed value of 0 indicates all security sensors are operating normally, otherwise the consolidated bitmap with 1 indicates a low battery in one or more sensors, and the bitmap with 2 indicates one or more sensors haven't reported in the elapsed time defined by the INACTIVE_TIMEOUT configuration directive. Run 'heyu show sensors' for a detailed report identifying the individual sensors with problems.
The old format is available for compatibility by setting the configuration directive OLD_STATE_FORMAT to YES. The commands require a housecode|unit parameter Hu and display the output in the heyuhelper style. Example outputs are shown in parentheses for Hu = B8.
onstate Hu State of Hu as either On or Off (b8On, b8Off)
dimstate Hu State of Hu as Dim, On, or Off (b8Dim, b8On, b8Off)
addrstate Hu Addressed state of Hu (b8Addr, b8Unaddr)
chgstate Hu Changed state of Hu (b8Chg, b8Unchg)
The following command displays the state of all units on housecode H
as a 16 character ASCII string. Characters 1-16 represent respectively
the states of Units 1-16, each as a (lower-case) hexadecimal digit
0-0xf formed by adding together the state values On = 8, Dimmed = 4,
Changed = 2, Addressed = 1.
statestr H (8c30000000000000)
The above example indicates H1 is On, H2 is On and Dimmed,
H3 was changed to Off by the most recent command on housecode H
and remains addressed, and H4-16 are all Off and unaddressed.
The following return the current brightness or native level
of module Hu as recorded by the Heyu state engine. (For Hu addresses
of X10 security sensors, the security data byte is returned.)
dimlevel Hu Brighness level of Hu as 0-100% (50)
rawlevel Hu Native level (0-210, 1-32, or 0-63) of Hu (32)
The following return respectively the stored brightness level 0-100%
and stored native level for modules which retain the memory of a
previous setting, e.g., lamp modules which support the Resume or
On-Level feature, or shutter controllers which store a limit value.
The level returned for modules without a memory feature will be just
the maximum level for that module type. (For Hu addresses of two-channel
X10 security sensors configured in dual mode, the security data byte
for the Aux channel is returned.)
memlevel Hu Stored brightness level of Hu as 0-100%
rawmemlevel Hu Stored native level of Hu
counter N Value of counter N
The following return the state bitmap of a module as a decimal integer.
See x10scripts(5) for the meaning of each bit, which differs for Heyu
and Xtend bitmaps. These are the values of the variables provided
in the script environment as 'X10_Hu'.
heyu_state Hu Heyu script environment state bitmap with dimlevel as a percentage of full brightness.
heyu_rawstate Hu Heyu script environment state bitmap with native level (0-210, 1-32, 0-63, 0-15, 0-255).
heyu_vflagstate Hu Heyu script environment vFlag state bitmap
xtend_state Hu Xtend script environment state bitmap
rcstemp H Retrieves the stored value of temperature from an RCS compatible thermometer which has previously been stored in the Heyu Engine state tables by either an automatic report or resulting from a query of the thermometer.
The following command directs the state engine to write an updated
state file to the hard drive.
This command should be required only if the configuration directive
AUTOFETCH has been changed to NO, _and_ it's important to know the
addressed/unaddressed state of a module. Here's why:
The state engine automatically updates the state file whenever an X10 function is sent or received, but not when an X10 address is sent or received until the X10 function which normally follows. The state file is used only when a state command, e.g., 'onstate' or 'dimstate' command is issued from the command line. (The environment variables supplied by Heyu when a script is launched by the state engine are created directly from the engine's memory record and not the state file.)
Of the state commands, only 'addrstate', 'heyu_state',
'xtend_state' report the addressed state of a module or modules.
If the configuration directive AUTOFETCH retains its default value
of YES, these commands will automatically call for an update of the
state file. If AUTOFETCH is changed to NO _and_ an X10 address is
sent or received without a following X10 function, then it will be
necessary to execute 'heyu fetchstate' before the any of the above
mentioned state commands in order for the reported addressed state
to be correct.
Example: If AUTOFETCH is set to NO and the following sequence of
X10 signals is received:
address unit 1 : housecode A
function On : housecode A
address unit 2 : housecode A
Then the command 'heyu addrstate An' will incorrectly show
A1 as addressed and A2 as unaddressed unless 'heyu fetchstate'
is run first.
(The above may be a little confusing but the vast majority of users can safely ignore both the 'fetchstate' command and the AUTOFETCH configuration directive.)
The following state commands retrieve data received from RFXSensors and stored in Heyu's state tables. See man page x10rfxsensors(5) for details.
rfxtemp Hu Stored Temperature
rfxrh Hu Stored Relative Humidity
rfxbp Hu Stored Barometric Pressure
rfxvs Hu Stored Supply Voltage
rfxvad Hu Stored A/D Voltage
rfxvadi Hu Stored internal A/D Voltage
rfxpot Hu Stored Potentiometer setting
rfxtemp2 Hu Stored Second Temperature
rfxlobat Hu Stored Low Battery status (1 = Low, 0 = Normal)
The following state commands retrieve data received from RFXMeters and stored in Heyu's state tables. See man page x10rfxmeters(5) for details.
rfxpower Hu Stored Watt-Hour meter reading.
rfxpanel [N] Stored total Watt-Hour reading for power panel N
rfxwater Hu Stored Water meter reading
rfxgas Hu Stored Gas meter reading
rfxpulse Hu Stored Pulse meter reading
rfxcount Hu Stored raw counter reading
The following state commands retrieve data received from the DigiMax 210 Thermostat. See man page x10digimax(5) for details.
dmxtemp Hu Stored current temperature (C)
dmxsetpoint Hu Stored setpoint temperature (C)
dmxstatus Hu Stored On/Off status (1 = On)
dmxmode Hu Stored Heat/Cool mode (1 = Heat)
The following state commands retrieve data received from Oregon Temperature/Relative Humidity/Barometric Pressure sensors or from Wind or Rain sensors. See man page x10oregon(5) for details.
oretemp Hu Stored temperature reading.
orerh Hu Stored Relative Humidity.
orebp Hu Stored Barometric Pressure.
orewindavsp Hu Stored Wind Average Speed.
orewindsp Hu Stored Wind Instantaneous Speed.
orewinddir Hu Stored Wind Direction angle.
orerainrate Hu Stored Rainfall Rate.
oreraintot Hu Stored Rainfall Total Accumulation.
elscurr Hu Stored Electrisave Current reading.
The following command allows an external program to store Temp/RH/BP data in the state table for a emulation (dummy) Oregon module for processing by Heyu, just as if the data were received from an actual Oregon sensor.
heyu ore_emu Hu <func> <value>
See section "OREGON SENSOR EMULATION" in man page x10oregon(5) for details.
The following command allows an external program to emulate a signal from an X10 Security sensor or remote, as if the signal were received from an actual device.
heyu sec_emu Hu <func> <flags>
where <funct> must be one which is transmitted by the physical
security sensor or remote mapped to Hu. Like other Heyu function names
it must be entered in all lower case.
<func> may be: alert, clear, sectamper, panic, arm, disarm, test, slightson, slightsoff, sdusk, sdawn, akeyon, akeyoff, bkeyon, or bkeyoff.
The <flags> must be specified as they would appear in the monitor/logfile
when an actual RF transmission is received, although they are not case
sensitive and can appear in any order after the <func>. There are
no defaults, e.g., for a door/window sensor with a Min/Max switch, either
swmin or swmax must be specified.
<flags> may be: swmin, swmax, swhome, swaway, main, aux, and lobat as supported by the particular sensor. Do not specify the tamper flag as it is handled differently from the other flags.
Enter 'heyu help' for a complete up-to-date listing of the
commands and their syntax. A number of commands have synonyms which some
users may find easier to remember. Enter 'heyu syn' to see the
synonyms for each command.
Although a few commands are different, the command syntax in general is as follows:
heyu <command> Housecode|Units [<data>]
The usual Housecode|Units address is comprised of a case-insensitive
housecode letter A through P, followed with no intervening spaces by a
list of the particular unit codes to be addressed, ranging from 1 through 16.
Unit code 0 is acceptable (but not necessary) for commands which don't
require any unit codes.
An 'alias' defined in the configuration file can be used in place of
a Housecode|Units string.
For any command, using an underscore ('_') in place of the housecode letter
will direct Heyu to substitute the default housecode defined in the
The units list may consist of a single unit, multiple units delimited
by commas, a range of units separated with a '-' sign, or a combination
of the foregoing.
The following are examples of valid Housecode|Unit addresses:
For commands which apply to all units in a given housecode, the
units list is omitted, e.g.,
heyu lightson B
Direct Command listing (H = Housecode, HU = Housecode|Units):
on HU Turn units ON
off HU Turn units OFF
dim HU <level> Dim by <level> (1-22)
dimb HU <level> Dim to <level> (1-22) after full bright
obdim HU <level> Dim to <level> after on and full bright.
bright HU <level> Brighten by <level> (1-22)
brightb HU <level> Brighten by <level> (1-22) after full bright
lightson H Turn All Lights ON
lightsoff H Turn All Lights OFF (**)
allon H Turn All Units ON
alloff H Turn All Units OFF
turn HU <command> Change state on|off|up|down [vv]
preset HU <level> Preset units to <level> (1-32) (*)
mpreset HU <linked> Limited Preset for uploaded macros
preset_level <level> Preset to <level> (1-32) (function only)
status HU Request ON/OFF status (two-way modules)
status_on HU Status Acknowledge ON
status_off HU Status Acknowledge OFF
hail [H] Hail other devices
hailw [H] Hail other devices, await ack (*)
hail_ack [H] Hail Acknowledge
data_xfer H Data Transfer (function code 0xC)
xon HU Extended Turn Units Full ON (LM14A)
xoff HU Extended Turn Units Full OFF (LM14A)
xpreset HU <level> Extended Preset <level> (0-63) (LM14A)
xallon H Extended All Units ON (LM14A)
xalloff H Extended All Units OFF (LM14A)
xstatus HU Extended Status Request (LM14A)
xconfig H <mode 0-3> Extended Config Auto Status Report (LM14A)
(0 = Off, 1 = Extended, 2 = Standard, 3 = Either)
xpowerup HU Extended Module PowerUp signal (LM14A)
xgrpadd HU G Include HU in group G (0-3) at current level
xgrpaddlvl HU g <level> Include HU in group g (0-3) at level (0-63)
xgrprem HU g[,g,...] Remove HU from group(s) in list.
xgrpremall H g[,g,...] Remove all housecode H from group(s) in list
xgrpexec H G Execute functions for housecode H, group G
xgrpstatus HU G Return level (or Nack) for unit(s) in group G.
(for 2-way modules only)
xfunc <T/F> HU <Data> Extended command - general
xfuncw <T/F> HU <Data> Extended command - general, await ack (*)
address HU [HU [...]] Send HC|Units addresses only (*)
function <command ...> Send command function only
kill_all_hc Send All_Units_Off to All Housecodes
pause N.NNN Pause for N.NNN seconds (*)
sleep N.NNN Sleep for N.NNN seconds (*)
delay NNN Delay for NNN minutes (*)
rdelay [MIN] MAX Delay random time between MIN and MAX minutes (*)
temp_req <query_cmd> Request temperature (RCS compatible) (*)
rcs_req <query_cmd> Request RCS compatible status (*)
vdata HU <Data> Write data to primary byte at address HU (*)
vdatam HU <Data> Write data to memory byte at address HU (*)
arm [parameters] Arm system [home|away] [min|max] (@) (*)
disarm Disarm system (@) (*)
setflag n[,n...] Set one or more flags (@) (*)
clrflag n[,n...] Clear one or more flags (@) (*)
clrspend H[U] Clear status-pending flags for H[U] (*)
clrstatus H[U] Deprecated - same as clrspend
settimer N <hh:mm:ss> Set countdown timer N to hh:mm:ss (@) (*)
clrtimers Reset all countdowns timers to zero (@) (*)
clrtamper Reset the global tamper flag (@) (*)
setcount N <count> Set counter N to count (0-64K) (@) (*)
inccount N Increment counter N by 1 (@) (*)
deccount N Decrement counter N by 1 (@) (*)
(*) Not available for use in uploaded macros.
(**) Many dimmer modules do NOT support this command.
(@) Ignored if the Heyu state engine daemon is not running.
Additionally, if Heyu has been configured to recognize Extended Code
Type 0 (Shutter and Shade) commands:
shopen HU <level> Open shutter to level (0-25) and cancel limit
shopenlim HU <level> Open shutter to level (0-25), enforce limit
shsetlim HU <level> Set limit (0-25) and open shutter to limit
shopenall H Open all shutters fully and cancel limit
shcloseall H Close all shutters fully
(The only module known to support these shutter commands is the 230 Volt, 50 Hz, Marmitek SW10 Shutter Motor Controller sold in Europe, and Marmitek keeps this support a secret.)
Internal engine precommands. These work the same as the corresponding direct commands without the '@' prefix but are used ONLY in the command line of a SCRIPT directive. See the SCRIPT COMMAND LINE section of man page x10scripts(5) for details.
@arm [parameters] Arm system [home|away] [min|max] (*)
@disarm Disarm system
@setflag n[,n...] Set one or more flags (*)
@clrflag n[,n...] Clear one or more flags (*)
@clrspend H[U] Clear status-pending flags for H[U] (*)
@settimer N <hh:mm:ss> Set countdown timer N to hh:mm:ss (*)
@clrtimers Reset all countdown timers to zero (*)
@vdata HU <byte> Write data (0-255) to HU primary address (*)
@vdatam HU <byte> Write data (0-255) to HU memory address (*)
@setcount N <count> Set counter N to count (0-64K) (*)
@inccount N Increment counter N by 1 (*)
@deccount N Decrement counter N by 1 (*)
@decskpz N Decrement counter N by 1 and skip if zero (*)
@decskpnz N Decrement counter N by 1 and skip if not zero (*)
@null Just a place holder - does nothing (*)
More details on a few of these commands:
The 'heyu obdim HU <level>' command is a compound command equivalent to
running the scene 'on HU; bright -H 22; dim -H <level>'. It is intended
to replace the 'dimb HU <level>' command when compatibility of the new
X-10 WS467 Wall Switch (redesigned in 2007) with the original WS467 (and other
dimmers) is required. (The redesigned WS467 cannot be turned on from the Off
state by a dim or bright alone.)
The _turn, _preset, and _status "legacy" commands in earlier versions
of Heyu have been removed.
The 'setflag', 'clrflag', and 'clrstatus' commands are not strictly speaking direct commands because they send nothing to the CM11A and only control software flags in the state engine. They are included with the direct command group so they can be used in scenes and usersyns.
The 'setflag' and 'clrflag' parameter may be a single flag number between 1 and N, e.g., 'heyu setflag 4', or a comma delimited list of numbers or ranges of numbers, e.g., 'heyu setflag 2,3,5-7'. If the state engine daemon is not running, these commands will be silently ignored.
The 'arm' command controls the setting of Heyu global security flags which can be tested as part of the launch conditions for Heyu scripts. These flags are "disarmed", "armed", "notarmed", "armpending", "home" and "away". (The "notarmed" flag is set when either the "disarmed" or "armpending" flag is set.)
The MIN or MAX parameter determines the delay before the system enters
the Armed state. With MIN, the "armed" flag is set immediately. With
MAX, the "armpending" flag is set until the end of the delay time given
by the ARM_MAX_DELAY configuration directive, at which time the flag will
change from "armpending" to "armed". If neither MIN nor MAX is entered
the default is MIN.
When the 'arm' command is issued at the command line, Heyu will issue a warning if any of the configured security door/window or motion sensors are in the Alert state, since many of these sensors will retransmit the Alert signal at their heartbeat intervals.
The HOME or AWAY parameter sets the "home" or "away" flag respectively. If neither HOME nor AWAY is entered, the default is AWAY.
When the 'arm' command is received from an RF Security remote (signal source RCVA), the automatic setting of the global security flags as described above may be disabled with the config directive "ARM_REMOTE MANUAL". This allows using the command to launch a script to customize the arming process, e.g., if doors or windows are open, warn the user and don't arm the system.
The 'disarm' command takes no parameters. It sets the "disarmed" flag and clears all the other global security flags.
If the 'hail' or 'hail_ack' commands are entered without a housecode, Heyu will supply the default housecode from the Heyu configuration file, as if an underscore were entered for the housecode letter.
The Heyu 'turn' command requires using the underscore to
initiate replacement with the default housecode. It supports
the functions on, off, lightson, lightsoff, allon, alloff, dim, dimb,
bright, brightb, or any of the synonyms for these functions.
The 'turn' command also supports the CM17A commands fon, foff, fdim, fbright, flightson, flightsoff, falloff, and the applicable "fast" implementations of these commands.
The Extended Code command 'xconfig' configures the automatic status reporting mode of an X-10 2-way module like the LM14A or AM14A.
The module can be directed to automatically report its status whenever it receives a command which changes its state. The four modes are: 0 = Off; 1 = Report status when an Extended command is received; 2 = Report status when a Standard command is received; 3 = Report status when either a Standard or Extended command is received. (Note that the mode is stored in volatile memory in the module and will be reset to the default mode 0 in the event of a power interruption.)
The Extended Code module power-up signal 'xpowerup' is sent by
X-10 2-way modules like the LM14A and AM14A when they are
powered up following an AC power interruption of at least a few
seconds duration. This signal is included as a direct and macro
command primarily for testing purposes - its primary use is
in launch conditions for a script or shell command to reconfigure
the status reporting mode of the module.
The general Extended Code commands 'xfunc' and 'xfuncw' require
entering the extended Type/Function for the desired function between
the command and the Housecode|Units list. Both the T/F and Data
bytes are entered as hexadecimal digits. Example:
heyu xfunc 31 M12 20
(which is equivalent to 'heyu xpreset M12 32')
The Extended Code Group command 'xgrpadd' allows a module which
supports extended code (Type 3) functions, like the LM14A, to be
assigned to up to four groups (0-3), each with an individual preset
level (0-63). Then a single 'xgrpexec' command executed for a group
will set each member of that group on that housecode to the predefined
preset level. The 'xgrprem' and 'xgrpremall' command removes
either individual units or the entire housecode from one or more groups.
The 'xgrpstatus' command polls a (2-way) module for the extended
preset level for a group stored in the module's (volatile) memory.
heyu xgrpadd A1,9 2
adds modules A1 and A9 to group 2 at their current levels.
heyu xgrpaddlvl A1,2,4 3 40
adds modules A1, A2 and A4 to group 3 at extended preset level 40
heyu xgrpexec A 2
results in modules A1 and A9 simultaneously going to the levels defined for group 2.
heyu xgrprem A9 2
removes A9 from group 2.
heyu xgrprem A1 2,3
removes A1 from groups 2 and 3
heyu xgrpremall A 2,3
removes all modules on housecode A from groups 2 and 3
heyu xgrpstatus A1 3
for 2-way modules will be either acknowledged ("xGrpAck") by A1 with the preset level stored for group 3, or negative-acknowledged ("xGrpNack") if A1 is not a member of group 3.
Details of Extended Codes defined by X-10 are found in their document
xtdcodes.pdf which may be downloaded from their website. (This
document replaced their older XTC798.DOC.)
The (old-style) 'preset' command has a peculiar coding - the
housecode is not part of the function byte as it is for all other
native X10 commands. Since Heyu's 'preset_level', i.e.
preset function-only, command does not take a housecode, it is
programmed simply as:
heyu preset_level <level>
The 'mpreset' command implements the very limited CM11A
support for (old style) 'preset' commands in uploaded macros.
The allowed preset levels are linked with the housecode
according to the following table.
HC Levels supported
A 7, 23
B 8, 24
C 5, 21
D 6, 22
E 9, 25
F 10, 26
G 11, 27
H 12, 28
I 15, 31
J 16, 32
K 13, 29
L 14, 30
M 1, 17
N 2, 18
O 3, 19
P 4, 20
If the 'mpreset' command is executed from the Heyu command
line, the levels are restricted to those shown, for consistancy
with its support in an uploaded macro.
The 'brightb' command (brighten after brightening to 100%)
is essentially useless. It is implemented as a direct command
only because it is a valid (although equally useless) command
in an uploaded macro. A design goal for Heyu is to have the
ability to program any command supported by the CM11A, and to
have a direct command corresponding to each macro command.
(The existance of the brightb macro command is probably just
a side effect of firmware code shared with the dimb command.)
The 'address' command sends one or more module addresses to the
power line with no function code. It is useful for devices like
the various SwitchLinc(TM) modules which require a sequence of
addresses only, with no intervening functions, for programming
them. (There does not appear to be any way to have the CM11A
send only addresses from an uploaded macro in its EEPROM.)
Send individual Housecode|Unit addresses to guarantee the
order in which they are sent.
heyu address F1 B3 B4
The 'function' command sends only the function code for its
argument command, without any module unit addresses. The
housecode is part of the function code, so must be specified.
heyu function on A
The 'kill_all_hc' command sends an 'alloff' command to each
housecode A-P. Its purpose is to put the user's home system in a
known state, with all modules turned off and unaddressed.
The 'pause' command is useful in scenes or usersyns when it's
desireable to insert a short delay between transmissions of commands
defined in the scene/usersyn. Its parameter is decimal seconds
and fractions, with millisecond precision (although not necessarily
millisecond accuracy). It should not be used to insert long delays
as the serial port write lock prevents other Heyu commands from being
executed during the pause interval.
The 'sleep' command is similar to the 'pause' command except that
the serial port write lock is removed during the sleep interval, allowing
other Heyu commands to be executed during the interval. This Heyu
command may be useful for operating systems under which the shell
sleep command accepts only an integer parameter.
The 'delay' and 'rdelay' commands are similar to 'sleep' in that
the port write lock is removed during the interval, but the time is
expressed in integer minutes 0-240. The 'delay' command delays
for a fixed time. The 'rdelay' commands accepts either one or
two parameters, [MIN] and MAX. The delay will be a random time no
shorter than MIN (default 0) and no longer than MAX.
The 'temp_req' command requires as an argument the command used by the particular model of remote thermostat/thermometer to initiate an RCS-compatible temperature report. It will then convert the encoded reply from the thermometer to a temperature and display it on the command line. For the TempLinc(TM) Model 1625 remote thermometer, the command to initiate the report is the 'status' command. For the RCS TX15-B (or newer RCS TXB16) Thermostat, the command to initiate the temperature report is the 'preset' command to level 1 at unit 5. Examples:
For the TempLinc 1625:
heyu temp_req status A1
For the RCS TX15-B:
heyu temp_req preset A5 1
An RCS-compatible remote thermometer encodes the temperature in
the unit code and preset Level of an old-style Preset command
according to the following formula:
temperature = -60 + (level - 1) + 32 * (unit - 11)
(valid for units 11 through 16)
Whether the temperature scale is Celsius or Fahrenheit is
determined by how the thermometer is initially programmed.
The same formula is used in either case.
Since the unit code of the thermometer module itself is
lost, the only way to distinguish between the reports from multiple
thermometers is to assign each to a different housecode.
A (fictitious) unit 0 alias, e.g., 'ALIAS Basement B0', can be
defined to give a name to the location where the temperature is
reported. If the Heyu State Engine is running, the decoded temperature
will be stored at this address, where it can later be recovered
with either the 'heyu dimlevel B0' or 'heyu rawlevel B0' commands.
Or from within a script launched by Heyu, from the value of environment
variable X10_B0 or the environment variable for the alias for this
address, e.g., x10_Basement.
The 'rcs_req' command functions similarly to the 'temp_req'
command. (It is in fact the same command with a different name
and either can be used interchangeably.)
Heyu now has built-in support for interpreting the various status reports received from a RCS TX15-B or TXB16 thermostat. The thermostat can be directed to transmit these reports with the following commands (for a thermostat configured for housecode A):
heyu rcs_req preset A5 1 (temperature)
heyu rcs_req preset A5 2 (setpoint temperature)
heyu rcs_req preset A5 3 (system mode)
heyu rcs_req preset A5 4 (fan mode)
heyu rcs_req preset A5 5 (setback mode)
heyu rcs_req preset A5 6 (setback delta temperature)
Note: the temperature value stored at the unit 0 address location will be the one most recently decoded, whether (room) temperature, setpoint temperature, or setback delta.
See the TX15-B or TXB16 protocol manual for complete details.
The 'settimer' command will accept the countdown time parameter
as either seconds, minutes:seconds, or hours:minutes:seconds. Minutes
and seconds aren't limited to the range 0-59.
The specified countdown time is decremented at each one-second tick of the computer's clock, so the accuracy of the countdown time is only +0/-1 second, depending on when between ticks the timer is set.
When the timer counts down to zero, Heyu will launch a '-timeout' script if one has been specified for that timer in the configuration file. If the timer is reset to zero before timeout, then no script is launched. In the current implementation, the countdown times are not reset to zero when a 'heyu restart' is executed.
The 'setrtimer' command sets a countdown time similar to 'settimer' above, but a random countdown time. It will accept either one or two time parameters, "[MIN] MAX". The coundown time will be a random interval no shorter than MIN (default 1 second) amd no longer than MAX. Both time parameters may be expressed as hh:mm:ss, mm:ss, or just seconds.
Advanced Addressing Options:
Codes are transmitted by the CM11A over the power line in several
chunks of code - one or more address bytes followed by a function
Each address byte includes the housecode and a single unit code.
Each function code redundantly includes the housecode plus the
particular command function. (For extended codes, the function chunk
of code also includes a unit code and the dim level, if any.) So
for commands which apply to all units in the housecode (like the
foregoing "lightson" command) or for extended codes, the address
bytes are normally omitted by Heyu.
For some purposes it may be necessary to send only the function code
for a command which normally requires a units address, or include
a unit address for commands which don't require one. For these
purposes the following syntax has been implemented:
Prefixing the Housecode|Unit address with a '-' sign will suppress
sending the address bytes (equivalent to using the
'heyu function ...' command). While prefixing the Housecode|Unit with
a plus '+' sign will force sending the address bytes. Examples:
heyu lightson +B7,12
heyu off -G7 (or just -G will do)
If a housecode is prefixed with a '+' sign but not followed by
a units list, Heyu will use unit 13. (This is for compatibility
with X-10's ActiveHome(TM) software, which always sends an address
regardless of whether it's needed or not.)
The CM17A commands are merely listed here. See man page x10cm17a(5)
for a complete description.
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 RF Arbitrary 16-bit words.
flux <count> <post-delay> xxxx xxxx ... (*)
The following "fast" CM17A commands require special timing
configuration. See man x10cm17a(5).
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 Abitrary two hex bytes
ffarw xxxx xxxx ... Transmit RF Arbitrary 16-bit words.
fflux <count> <post-delay> xxxx xxxx ... (*)
(*) Note: flux and fflux are similar to farw and ffarw except that the burst count and post-delay are specified on the command line. They are customized for the LUX17/23 front ends to Heyu but are available for general use if convenient.
Heyu must be configured to recognize the CM10A - see the instructions for the TTY directive in man page x10config(5). Once Heyu is thus configured, the CM10A will be properly initialized at startup or in the event of an AC power interruption.
Heyu should now start and run properly.
Unless you have a serial connector "Y" adapter, the CM11A will have to be
This command allows setting the ramp value in the range 0-3. Tests of modules I own show that the ramp value has no effect for the X-10 LM14A and redesigned WS467 modules, whereas the redesigned LM465 module immediately goes to full brightness, the same as programming a preset level of 63, for any preset level and any ramp value other than zero. Modules supporting extended codes from other labels or manufacturers may or may not support the ramp.
The redesigned LM465 (module type LM465-1) supports it; the redesigned WS467 (module type WS467-1) doesn't. The LM14A and AM14A 2-way modules treat it the same as the 'xgrpexec' command, which is all wrong. (The Heyu module types for all the above attempt to model the actual physical device behavior, whether correct or incorrect.)
Heyu extended group commands listed in this man page or in
'heyu help' showing the group parameter as a capital 'G'
may be executed with a group reference.
The following examples illustrate assigning the module A1 to an absolute group (2) or to a group with a reference (2.10), in both cases at their current brightness level.
heyu xgrpadd A1 2
heyu xgrpadd A1 2.10
Then in the latter example, issuing the command 'heyu xgrpexec A 2.10'
will set all members of group 2.10 to the levels stored for that group
in the modules' memory.
The behavior of X-10 extended code devices when assigning relative
groups varies from device type to device type, and it's anyone's
guess whether X-10 will make unannounced changes. The behavior
listed for the following module types is supported by Heyu:
LM14A, AM14A: Assigning a reference to one group automatically
changes all group memberships for that housecode|unit to use the
WS467-1: As above, but the housecode|unit is simultaneously a member of
the absolute group.
LM465-1: Assigning a group reference removes the housecode|unit from
membership in all other groups which don't already use the same
The command 'heyu show group H' will display the group memberships
for all units in Housecode H, absolute and, if assigned, referenced.
Note: There is no provision in the Extended Code protocol for assigning a group reference and level with one command - the module must first be brought to the desired level with the xpreset or dim or bright command and then added to a group at its current level. As a consequence, the 'heyu restore_groups' command can result in a lot of blinking lights when groups with a reference are restored.
Heyu toggles the DTR line and the input line(s) should replicate the "SET"
or "clr" state of the DTR line, e.g., for pin 4 jumpered to pin 9 there
should be displayed:
$ heyu port_line_test
Jumpered pin 4 to 9 1 6 8
Status Line: DTR => RI CD DSR CTS
--- --- --- --- ---
clr => clr clr clr clr
SET => SET clr clr clr
clr => clr clr clr clr
SET => SET clr clr clr
Failure of the serial port to support a given input line is indicated by the state of the line under test being displayed as constantly clr or constantly SET. This is the case under Linux with a USB->Serial adapter containing an older Prolific chip. (Whether this is a hardware bug or a Linux bug is unknown.)
Some PC motherboards have the capability to power up the system when the RI signal is asserted, yet lack the ability in the BIOS to turn off this feature. To prevent the CM11A from inadvertantly powering up a PC like this, run the heyu ri_disable command as the last command (other than heyu stop) before shutting down the PC. Then run the heyu ri_enable command after starting up the PC and Heyu again.
Note that in the event of an interruption of AC power, the CM11A powerup condition is with the RI assertion capability enabled. And Heyu uses the command for enabling the RI line in various places for unrelated reasons.
heyu sendtext A "Hello world."
The additional hardware required is to connect the secondary of a
4 to 8 VAC (RMS) transformer between the Signal Ground (DB9 pin 5) and
Carrier Detect (DB9 pin 1) pins of the serial port to which the CM11A
is connected. (Neither the CM11A nor the CM17A normally use the
Carrier Detect pin.) The polarity of the AC voltage on the CD pin
must be in-phase with the AC power line for the -tr and -tf options
to match the rising and falling zero-crossings respectively, otherwise
they'll work backwards.
An adapter between the CM11A cable and serial port will be required
to make this connection - I use a male/female pair of DB9 solder-type
connectors with corresponding pins joined with 3/4" lengths of bus bar,
and connect to the SG and CD pin bus bars with Radio Shack hook clips.
Note: prudence dictates using an inexpensive serial port add-on card for
experiments like this to reduce the risk to motherboard components.
The output voltage of a transformer may be substantially higher than
its rating (at rated current) when supplying only the very low current
to the serial port pin. Although the RS232 specification allows for a
voltage as high as 25 Volts, PC serial ports are normally operated
between +/- 12 Volts and it would be unwise to exceed that level, and
certainly no higher than 15 Volts peak. (12 Volts peak -> 8.49 Volts RMS.)
Where in the above <tty> is a suffix representing the serial port to
which the CM11A is connected, e.g.,
/dev/ttyS0 -> ttyS0
/dev/usb/ttyUSB0 -> ttyUSB0 (implies a USB-Serial adapter)
('heyu list' will display the LOCKDIR, SPOOLDIR, and SYSBASEDIR compiled into Heyu for your operating system.)
Heyu does not always handle well an X10 command received over the power line
when it's in the middle of sending out a command.