DragonFly On-Line Manual Pages
HEYU(1) DragonFly General Commands Manual HEYU(1)
NAME
Heyu - a control program for the X-10 CM11A serial interface
USAGE
heyu [options] command [parameter(s)]
Run 'heyu help' for a description of the Heyu options and commands
available in the current version.
DESCRIPTION
Heyu is a program for controlling an X-10 CM11A 2-Way Computer
Interface. This is the control device manufactured by X-10 (USA) Inc.
and found in their ActiveHome(TM) CK11A kit. Equivalent (rebranded)
devices have been sold as the IBM HD11A Home Director and the RCA
HC60CRX Home Control Interface. 220 Volt versions of the CM11A are
sold in Europe as variously named CM11x models (depending on AC plug
style) and in the UK as the CM12U.
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. A network version of the RFXCOM
receiver, RFXLAN, is also supported.
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.
OPTIONS
-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
COMMANDS
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.
ADMINISTRATIVE COMMANDS
date Gets current date and time from the CM11A clock/calendar and
displays it in a form suitable for feeding to date(1) as input.
erase Erases the CM11A's EEPROM. All events, macros, etc are
permanently gone.
info Displays the current setting of CM11A's clock, base housecode,
battery timer, and monitored housecode registers. It also
displays the status of the uploaded timer schedule, if any.
help Displays a list of the commands that are available. If executed
with the name of a command as a parameter, it will display the
the syntax for that command only. If executed with the
parameter 'admin', 'state', 'direct', 'cm17a', 'shutter',
'rfxsensor', or 'rfxmeter' it will display only the commands of
that type.
syn Displays built-in synonyms for many of the common direct
commands.
<scene_label>
Executes a scene or user-defined synonym (usersyn) from the
user's configuration file.
show Display various information from the user's configuration file
or about the state of the system. Run 'heyu show' with no other
parameters to see the options available in the current release.
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
upload By itself (heyu upload), the upload command reads timers,
triggers, and macros from the user's schedule file, processes it
and creates a binary memory image, and uploads this image into
the CM11A's EEPROM.
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 changing anything.
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 x10config(5) for a description of the MODE
directive). It repeats the data processing Heyu would do if
'heyu upload check' were executed daily for the next 366 days
and writes a file 'cronreport.txt' to the hard drive with a
daily summary. (Its purpose is to prevent unpleasant surprises
if 'heyu upload' is to be executed automatically as a cron job.)
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.)
catchup
Reads the EEPROM image binary file x10image saved when a
schedule is uploaded and immediately executes in chronological
order the commands in the macros for each timed event scheduled
for today's date, beginning at 00:00 hours and continuing up
until the current system time.
trigger
An uploaded macro can only be executed by an uploaded timer or
if triggered by a powerline command. The 'heyu trigger Hu
on|off' command emulates a powerline trigger by looking up the
trigger condition and macro commands in the x10image and
x10macroxref files saved by Heyu when a schedule is uploaded.
It then executes them as direct commands. Macro delays are
ignored.
macro Using the x10macroxref and x10image files saved when a schedule
is uploaded, 'heyu macro <label>' looks up the commands
comprising the macro with the argument label and immediately
executes them as direct commands. Macro delays are ignored.
monitor
When executed in a separate terminal window, all X10 events sent
and received by the CM11A interface will be displayed in this
window. The output goes to stdout and may be redirected to a
file (however the log file generated by the Heyu state engine
process contains the same information, and more). The events
are time-stamped and identified as to their source with the
following codes:
sndc - Sent from the Heyu command line.
snda - Transceived from RF by the heyu_aux daemon.
snds - Sent by Heyu from within a script. (*)
sndp - Sent by Heyu from within a power-fail script. (*)
sndm - Sent by an uploaded macro when initiated by a Timer.
sndt - Sent by an uploaded macro when initiated by a Trigger.
rcvi - Received over the AC power line.
rcvt - A Trigger signal which initiated an uploaded macro.
rcva - RF signals received from the heyu_aux daemon.
(*) When that script is launched by the Heyu state engine
daemon.
start Starts the Heyu relay daemon and other configured daemons, i.e.,
it will also start the Heyu Engine daemon if the directive
'START_ENGINE AUTO' appears in the configuration file and will
start the Heyu Auxilliary daemon if the 'TTY_AUX ...' directive
appears in the configuration file.
restart
Directs all running Heyu background processes - heyu_relay,
heyu_engine, heyu_aux - plus Heyu monitors, to re-read the
configuration file and incorporate any changes since these
processes were started.
stop Kills the heyu_relay daemon that gathers input from the tty
port. This will also cause heyu_engine, heyu_aux, and any
monitors to stop. It can only kill the processes that you have
permissions to stop.
engine Starts the Heyu state engine daemon, heyu_engine, a background
process which maintains a record of the state of each module
based on X10 signals sent or received, and which can launch
scripts based on these signals. If so enabled in the
configuration file, its output, similar to that of the monitor,
is written to a log file.
This command will not be needed if the directive "START_ENGINE
AUTO" is included in the configuration file and Heyu's
background processes are initiated by running 'heyu start'.
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.
aux Starts the auxiliary daemon heyu_aux, a background process which
allows X10 commands to be input to Heyu via RF signals from a
W800RF32A, MR26A, or RFXCOM serial receiver, or from an RFXLAN
network receiver. The serial port to which the receiver is
connected, or the network address in case of RFXLAN, and the
receiver device type must be specified in the configuration file
with the TTY_AUX directive.
This command will not be needed if Heyu's background processes
are initiated with the 'heyu start' command.
script_ctrl
Globally disables ('heyu script_ctrl disable') or enables ('heyu
script_ctrl enable') launching of scripts by Heyu. This command
overrides the configuration directive SCRIPT_CTRL (or its
default value of ENABLE).
initstate
If no housecode is specified, initializes the entire X10 state
table to zero. With a housecode (heyu initstate H), initializes
the state table to zero for just that housecode.
initothers
Initialize the cumulative received address state table to zero.
reset The default action for reset is to clear the registers in the
the CM11A and to set it to the default housecode defined in the
configuration file. The CM11A will then track state changes for
that housecode in its internal registers. If a housecode is
specified as an argument, the CM11A will be set to track state
changes on that housecode instead. Note that the state recorded
in the CM11A internal registers is completely independent of the
all-housecode states tracked by the Heyu state engine.
setclock
Reads the system clock and loads it into the CM11A. This is
adjusted for local daylight savings time and for the mode of an
uploaded schedule, if any. As of Heyu version 2, the CM11A
clock is maintained on local Standard Time throughout the year.
readclock
Displays the date and time for the CM11A and system clocks. The
raw data from the CM11A clock is adjusted for local daylight
savings time and for the mode of an uploaded schedule, if any.
newbattery
Resets the CM11A battery timer to zero.
purge Cancel any pending delayed macros, i.e., delayed macros which
have been called by a timer or trigger but have not yet been
executed.
clear Clear the CM11A unit status registers for the monitored
housecode.
utility
Several infrequently-used options are available:
'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|-o [-]nn] [-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 or -o [-]nn direct Heyu to use the
definition of Dawn and Dusk as either Sunrise/Sunset, or Civil,
Nautical or Astronomical Twilight, or a specified position of
the Sun centre in angle minutes below the horizon (actually
above the horizon if -nn), respectively, overriding the
definition of Dawn and Dusk from 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'.)
logmsg Writes its quoted-text argument (max length 80 characters) as a
time-stamped entry in the Heyu logfile and on the monitor
screen. (There's no checking to see whether either the engine
or monitor is actually running.) This is primarily intended for
making occasional notes while testing and may or may not play
well if executed in the midst of X10 power line activity. It
will also increase the size of the spool file by a few bytes
more than the length of the text, so should be used sparingly.
Example:
heyu logmsg "Awaiting signals from my new wall switch and
transceiver."
cm10a_init
Manually re-initialize a CM10A interface provided Heyu has been
configured for a CM10A instead of a CM11A. Note that when thus
configured, the Heyu relay should handle this automatically
after a power interruption.
wait Wait until execution of an uploaded macro has completed before
returning. This is primarily intended for use when a script or
shell command is launched by an X10 command executed within an
uploaded macro, i.e., with launch source SNDM or SNDT, when it's
important to be certain that the execution of the macro has been
completed. If the timeout parameter is omitted, the default
timeout is 30 seconds. This command operates by repeatedly
pinging the CM11A once a second until it echoes back the ping
character.
restore_groups
Primarily intended for use following an interruption of AC
power, this command sends the X10 signals to all modules defined
as supporting extended code groups to restore the group
assignments and xconfig mode to the settings preserved in the
X10 state file. (Run 'heyu show groups H' to display the group
settings.)
logtail
Calls the system 'tail' command to display the last N lines of
the Heyu log file. If parameter N is omitted, the default for
the system tail command, typically 10 lines, is displayed. The
directory where the log file is maintained must have been
specified with the LOG_DIR directive in the Heyu configuration
file.
launch Launches a script defined by a SCRIPT directive provided a
restricted subset of the launch conditions are satisfied. For
all scripts, the sources, keywords, and flags other than global
flags are disregarded in the launch conditions.
For a Normal script, function tokens on, off, dim, and changed
are interpreted as representing the on/off/dim/changed state of
the specified module addresses rather than signals. All other
function tokens are disregarded. The launch condition is
satisfied if any one of the state comparisons is TRUE and all
the global flags are TRUE.
For an Address script the launch conditions are satisfied when a
module is in the addressed state and the global flags are true.
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.)
Examples:
For the directive:
SCRIPT -l CheckLights A1-16 on notnight nosrc; B1-16 on
notnight nosrc :: ...
heyu launch CheckLights
heyu launch -L1 CheckLights
version
Prints the version number and then exits.
STATE COMMANDS
These commands are primarily intended for external scripts or programs
to obtain state information from Heyu which has previously been stored
in the state tables maintained by the Heyu engine. Scripts and
programs launched by the Heyu engine already have access to complete
state information via the environment variables passed to them. For a
more human-readable display, use the 'heyu show housemap [H]' command.
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.
fetchstate
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.
DIRECT COMMANDS
Heyu version 2 greatly expands the number of commands which can be
executed directly from the command line. All commands which the CM11A
is capable of sending are now available, although many of them will be
of little use to the average user.
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 configuration file.
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:
A7
B3,5
g2,4,6-9,11,14-16
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.
Examples:
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. Example:
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.
Example:
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)
heyu rcs_req preset A5 7 (outdoor temperature)
heyu rcs_req preset A5 8 (heat setpoint temperature)
heyu rcs_req preset A5 9 (cooling setpoint temperature)
Note: the temperature value stored at the unit 0 address location will
be the one most recently decoded, whether (room) temperature, setpoint
temperature, setback delta, outdoor, heat setpoint or cooling setpoint.
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 code.
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.)
CM17A COMMANDS
Heyu version 2 supports commands to actuate a CM17A device connected to
the serial port to transmit X10 RF signals. (The CM17A is a transmit-
only device; it does not receive RF.) There is no way of detecting the
presence or absence of a CM17A on the serial port other than by 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. These commands will have no effect if the CM17A is
absent other than a short delay. All of them may be used in Heyu
scenes and usersyns.
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.
COMPOUND COMMANDS
Individual Heyu _direct_ commands may be strung together into a command
list and executed with a single invocation of Heyu. To use this
feature, delimit the individual commands with semicolons and enclose
the entire command list within double quotes so it's passed to Heyu in
a single chunk.
EXAMPLES
heyu turn a5 on
Turns X10 module A5 on.
heyu on a5
Same as above
heyu fon a1
Transmits X10 RF On signal via a CM17A device.
heyu turn b7 dim 8
Dims X10 lamp module B7 by 8/22 of its total range.
heyu "on a1; off b1; dim c7 3"
A compound command.
heyu info
Displays CM11A clock time, base housecode and unit status. It also
has a bitmap that shows what it thinks is the state of the X10
modules on the same housecode.
heyu status B1
Returns the status of the 2-way X10 module B1 if the unit replies.
heyu stop
Stops the relay daemon that controls the tty port. The monitor
program and/or state engine daemon will also stop if they are
running. Heyu has to be stopped before running a new version to
avoid 'text busy' messages.
heyu setclock
Sets the CM11A clock to the current time of day per the MODE
specified in the user's config file and the record of an uploaded
schedule, if any.
heyu reset
Sets the CM11A to the default housecode specified in the x10config
file.
heyu reset c
Sets the CM11A to track events on housecode C
heyu newbattery
Resets the CM11A battery timer to zero. (There's no way to set the
CM11A battery timer to any specific time other than 0.)
heyu date
Displays date in date(1) input format. The year is taken from
your system clock. Please don't use this to set your computer's
clock.
CM10A SUPPORT
Heyu provides CM10A support only for Direct commands and applicable
Administrative commands - e.g., the CM10A does not have a clock, so
commands to set or read the clock don't work. (The CM10A includes a
very limited memory for uploaded macros but Heyu does not support this
feature.)
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.
WEB INTERFACE SUPPORT
Heyu endeavors to support web interface development by providing in a
customizable format simple information ("web hooks") about it's
configuration which might otherwise require extensive parsing of the
Heyu configuration file.
heyu webhook
By itself, displays a summary of the available options. Further
details and usage examples are provided in the file
"README.webhook" included with the Heyu source distribution.
HEYU CLEANUP
On occasion, generally due to initial misconfiguration or system crash,
there may exist stale files and/or processes which interfere with the
operation of Heyu. To clean up these files and/or processes, do the
following:
Run 'heyu stop'
Check for any Heyu processes and kill them. Under Linux,
running the command 'ps aux | grep heyu' will display any such
processes.
Run 'heyu list' to display the LOCKDIR and SPOOLDIR directories
compiled into Heyu.
Go into the displayed LOCKDIR directory and, if they exist,
delete files LCK..ttySxx (where ttySxx are serial ports to which
either the CM11A or an RF receiver is connected) and delete any
other files LCK..heyu.*
Go into the displayed SPOOLDIR directory and delete all files
with "heyu" in the filename.
Heyu should now start and run properly.
EXPERIMENTAL STUFF
The following commands don't appear in the 'heyu help' menu or regular
list of commands higher up in this man page. They may be of interest
to some for testing and hacking the CM11A. There is no guarantee they
won't lock up the CM11A or cause it to go into a loop or go up in
smoke. There's also no guarantee these commands won't be eliminated in
later versions of Heyu. (Let us know if you find a good use for any of
them.) Those identified by "(Admin)" work only at the command line;
the others ought to work in scenes and usersyns (but not necessarily in
macros). See also the similarly named section in man page
x10config(5).
heyu status_emu Hu
Execute by a script to emulate the response to a received Status
Request by a module which has no status reporting capability,
e.g., any 1-way module. If the state of module Hu as recorded by
the Heyu engine is is ON, the command sends a StatusOn signal,
otherwise a StatusOff signal. (There are third-party X10
transmitters, e.g., some ACT transmitters, which send a Status
Request and always expect a response.)
heyu rts_pulser <msec_on> <msec_off> <repetitions> (Admin)
This command turns the RTS status line On (high, positive) for
<msec_on> milliseconds, turns it Off (low, negative) for
<msec_off> milliseconds, then repeats the On/Off cycle for a total
of <repetitions> cycles. It is useful for driving an N-channel
MOSFET as an electronic switch.
Unless you have a serial connector "Y" adapter, the CM11A will
have to be disconnected.
heyu xpresetramp HU <level> <ramp>
The document "xtdcode.pdf" on X10's website indicates that the
upper two bits of the data byte for the extended preset dim
command control the rate at which the lamp ramps up to its
programmed brightness level. A previous release of this document
as "XTC798.DOC" showed these bits as "don't care".
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.
heyu xgrpoff H G
This Extended Group command is supposed to turn Off all units in
housecode H which are members of group G. It is included as an
experimental command because most modules either don't support it
or get it wrong.
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 xgrpdim H G
heyu xgrpbright H G
These Extended Group commands are supposed to dim or brighten the
modules in a group by one extended level out of 62 (starting at
the resumed level if Off). They are included as experimental
commands because most modules don't support them. The redesigned
LM465 (module type LM465-1) does support them (approximately); the
other extended code devices don't. In actuality, the number of
these commands required to span the full range 1-62 is phase-
dependent, observed to be about 78 if triggered on the rising zero
crossing (heyu -tr ...) or about 53 if triggered on the falling
zero crossing (heyu -tf ...). These average in the long run to
about 65 with random zero crossings
Group "reference"
X-10's Extended Code protocol allows the total number of groups to
expand beyond four (although any particular housecode|unit is
limited to membership in four) through what they refer to as a
"group reference".
Heyu implements the group reference as a number from 1 through 16
which may be dot-appended to the "absolute" group number for many
of, but not all, the extended code group commands. All groups for
a particular housecode|unit must have the same group reference.
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
same reference.
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 reference.
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 port_line_test (Admin)
Test whether the serial port supports the Ring Indicator (RI)
and/or other serial input status lines. This test is run on the
port itself - no CM11A - and requires hooking a jumper between the
serial port's DTR line (DB-9 pin 4) and one (or more) of the input
status lines to be tested: RI (pin 9), CD (pin 1), DSR (pin 6),
CTS (pin 8).
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.)
heyu ri_disable and heyu ri_enable (Admin)
These commands disable and enable the CM11A feature of asserting
the Ring Indicator (RI) serial line just prior to reporting an X10
signal received over the powerline.
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 ping (Admin)
A quick check to see if the CM11A is responding. It sends the
command to enable the CM11A's serial RI line and waits for the
expected echo.
heyu pausetick
Pauses until the system clock rolls over to the next second.
Sometimes useful in timing commands.
heyu sendbytes xx xx xx ...
Similar to the 'address' command except that the addresses are
entered as hexadecimal bytes housecode|unitcode (encoded value
0x00 - 0xFF). See the X10 protocol.txt document for the encoding.
heyu sendtext H "quoted text string"
Sends a string of quoted ASCII text as addresses on the specified
housecode. Each character in the string is represented by two
address bytes with their unit codes being the high and low nybbles
of the character. The text is transmitted at the phenominal speed
of about 0.9 characters/second and the PC's resources are tied up
while the transmission is taking place. It works only from the
command line - not in a macro and (currently) not in a scene or
usersyn. Perhaps someone will discover a use for this otherwise-
useless experimental command. :-)
Example:
heyu sendtext A "Hello world."
heyu upload imagefile <filename> (Admin)
Uploads any 1024 byte binary image file to the CM11A's EEPROM,
whether created by Heyu or not, including binary image files
created by X-10's ActiveHome software under MS Windows. Note:
there won't be any x10record or x10macroxref files created, nor
are those existing files deleted.
heyu command2cm11a xx xx xx ...
Sends any arbitrary string of hex bytes to the CM11A and attempts
the normal software handshake for commands.
heyu bytes2cm11a xx xx xx ...
Sends any arbitrary string of hex bytes to the CM11A without
making any attempt at the normal handshaking for commands.
heyu reserved (Admin)
There's a bit in the status update block identified as "reserved"
in the X10 protocol.txt and which is normally reset to 0. This
command sets it to 1 to see if it has any effect on anything. (So
far I haven't noticed that it does anything at all, but who
knows.)
heyu powerfailtest boot|notboot (Admin)
Emulate interruption of AC power to the CM11A. This allows
testing of -powerfail scripts without having to actually interrupt
power. The parameter 'boot' or 'notboot' specifies whether to
emulate as if Heyu was just started or already running,
respectively, when power to the CM11A is restored. This command
requires that the Heyu state engine daemon be running. Note that
this command does not update the CM11A clock (or re-initialize a
CM10A) as would be done by the heyu_relay daemon following an
actual power interruption.
options -tr, -tf
Many X10 modules are found to respond differently to commands,
specifically dims and brights, depending on whether the power line
signal begins on the rising or falling zero crossing. Which one
the signal starts at is random with the CM11A and most other
transmitters. With additional hardware, these experimental
options will allow transmission of (direct) commands to
synchronize with only the rising (-tr) or only the falling (-tf)
zero crossing. Fast timing is required so a timing loop will have
to be calibrated by running 'heyu utility calibrate'.
Example:
heyu -tr dim A1 10
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.)
heyu tdim HU <level>, heyu tbright HU <level>
These commands operate as if the dim or bright commands were
issued with the -tr option. They are now deprecated.
ENVIRONMENT
X10CONFIG - Points to a fully qualified file name of your configuration
file, if located elsewhere than in one of the standard places. See
x10config(5) for more information on its makeup.
HEYUSUB - Optionally specifies an additional subdirectory level under
the standard places where the configuration file will be found, i.e.,
$HOME/.heyu/$HEYUSUB/
/etc/heyu/$HEYUSUB/
X10SCHED - Points to a fully qualified file name of your schedule file
(timers and macros), if located elsewhere than in one of the standard
places. See x10sched(5) for more information on its layout.
ASIF_DATE - Instruct Heyu to process the data in your schedule file as
of the specified date ( format yyyymmdd ) instead of the current system
date. (Its primary use is with 'heyu upload check' - to examine the
details when something suspicious is brought to light with the 'heyu
upload croncheck' command.)
FILES
$HOME/.heyu/x10config - Heyu configuration file when in user's home
directory.
SYSBASEDIR/x10.conf - Heyu configuration file when in system-wide
directory.
Included in the same directory as the configuration file are:
x10state - module on/off/dim state file (binary).
x10.sched - default filename for schedule of uploaded timers and
macros.
x10record - record of the uploaded schedule parameters.
x10macroxref - addresses of uploaded macros.
x10image - binary image of the uploaded schedule.
LOCKDIR/LCK..<tty> - lock file for serial port.
LOCKDIR/LCK..heyu.relay.<tty> - lock file for relay process.
LOCKDIR/LCK..heyu.engine.<tty> - lock file for state engine process.
LOCKDIR/LCK..heyu.write.<tty> - lock file for processes that write to
the CM11A
SPOOLDIR/heyu.out.<tty> - fifo file for relay process.
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.)
BUGS
Occasionally the interface will not accept the first command after a
reboot of the CM11A or the computer.
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.
AUTHORS
Re-written to use the CM11A interface by Daniel B. Suthers
(dbs@tanj.com).
Originally written (Known as X10) by Larry Campbell (maynard!campbell).
System V port, ID file, improved display formats, and other cleanup by
John Chmielewski (rogue!jlc). Module aliasing additions by Paul Fox
(pgf@foxharp.boston.ma.us)
Enhanced capability for uploaded schedules, state functions, and
execution of scripts by Charles Sullivan (cwsulliv01@heyu.org)
TRADEMARKS
Heyu is a trademark of Daniel B. Suthers. X10, CM11A, and ActiveHome
are trademarks of X-10 (USA) Inc. TempLinc, SwitchLinc, and LampLinc
are trademarks of Smarthome, Inc. W800RF32A is a trademark of WGL &
Associates.
SEE ALSO
http://www.heyu.org
date(1), x10config(5), x10sched(5), x10scripts(5), x10cm17a(5),
x10aux(5), x10rfxsensors(5)
local HEYU(1)