.TH X10SCRIPTS 5 local .SH NAME .B x10scripts\^ - Scripting for HEYU, an X-10 CM11A serial interface control program .SH DESCRIPTION .I Heyu is a program for controlling an X-10 "CM11A" home control device. See the \fIheyu\fP(1) man page for usage information. .PP This page contains information regarding the capabilities of Heyu version 2 for launching scripts upon reception of specified X10 signals or special conditions. (The auxilliary program Xtend by David Shaw which was required by earlier versions of Heyu for this functionality is no longer needed or used.) .PP In order to launch scripts the Heyu state engine daemon must be running. It is started manually by executing \'heyu engine\', or can be configured to start automatically with the \'heyu start\' command by including the directive "START_ENGINE AUTO" in the configuration file. If the Heyu configuration file is changed, the daemon must be restarted by executing \'heyu restart\' - the existing daemon will re-read the configuration file and incorporate the changes. .PP There are six types of scripts which can be launched by Heyu: \fINormal\fP scripts are launched by an X10 function signal, e.g., \'on\', \'off\', etc., which can be either sent or received. \fIAddress\fP scripts are similar to normal scripts but require only an X10 address signal. \fIPowerfail\fP scripts are launched when a temporary interruption of AC power is reported to the computer by the CM11A. \fIRFFlood\fP scripts are launched when an unbroken stream of RF signals are received by the auxiliary input daemon heyu_aux. \fISensorfail\fP scripts are launched when a security sensor (which periodically reports its current state) fails to report in the specified time. \fITimeout\fP scripts are launched at expiration of a user-specified countdown time. .PP The Heyu state engine daemon interprets X10 signals, both those received over the AC power line via the CM11A interface and those sent to the interface by Heyu, and keeps a record of the effect of these signals upon each X10 module identified in an ALIAS directive in the configuration file (or the default module). See the \fIx10config\fP(5) man page for details about this. .PP Heyu classifies each X10 signal by its source, which will be one of the following: .br \fIsndc\fP - Sent from the Heyu command line. .br \fIsnds\fP - Sent by Heyu executed from a normal or address script. (*) .br \fIsndp\fP - Sent by Heyu executed from a power-fail script. (*) .br \fIsndm\fP - Sent by an uploaded macro when initiated by a Timer. .br \fIsndt\fP - Sent by an uploaded macro when initiated by a Trigger. .br \fIsnda\fP - RF transceived to power line code by the heyu_aux daemon. .br \fIrcva\fP - RF signals forwarded from the heyu_aux daemon. .br \fIrcvi\fP - Received over the AC power line. .br \fIrcvt\fP - A Trigger signal which initiated an uploaded macro. .br (*) When that script is launched by the Heyu state engine daemon. .PP Note that a CM11A does NOT report the individual addresses and functions when a macro is executed, only the fact that a macro at EEPROM address XXX has been executed. Heyu determines the individual addresses and functions from a copy of the EEPROM memory image it stores in file \'x10image\' when a schedule is uploaded to the CM11A. .br Neither does the CM11A report the actual X10 signal which triggers a macro, at least not reliably. Again, Heyu determines this from the stored memory image file. (The CM11A firmware allows Heyu to distinguish up to six different triggers for the _same_ macro.) .PP Each X10 module in the system can be in the major states \fIOn\fP, \fIDimmed\fP, and \fIOff\fP. They are not mutually exclusive - a module that is in the \fIDimmed\fP state is also considered to be in the \fIOn\fP state. .PP In addition, there are two minor states: \fIAddressed\fP and \fIChanged\fP. .PP A module is considered to be in the \fIChanged\fP state when the last X10 signal on its housecode caused a change in its major state. .PP Addressing is a feature built into module firmware and emulated in the Heyu state engine. .PP A standard X10 module becomes \fIAddressed\fP when it receives an X10 address code matching its own housecode|unit address. It becomes unaddressed when it receives an X10 address code not matching its own address after having received _any_ X10 function code on the same housecode -or- when it receives the \'alloff\' (all_units_off) function on that housecode. Some, but not all, dimmer modules which support the \'lightsoff\' (all_lights_off) command will become unaddressed after receiving that command. (SwitchLinc and other modules which accept the \'preset\' function automatically unaddress themselves insofar as a subsequent \'preset\' function is concerned immediately after receiving any X10 function code.) .PP The Heyu state engine can execute one or more scripts defined in SCRIPT directives in the configuration file. The word \'script\' as used here encompasses not only shell scripts but also executable binaries and shell commands. .PP The state tables maintained by the Heyu state engine daemon include 16 common flags which can be set or cleared by Heyu commands. The state of one or more flags can be included as part of the conditions determining whether a script is to be executed. Heyu\'s security commands set flags, e.g., \'armed\', \'disarmed\', etc., which can also be tested as part of the launch conditions. If the LONGITUDE and LATITUDE directives are included in the user\'s configuration file, the flags \'night\' and \'dark\' and their negations \'notnight\' and \'notdark\' can also be tested in the launch conditions. .PP The user can choose to run in a mode compatible with the \fIheyuhelper\fP feature of Heyu 1.xx, a mode compatible with (most) Xtend scripts, or with the full features of Heyu scripting. For \fIheyuhelper\fP, put the directive SCRIPT_MODE HEYUHELPER in your configuration file, otherwise specify (or take the default) SCRIPT_MODE SCRIPTS. .PP When SCRIPT_MODE HEYUHELPER is specified, all the other script-oriented directives described below except SCRIPT_SHELL and SCRIPT_CTRL are ignored. If an executable script named \'heyuhelper\' exists on the user\'s path, it is launched every time Heyu receives an X10 function over the AC power line via the CM11A interface. One difference from Heyu 1.xx however is that the heyuhelper script is NOT launched when an uploaded macro is executed. .SH QUICK SCRIPTS For those anxious to get started without having to understand all of Heyu\'s extended scripting features, just take the default for SCRIPT_MODE, add one or more simple SCRIPT directives like the following to your configuration file, and run \'heyu engine\' to start the Heyu state engine (or \'heyu restart\' if it's already running). The simple SCRIPT format for (normal) scripts is: .PP SCRIPT Housecode|unit function :: .PP The Housecode|Unit and function taken together describe for Heyu the \fIlaunch condition\fP, i.e., the condition under which the command line is to be executed. .PP The Housecode|Unit can be an ALIAS defined in the configuration file. .PP Examples: .br SCRIPT porch_light on :: echo "Porch light has been turned on" | mail .PP The above sends an email to you whenever the X10 \'on\' signal for the housecode|unit aliased to \'porch_light\' is received over the power line. .PP SCRIPT C1 off :: play ssb.wav; heyu turn tv_set off .PP When remote X10 signal \'C1 off\' is received, play the Star Spangled Banner .wav file, then turn off the TV set. Users outside the USA can substitute whatever TV station signoff music is typical for their country. :-) .br Note: The \'::\' (two colons) is a mandatory separator between the launch condition (e.g. \'C1 off\') and the command line. .br Unless redirected elsewhere, any text output from a launched script will be written to the log file. .PP Address scripts are similar to normal scripts but the keyword \'address\' is substituted in place of any and all function names. Example: .PP SCRIPT A1 address :: mysound.sh volumeup .br SCRIPT A2 address :: mysound.sh volumedown .PP For powerfail scripts the simple SCRIPT format is: .br SCRIPT -powerfail :: .PP Example: .br SCRIPT -powerfail :: heyu on night_lights .SH ADVANCED SCRIPTS .PP Define for Heyu a script to be launched and the conditions for launching it with a SCRIPT directive in your configuration file. Any number of SCRIPT directives may appear in the configuration file. .PP The format is: .br SCRIPT [-l label] :: [options] .PP tell Heyu under what conditions the script is to be launched. See the section LAUNCH CONDITIONS below for full details. may alternatively (or additionally) be specified with a LAUNCHER directive in the configuration file. .PP Launch conditions are tested in the order they appear in the configuration file. The command line will be executed for the first (and only the first) set of launch conditions which are satisfied, i.e., only one command line can be executed per X10 signal or special condition. .PP The script label is optional so long as all the launch conditions are specified in the SCRIPT directive. If omitted, Heyu will create a label for display purposes of the form \'Script_NN\', where NN is the line number of the SCRIPT directive in the configuration file. If script labels are provided, they must be unique for each SCRIPT directive. .PP A script label is mandatory when any launch conditions are separately specified with a LAUNCHER directive - Heyu needs it to match up the launcher with its corresponding script. But most users probably won\'t bother with the LAUNCHER directives. .br The symbol \'::\' (two colons) is mandatory, to tell Heyu when the list of launch conditions ends and the command line begins. .br When a script is launched, Heyu provides additional environment variables containing information from Heyu\'s record of the state of each module, plus a few other variables to simplify writing the script. The script options allow some variation in the type and format of these environment variables. .PP Script options are: .PP \fI-xtend\fP (or simply \fI-x\fP) - Provide an environment compatible with Xtend scripts. .PP \fI-rawlevel\fP (or simply \fI-r\fP) - Include native dimlevel of modules instead of percentage of full On level in the Heyu environment, i.e., for standard modules 0-210; for preset modules 1-32; for extended code modules 0-62. This option is incompatible with the -xtend option. .PP \fI-noenv\fP (or simply \fI-n\fP) - Provide no environment variables beyond those which already exist in the user\'s environment. .PP \fI-quiet\fP (or simply \fI-q\fP) - Heyu will normally display the script label along with the full command line in the log file when a script is launched. This option directs Heyu to display only the script label - useful if you have a very long command line and don't want to clutter your log file. .PP Script options must be placed between the \'::\' separator and the start of the command line. .PP Example: .br SCRIPT D1 off :: -x myxtend.sh .PP See the section SCRIPT ENVIRONMENT below for a description of these environment variables. .PP .SH LAUNCH CONDITIONS FOR NORMAL SCRIPTS The launch conditions tell Heyu under what conditions a script is to be launched. Each time an X10 function is sent or received (or a power-fail signal is received - more about this in the next section), Heyu will test to see which (if any) of the conditions are satisfied. The testing is performed in the order in which the conditions are specified in the configuration file, and stops once the conditions are matched and a script is launched. .PP For normal scripts, each set of launch conditions specifies the affected housecode|units, the function or functions, optional function mode keywords, the allowed source(s) of the functions, and optional flag conditions. .br HU functions [keywords] [sources] [flags] .PP The housecode|units string \'HU\' must always come first and must always include one or more units even when a function like \'alloff\' (all units off) is specified. (An alias may be used in place of a housecode|units string.) Functions, keywords, and sources may appear in any order after that. .PP Whether included within the SCRIPT directive or separately in LAUNCHER directives, multiple launch conditions for the same script may be continued on the same line by separating each group of conditions with a semicolon (\';'\'), i.e., .br HU functions [keywords] [sources] [flags]; HU functions [keywords] [sources] [flags]; ... .PP Functions which can be specified in a launch condition are any of the native X10 functions: on, off, dim, bright, lightson, lightsoff, alloff, preset, extended, hail, hail_ack, status, status_on, status_off, data_xfer. Also functions allon, xpowerup, and vdata. The general functions \'anyplc\' or \'anyfunc\' in a launch condition will match any of the above. .br RF signals received from X10 security remotes and sensors via the heyu_aux daemon provide the additional functions disarm, arm, alert, clear, panic, slightson, and slightsoff. The general functions \'anysec\' or \'anyfunc\' will match any of these. .PP The \'allon\' function is Heyu-defined and in reality is just the \'on\' signal when sent to all 16 unit codes on a housecode. (Note: \'allon\' as used in Heyu 1.xx is the same as \'lightson\', which is not the case here.) .br The \'xpowerup\' function is sent by X-10 2-way modules like the LM14A and AM14A at power-up following an AC power interruption of at least a few seconds duration. .PP Heyu also defines three \'generic\' functions: gon, goff, and gdim. .PP The generic \'gon\' encompasses any of: on, lightson, allon, preset level 32, or extended preset level 62 or 63. .PP The generic \'goff\' encompasses any of: off, lightsoff, alloff, preset level 1, or extended preset level 0. .PP The generic \'gdim\' encompasses any of: dim, bright, or any preset or extended preset levels between the limits specified for \'gon\' and \'goff\'. .PP One or more functions can be specified in each launch condition. The logic used when the HU contains more than one unit and/or there is more than one function is illustrated in the following example: .PP SCRIPT A1,3 on off flag4 notflag7 :: myscript.sh .br is equivalent to: .PP IF (A1 is addressed OR A3 is addressed) AND .br (function On is received OR function Off is received) .br THEN .br Execute myscript.sh .PP KEYWORD \'trigemu\' .PP If a macro is uploaded to the CM11A EEPROM memory and a powerline trigger (e.g., "A1 on") is defined for it, the macro will only be triggered when the powerline address signal immediately precedes the powerline On function, with no intervening address or function signals. Inclusion of the \'trigemu\' keyword in the launch conditions emulates this behavior. .br Example: If the sequence "Addr A1, Addr A2, Addr A3, Func On A" is received in that order, a script will be launched with the launch condition: .br A2 on .br but not with the launch condition: .br A2 on trigemu .br because the Addr A3 signal intervened between the Addr A2 and the Func On A signals. .br Note: the \'trigemu\' keyword is ignored for lightson, lightsoff, alloff, and extended functions in the launch conditions. .PP KEYWORD \'module\' .PP In the default \'signal\' mode, whether or not a script is launched depends only on reception of the function at the housecode|unit as specified in the launch condition and is independant of the module at that address. .PP Inserting the keyword \'module\' in the launch conditions results in X10 signals being \'filtered\' by the attributes of the modules before the launch conditions are tested. For example, a script otherwise programmed to be launched when the \'dim\' signal is received would not be launched if the module at the particular housecode|unit happened to be an appliance module (as defined in the ALIAS directive). .PP KEYWORD \'changed\'. .PP Inserting the keyword \'changed\' in the launch conditions inhibits launching a script unless the function causes a change in the major state of the module. For example, the launch condition \'A1 off changed\' will not launch the script if the module at A1 is already in the Off state when the \'off\' function is received. .PP In the case of RF signals received from the auxiliary input daemon heyu_aux (source RCVA), any difference in the data from the previous transmission at the same housecode|unit address is considered a change. .PP The keyword \'changed\' automatically implies the filtering otherwise performed when the keyword \'module\' is specified and doesn\'t require separately specifying it. .PP The \'changed\' keyword can also be used by itself without specifying a function, whereupon the script will be launched whenever a major state of the module is changed by any function. .PP SOURCES .PP By default, a script is launched only when the X10 function is received over the AC power line (rcvi) by the CM11A interface. This can be extended to other sources by including one or more source keywords in the launch conditions. For example, \'A1 on sndc\' would launch the script if the function is either received over the power line (per the default rcvi) or sent from the Heyu command line. .PP The source keyword \'anysrc\' can be used to represent the sources sndc, sndm, sndt, sndp, snda, rcvi, rcvt, rcva. It excludes the source \'snds\'. .PP The source \'snds\' can be separately specified if you really have to use it, but ONLY when you have verified that its use won\'t result in a script loop. A script loop WOULD result in the following simple (and obvious) case: .br SCRIPT A1 on rcvi snds :: heyu turn A1 on .PP however the possibility of a script loop may not be quite so obvious when you have multiple and/or more complex SCRIPT directives. .PP Note that the default source or sources can be changed with the LAUNCHER_SOURCE directive in the configuration file. .PP One can disallow default sources by prefixing the source with \'no\', e.g., \'norcvi\', \'nosndm\'. The keyword \'nosrc\' has a special use - it has the function of cancelling out all of the default sources. It must always be accompanied by one or more actual source keywords if a script is to be launched. .PP Warning: Functions with sources \'sndm\' or \'sndt\' are processed by Heyu at the time it receives the signal from the CM11A that a macro has been executed, which may be some time - seconds or even minutes depending on the length of the macro - before the functions are actually transmitted by the CM11A. Thus the state of the modules as recorded by Heyu will be incorrect before the functions are actually transmitted. In addition, the CM11A will not accept further commands while it\'s in the process of transmitting the macro commands, so an attempt to send another command may time out. To avoid these problems, the \'heyu wait\' command can be used to defer execution of a launched script until all macro commands have been transmitted. .br Example: .br SCRIPT A1 on sndm :: heyu wait; (($X10_B2 & $isOn)) && heyu on C3 .PP FLAGS .PP Flags which may be tested as part of the launch conditions are: the 16 common software flags set or cleared by Heyu state commands; the global security flags disarmed, armed, armpending, home, and away; the flags night, dark, and their negations notnight and notdark; plus the "local flag" security switch or low battery condition swhome, swaway, swmin, swmax, and lobat transmitted by security remotes and sensors. (When used by themselves, home or away imply armed.) .br The common flag "true-if-set" keywords are flag1, flag2, ... , flag16. The flag "true-if-clear" ("true-if-reset") keywords are notflag1, notflag2, ... , notflag16. Inclusion of one or more of the flag keywords in the launch conditions means that each flag condition must be TRUE in order for the script to be executed. In other words, the flag condition is AND\'d with all the other launch conditions. .br Examples: .br SCRIPT B1 on rcvi flag4 flag6 notflag8 :: my_command .br In the above, my_command will be executed when the B1 On signal is received only if flags 4 and 6 are set and flag 8 is not set (clear). .br SCRIPT back_door alert armed rcva :: heyu on siren .br In the above, the module controlling a siren is turned on when the back door is opened and the door/window security sensor on that door transmits the alert signal while the system is armed. .br SCRIPT motion_sensor on night :: heyu on porch_light .br The above will turn on the porch_light only if the On signal from the motion_sensor is received between Dusk and Dawn. .br SCRIPT motion_sendsor on dark :: heyu on porch_light .br The above is similar to the previous one, but the condition is that the motion_sensor signal is received between Dusk+Offset and Dawn-Offset, where Offset is defined by the config directive ISDARK_OFFSET. .SH LAUNCH CONDITIONS FOR ADDRESS SCRIPTS Launch conditions are identical to those for normal scripts except the keyword \'address\' is used in place of any and all functions. Neither functions nor the keywords \'changed\', \'signal\' or \'module\' may be specified for address scripts. (Likewise, the keyword \'address\' may not appear in the launch conditions for normal acripts.) The launch conditions may include sources and flags as for normal scripts. .PP Note that the launch conditions for address scripts are evaluated each time an address signal is encountered and those for normal scripts each time a function signal is encountered, so it\'s possible to have multiple script launchings for what might appear to be a single X10 command. .SH LAUNCH CONDITIONS FOR POWERFAIL SCRIPTS For powerfail scripts, the launch conditions always start with the special keyword \'-powerfail\' (note the \'-\' prefix) and may optionally be followed with flag conditions. (Module addresses, functions, and sources are not applicable for powerfail scripts.) .br -powerfail [flags] .PP As with normal scripts, each of the specified flag conditions must be TRUE for the script to be launched, and the same flag1, flag2, ..., flag16 and notflag1, notflag2, ..., notflag16 keywords are valid. Security flags (disarmed, armed, armpending, home, away) may also be tested, however they may not be valid if the computer has been powered down during the power interruption. .br In addition there are two special flags, \'boot\' and \'notboot\' which are valid only for powerfail launchers. The boot flag is set by the Heyu relay daemon at the time it is first started and cleared a few seconds afterwards. .PP If the boot flag is included in the launch condition, then the script will be launched only if the powerfail signal is received immediately following the startup of the Heyu relay daemon, i.e., if the the CM11A is polling for a clock update at the time Heyu is first started. .PP Conversely, if the notboot flag is included in the launch condition, the script will be launched only if the powerfail signal is received after the initial refractory period of a few seconds. .PP If neither the boot nor the notboot flag is included, then the script will be launched regardless of the time the powerfail signal is received. .PP Note: A powerfail script can be launched at startup ONLY if Heyu is started with the \'heyu engine\' or \'heyu start\' commands, else the state engine daemon won\'t be running in time to catch the powerfail signal at startup. .SH LAUNCH CONDITIONS FOR RFFLOOD SCRIPTS An RFflood signal is issued with the "started" flag when an RF flood is first detected, then again at increasing longer intervals while the flood continues. Another RFflood signal is issued with the "ended" flag when the flood ceases. Either of these two flags can be tested in the launch conditions along with the 16 common flags and the global security flags. .br Example: .br -rfflood started .PP Housecode|unit addresses, functions, and sources are not applicable for RFFLOOD script launch conditions. .SH LAUNCH CONDITIONS FOR SENSORFAIL SCRIPTS If Heyu has not received any signal from a security sensor, either a normal alert or its periodic "alive" signal, in the interval specified by the INACTIVE_TIMEOUT directive, it can launch a \'-sensorfail\' script. The 16 common flags and the security flags can be included in the launch conditions. .br Example: .br -sensorfail armed .SH LAUNCH CONDITIONS FOR TIMEOUT SCRIPTS Heyu can launch a script when a countdown timer set by the user reaches zero. The particular timer must be specified. The 16 common flags and the security flags can also be included. .br Example: .br -timeout timer2 flag3 .SH LAUNCHERS Launchers are an alternative way of specifying the launch conditions for a script. They can be useful when you have multiple or very complex sets of launch conditions, otherwise most users will probably find it more convenient (and less confusing) to include all the launch conditions in the SCRIPT directive. .PP The format for a launcher directive in the configuration file is: .br LAUNCHER HU functions [keywords] [sources] [flags]; HU functions [keywords] [sources] [flags]; ... .br where the mandatory script_label (no -l switch is used here) must match the label in the SCRIPT directive to which it applies. .SH SCRIPT ENVIRONMENT for Heyu scripts .PP When the -xtend option is NOT specified, Heyu provides a number of environment variables which can be used by scripts. Here is a summary - see below for descriptions and examples: .br X10CONFIG .br X10_A1 ... X10_P16 .br x10_ ... (Note lower case prefix \'x10_\') .br whatLevel, isAppl, isSpend, isOff, isOn, isAddr, isChg, isDim .br X10_Housecode, X10_Unit, X10_LastUnit, X10_Function, X10_PresetLevel .br X10_Xfunc, X10_Xdata .br X10_BrightVal, X10_DimVal, X10_RawVal .br X10_Flag1, X10_Flag2, ... , X10_Flag16 .br X10_Year, X10_Month, X10_MonthName, X10_Day, X10_Hour, X10_Minute, X10_Second, X10_WeekDay, X10_WeekDayName, X10_isDST, X10_DateString .br X10_DawnTime, X10_DuskTime, X10_SysTime .br X10_isNightTime, X10_isDarkTime .br X10_Vdata, X10_SecLights .br X10_Disarmed, X10_Armed, X10_ArmPending, X10_Home, X10_Away .br X10_swMin, X10_swMax, X10_swHome, X10_swAway, X10_LoBat .br X10_Timer, X10_Sensor .br helper, bighelper .br X10_Expire .PP The environment variable X10CONFIG contains the full pathname of the configuration file in effect for the Heyu state engine. Unless overridden, instances of Heyu executed by a script will therefore automatically use the same configuration file. .PP For each housecode|unit \'Hu\', the state variable \'X10_Hu=heyu_bitmap\' where the bit values in \'heyu_bitmap\' are: .br Bits 0 through 7 represent the module dim level .br 256 Unit is an appliance module, i.e., has no Dim/Bright attribute. .br 512 Status pending bit. .br 1024 Unit is Off .br 2048 Unit is Addressed .br 4096 Unit is Changed .br 8192 Unit is Dimmed .br 16384 Unit is On .PP The module dim level will be either the integer 0 through 100 representing the percentage of full brightness, or the native module level (0-210, 1-32, or 0-62) if the -rawlevel script option is specified. (The dim level for an appliance module will be either the lowest value if it\'s Off or the highest value if it\'s On.) .PP For each single-unit ALIAS defined in the configuration file, the state variable \'x10_=heyu_bitmap\', e.g., .br x10_porch_light= .br where is as described above. .PP Note that the prefix for ALIASes is the lower case \'x10\' to avoid possible conflict with the other Heyu environment variables which are prefixed with the upper case \'X10\'. The configuration directive ENV_ALIAS_PREFIX can be used to revert to the upper case prefix for compatibility with existing scripts if absolutely necessary. .PP Mask variables which can be used to test the state variables without having to remember the bitmap values: \'whatLevel\', \'isAppl\', \'isSpend\', \'isOff\', \'isAddr\', \'isChg\', \'isDim\', and \'isOn\'. .PP Example: In the bash shell, the construct .br (($x10_porch_light & $isOn)) .br will return TRUE ( > 0 ) if the module aliased to porch_light is in the On state, and .br level=$(($x10_porch_light & $whatLevel)) .br will recover the brightness level of the module aliased to porch_light. .PP Note: The bash construct above is compact and convenient, but is not defined by POSIX. Other shells may have to use the POSIX compatible construct: .br [ $(($x10_porch_light & $isOn)) -ne 0 ] .br to test the state of the module. .PP The mask variables should always be used instead of the numeric values for testing the state of a module. The numeric values (for the Heyu environment) may change in a future release of Heyu. (The bit representing \'On\' is however guaranteed to always have the highest numeric value, so that a test for \'On\' like the example in the Xtend documentation $X10_B4>=128 will continue to work so long as the mask is used rather than the numeric value, i.e., $X10_B4>=$isOn.) .PP Details of the function which launched the (normal) script: .br \'X10_Housecode\' (A-P) .br \'X10_Unit\' (1-16) .br \'X10_LastUnit\' (1-16) .br where \'X10_Unit\' is the last unit _in X10 order_ of the addressed units which resulted in launching the script, while \'X10_LastUnit\' is the last addressed unit for that housecode (which may or may not have resulted in launching the script). .br \'X10_Function\' () .br where is one of the following: On, Off, AllOn, AllOff, Dim, Bright, LightsOn, LightsOff, Preset, Extended, Hail, HailAck, Status, StatusOn, StatusOff, DataXfer, xPowerUp, Vdata, Arm, Disarm, Panic, Alert, Clear, sLightsOn, sLightsOff. .PP And only when is \'Preset\': .br \'X10_PresetLevel\' (1-32) .PP And only when is \'Extended\': .br \'X10_Xfunc\' (0-255) .br \'X10_Xdata\' (0-255) .PP And only when is \'Dim\' or \'Bright\': .br \'X10_RawVal\' (2-210) (Unsigned for both Bright and Dim) .br \'X10_DimVal\' (2-210) (+ for Dim, - for Bright) .br \'X10_BrightVal\' (2-210) (+ for Bright, - for Dim) .PP And only when is \'Arm\': .br \'X10_swHome\' Logical (0 or 1) .br \'X10_swAway\' Logical (0 or 1)) .PP And only when is \'Arm\' or \'Alert\' or \'Clear\': .br \'X10_swMin\' Logical (0 or 1) .br \'X10_swMax\' Logical (0 or 1) .PP And only for -timeout scripts: .br \'X10_Timer\' (= timer number 1-16) .PP And only for -sensorfail scripts: .br \'X10_Sensor\' (= Housecode|Unit of sensor) .PP For RF data from security and entertainment transmitters: .br \'X10_Vident\' (0-255) .br \'X10_Vdata\' (0-255) .PP Note: None of the environment variables relating to a housecode|unit and function which launches a script exist for Powerfail, RFFlood, or Timeout scripts. .PP The 16 flag environment variables, X10_Flag1 ... X10_Flag16 have values 1 or 0 when the corresponding flags are respectively set or cleared. .PP The Calendar/Clock variables for today\'s date and time: .br \'X10_Year\' (e.g., 2004), \'X10_Month\' (1-12), \'X10_MonthName\' (Jan, Feb, etc.), \'X10_Day\' (1-31), \'X10_Hour\' (0-23), \'X10_Minute\' (0-59), \'X10_Second\' (0-59), \'X10_WeekDay\' (0-6), \'X10_WeekDayName\' (Sun, Mon, etc.). .br \'X10_isDST\' is a logical variable which is TRUE if Daylight Saving Time is currently in effect. .br \'X10_DateString\' is an ASCII string with the date and time formatted as displayed with events in the Heyu monitor and log file. .PP The variables \'X10_DawnTime\', \'X10_DuskTime\', and \'X10_SysTime\', which have the values for today\'s Dawn and Dusk time and the current system time. All are expressed as seconds after 0:00:00 Civil (wall-clock) Time, although Dawn and Dusk are computed by Heyu only to the nearest minute. .br (Dawn and Dusk are defined by default to be synonymous with sunrise and sunset, although this definition may be changed with the configuration file directive DAWNDUSK_DEF. Their calculation require that the LONGITUDE and LATITUDE of the user\'s location be defined in the configuration file, otherwise these variables will be undefined. They will also be undefined when there is no actual Dawn or Dusk event, as in polar latitudes during various seasons of the year.) .PP The logical variable \'X10_isNightTime\' which is TRUE between the times of Dusk and Dawn. .br The logical variable \'X10_isDarkTime\' which is TRUE between the times of Dusk and Dawn offset by +/- the number of minutes defined by the configuration directive ISDARK_OFFSET. The default is 30 minutes, meaning this variable will be TRUE between Dusk + 30 minutes and Dawn - 30 minutes. .PP Example: SCRIPT motion_detector on :: ( (($X10_SysTime > $X10_DuskTime)) || (($X10_SysTime < $X10_DawnTime)) ) && heyu turn outside_lights on .br will result in turning on the modules aliased to \'outside_lights\' when the motion detector module sends the \'on\' function, but only between Dusk and Dawn. Note: This must all be written on one line. .br Somewhat simpler in this case however is the equivalent: .br SCRIPT motion_detector on :: (($X10_isNightTime)) && heyu turn outside_lights on .PP The variables \'helper\' and \'bighelper\'. These have the same format as the command line argument passed to the heyuhelper script when the directive SCRIPT_MODE HEYUHELPER is chosen, e.g., a1Dim. They allow an existing heyuhelper script to be run under SCRIPT_MODE SCRIPTS by specifying the command line in the SCRIPT directive as .br SCRIPT :: heyuhelper $helper .br or .br SCRIPT :: heyuhelper $bighelper .PP This difference is that \'bighelper\' will supply the housecode|unit for every affected unit as successive command line arguments, whereas \'helper\' will supply the housecode|unit only for the last affected unit, the same as in the heyuhelper feature of Heyu 1.xx. .br For bighelper, the affected unit arguments will appear in reverse X10 unit order, i.e., .br 10, 2, 8, 16, 12, 4, 6, 14, 9, 1, 7, 15, 11, 3, 5, 13 .br so the first script argument will be the same for either helper or bighelper. .PP The environment variable \'X10_Expire\' contains the number of days (0-365) before expiration of an uploaded schedule, or a negative number with the following meaning: .br -1 SCHEDULE_EXPIRED (Schedule must be reloaded) .br -2 NO_EXPIRATION (Schedule contains no timers) .br -3 NO_RECORD_FILE (No schedule has been uploaded) .br -4 BAD_RECORD_FILE (File x10record is corrupted.) .br (These are the same numeric values which would be displayed upon execution of \'heyu upload cronstatus\'.) .SH SCRIPT ENVIRONMENT for Xtend scripts .PP Xtend (http://www.jabberwocky.com/software/xtend/) by David Shaw is an auxilliary program for launching scripts based on received X10 power line signals. Heyu now provides internally all the same functionality (and more) and Xtend is no longer needed. .PP The additional functionality of Heyu requires changes in the environment provided for the script which make it incompatible with scripts written for Xtend. For compatibility with existing Xtend scripts, the -xtend script option tells Heyu to instead supply the more limited but Xtend-compatible environment, as follows: .PP The environment variable X10CONFIG contains the full pathname of the configuration file in effect for the Heyu state engine. Unless overridden, instances of Heyu executed by a script will therefore automatically use the same configuration file. .PP The state variables \'X10_Hu=xtend_bitmap\' for each housecode and unit \'Hu\', where the bits in xtend_bitmap now have these values (which correspond with Xtend\'s): .br 32 Unit is addressed. .br 64 Unit is an appliance module i.e., has no Dim/Bright attributes. .br 128 Unit is On. .PP The three mask variables \'isAddr\', \'isAppl\', and \'isOn\', with values appropriate for Xtend. .SH AUTHORS Charles W. Sullivan (cwsulliv01@heyu.org) .SH SEE ALSO http://www.heyu.org .br heyu(1), x10config(5), x10sched(5), x10scripts(5), x10cm17a(5)