X10OREGON(5)

x10oregon - Oregon sensor support for HEYU

DESCRIPTION

Heyu is an X10 Automation program for Linux, Unix, and Mac OS X. See man page heyu(1) for usage information. Oregon sensors transmit encoded RF signals for Temperature, Relative Humidity, Barometric Pressure, Wind speed, Rainfall, and other variables. When equipped with a compatible RF receiver, Heyu can receive and decode this information. Also included in the same category are two miscellaneous sensors, the Electrisave CM113 and the OWL CM119, which transmit encoded data from AC current probes in the breaker box.

SYSTEM REQUIREMENTS

To use Oregon sensors with Heyu requires a 433.92 MHz RFXCOM X10 RF receiver and Heyu version 2.3 or greater. Support for the Electrisave CM113 was added in Heyu version 2.7. Support for the OWL CM119 was added in Heyu version 2.8 but also requires the special CM119 option in the RFXCOM receiver.

COMPILER OPTION

Support for Oregon sensors is compiled into Heyu by default. A compiler option can be used to omit this support. See the le INSTALL included in the Heyu distribution source directory for details.

CONFIGURATION

It is assumed that a working installation of Heyu version 2.3 or greater exists on the computer, and that the user has a basic familiarity with Heyu. Include the following directive in the Heyu conguration le: TTY_AUX <serial_port> RFXCOM where <serial_port> is the port where the RFXCOM receiver is connected. The RFXCOM receiver connects to a USB port but includes a USB->Serial converter chip. Start Heyu with heyu start, then open another xterm window and run heyu monitor in it to start the Heyu Monitor. Wait for the sensor to make a transmission, usually about every 40 seconds, and in the Heyu monitor window you should then see something like this (ignoring the date and time): rcva func RFdata : Type ORE_TH1 Ch 1 ID 0x1F Data 0x1a2d101f6027908344 The example is for an Oregon Remote Temperature and Humidity sensor, which is in the group of Oregon sensors using the protocol identied by the mnemonic ORE_TH1. Map the Oregon ID to an otherwise unused housecode and unitcode address with an ALIAS directive in your Heyu conguration le using the module type ORE_xxx corresponding to your sensor group. (A list of Oregon sensor module types appears farther down in this page.) Syntax: ALIAS <label> <Housecode/Unit> <module_type> <ID> Example: ALIAS Attic D5 ORE_TH1 0x1F Run heyu restart to incorporate this change into the running Heyu daemons. Then the next time the sensor makes a transmission you should see (with the above example) something like this: rcva func oreTemp : hu D5 Ch 1 Temp 27.7C (Attic) rcva func oreRH : hu D5 Ch 1 RH 39% (Attic)

STORED OREGON DATA

If the Heyu Engine daemon is running, current Oregon data is stored in the Heyu state tables and displayed in the Heyu log le (if thus congured). Stored data can be retrieved with the (lower case) Heyu state commands corresponding to the displayed function labels. In the following, "Hu" is the Housecode|Unit address to which the sensor has been mapped in the ALIAS directive, or the alias label itself. Examples: heyu oretemp Hu - Temperature heyu orerh Hu - Relative Humidity heyu orebp Hu - Barometric Pressure The command heyu show oregon will display stored data from all congured Oregon units in tabular form.

UNIT SCALING

The native units for output of Oregon sensors are Celsius for temperature, hPa (hectoPascals) for Barometric Pressure, and kilograms for Weight. (See the sections WIND SENSORS and RAIN SENSORS for information about those sensors.) These may be scaled by Heyu to different units with the following conguration le directives: Directive ORE_TSCALE <temp_scale> where <temp_scale> is F[ahrenheit], C[elsius], K[elvin], or R[ankine]. Example: ORE_TSCALE F Directive ORE_BPSCALE <BP_unit> <scale_factor> [<offset>] where <BP_unit> is the name of the new unit, e.g. mmHg, and <scale_factor> is the number by which the BP in hPa is multiplied to get its value in the new unit. Directive ORE_WGTSCALE <Weight_unit> <scale_factor> where <Weight_unit> is the name of the new unit, e.g., Lbs, and <scale_factor> is the number by which the Weight in kilograms is multiplied to get its value in the new unit. Some examples: ORE_BPSCALE mmHg 0.75006158 ORE_BPSCALE inHg 0.029529983 1.06 ORE_BPSCALE millibars 1.0 ORE_WGTSCALE Lbs 2.200 The optional <offset> parameter is added to the BP after scaling. In the USA at least, barometric pressures reported by the National Weather Service are adjusted to the BP at sea level. The offset can be used to approximate this adjustment for altitude. Typical values for BP versus altitude can be found on the Internet.

SUPPORTED OREGON MODEL NUMBERS
The following chart shows the Oregon model numbers known to be supported by the Heyu ORE_xxx module types. Temperature sensors: ORE_T1 : THR128 THR138 THC138 ORE_T1 : (THR128) Brookstone Projection Weather/Clock ORE_T2 : THC238 THN132N THWR288A THRN122N THN122N AW129 AW131 ORE_T2 : Radio Shack P/N 63-1091 Projection Weather/Clock ORE_T3 : THWR800 (Alpha)
Temperature / Humidity sensors: ORE_TH1 : THGN122N THGN123N THGR122NX THGR228N THGR238 THGR268 THGR238N ORE_TH2 : THGR810 THGR800 THGN800 ORE_TH3 : RTGR328N RTGN318 ORE_TH4 : THGR328N (Alpha) ORE_TH5 : WTGR800 ORE_TH6 : THGR918 THGR918N THGRN228NX Temperature / Humidity / Barometric Pressure sensors: ORE_THB1 : BTHR918 (Alpha) ORE_THB2 : BTHR918N BTHR968 Weight sensors ORE_WGT1 : BWR101 BWR102 Wind sensors ORE_WIND1 : WTGR800 ORE_WIND2 : WGR800 (In Oregin model WMR80A Weather Station bundle) ORE_WIND3 : WGR918N (In Oregin model WMR928N Weather Station bundle) Rain sensors ORE_RAIN1 : PCR918N (In Oregon model WMR928N Weather Station bundle) ORE_RAIN2 : PCR800 (In Oregon model WMR80A Weather Station bundle) ORE_RAIN3 : (Alpha) UV sensors ORE_UV1 : UVR138 (Alpha) ORE_UV2 : UVN800 (Alpha) Current sensors ELS_ELEC1 : Electrisave CM113 (See note below.) OWL_ELEC2 : OWL CM119 Module types designated "Alpha" have not yet been tested with actual data. Module type ORE_IGNORE can be used to ignore signals from Oregon sensors which may not be under your control, e.g., signals from a nearby neighbors sensor. An unused Housecode/Unit address must be sacriced. Specify the Oregon IDs for one or more sensors to be ignored. Example: ALIAS Neighbor_Sensors P6 ORE_IGNORE 3C 4E 2A Note: Use of this module type does not prevent RF intereference with signals from your own sensors. See section MULTIPLE OREGON SENSORS below. Note: Its possible for the signal transmitted from an ELS_ELEC1 sensor when the "Check" button is pressed to be confused with that from an Oregon temperature sensor type ORE_T2. Pressing the Check button a second time will generally clear up the confusion. The following module types are Oregon emulation (dummy) modules. See section "OREGON SENSOR EMULATION" below for usage. These modules do not take an ID parameter. ORE_TEMU - Temperature ORE_THEMU - Temperature and Relative Humidity ORE_THBEMU - Temperature and Relative Humidity and Barometric Pressure.

TEMPERATURE, HUMIDITY, and BAROMETRIC PRESSURE SETPOINTS
Temperature, Relative Humidity, and Barometric Pressure Min and/or Max setpoints can be dened for any Oregon sensor by appending parameters "TMIN <setpoint>" and/or "TMAX <setpoint>" and/or "RHMIN <setpoint>" and/or "RHMAX <setpoint>" and/or "BPMIN|BPMINL <setpoint>" and/or
"BPMAX|BPMAXL <setpoint>" to the ALIAS directive line for that sensor in the conguration le. When the data value reported by the sensor falls below or above the respective setpoint, corresponding local ags TMIN, TMAX, RHMIN, RHMAX, BPMIN, and BPMAX are raised which can be tested in the launch conditions for a Heyu script. Examples: ALIAS CrawlSpace B7 ORE_TH2 0x14 TMIN 32F RHMAX 90% ALIAS Attic D5 ORE_T1 0x1F TMAX 90F TMIN 60F Then if the B7 sensor reports a crawl-space temperature lower than 32 Fahrenheit, the TMIN ag will be raised. If the crawl-space humidity exceeds 90%, the RHMAX ag will be raised. And if the D5 sensor reports an attic temperature outside the range 60F - 90F, then the appropriate TMIN or TMAX ag will be raised. If the temperature scale sufx (C, F, K, or R) is omitted from the setpoint, the cong directive "ORE_DATA_ENTRY NATIVE|SCALED" determines whether the scale is the native Celsius scale or that dened by directive ORE_TSCALE. The only scale for relative humidity is %, which may optionally be omitted. The barometric pressure scale dened by the ORE_BPSCALE directive may optionally include an offset to adjust for altitude. If the specied Min or Max setpoint includes the offset, use BPMIN or BPMAX, otherwise use BPMINL or BPMAXL to specify that this is the unadjusted local pressure. In other words, a setpoint specied by BPMIN corresponds to the adjusted value displayed by Heyu, whereas a setpoint specied by BPMINL corresponds to the local value displayed on the sensors LCD screen. A BP setpoint may include the sufx for the units dened in the ORE_BPSCALE directive or the native units "hPa". If the setpoint is specied without a units sufx, the cong directive "ORE_DATA_ENTRY NATIVE|SCALED" determines whether the scale is the native "hPa" or that dened by directive ORE_BPSCALE.

HEYU SCRIPTS

Heyu scripts can be launched by the functions "oretemp", "orerh", and "orebp" the same as any other Heyu function. Similarly the "elscurr", "owlpower", and "owlenergy" functions from the current sensors The launch conditions in the SCRIPT directive must include the source keyword "RCVA" and may optionally include the keyword "changed", any of the 16 common ags, and the global security ags. They may also optionally include the local ags. Examples: SCRIPT L9 oretemp rcva armed away tmin :: my_oretemp.sh SCRIPT L9 orerh changed rcva :: my_orerh.sh Local ags for the Oregon functions are "lobat" for those sensors which transmit a low battery indicator, "tmin"/"tmax" for the "oretemp" function, "rhmin"/"rhmax" for the orerh function, and "bpmin"/"bpmax" for the orebp function. Example: SCRIPT CrawlSpace oretemp tmin :: echo "Freezing pipes" | mail

SCRIPT ENVIRONMENT

Any Heyu script has access to the stored Oregon data values through environment variables linked to the housecode|unit (Hu) and its alias (note lower case x10_) mapped to each Oregon unit. X10_Hu_oreTemp x10_<Hu_alias>_oreTemp X10_Hu_oreBP x10_<Hu_alias>_oreBP X10_Hu_oreRH x10_<Hu_alias>_oreRH X10_Hu_oreLoBat x10_<Hu_alias>_oreLoBat (1 = Low, 0 = OK); X10_Hu_oreWgt x10_<Hu_alias>_oreWgt X10_Hu_oreWindSp x10_<Hu_alias>_oreWindSp X10_Hu_oreWindAvSp x10_<Hu_alias>_oreWindAvSp
X10_Hu_oreWindDir x10_<Hu_alias>_oreWindDir X10_Hu_oreRainRate x10_<Hu_alias>_oreRainRate X10_Hu_oreRainTot x10_<Hu_alias>_oreRainTot X10_Hu_elsCurr x10_<Hu_alias>_elsCurr X10_Hu_owlPower x10_<Hu_alias>_owlPower X10_Hu_owlEnergy x10_<Hu_alias>_owlEnergy For sensor models which transmit this information: X10_Hu_oreCh x10_<Hu_alias>_oreCh (Channel number) X10_Hu_oreBatLvl x10_<Hu_alias>_oreBatLvl X10_Hu_oreForecast x10_<Hu_alias>_oreForecast If a Heyu script is launched by one of the functions "oretemp", "orerh", "orebp", "orewgt", "orewindsp", "orewindavsp", "orewinddir", "orerainrate", "oreraintot", "elscurr", "owlpower", or "owlenergy", the environment will additionally include variables for values and ags without the "Hu" identication, e.g., X10_oreTemp, X10_oreWgt, X10_elsCurr. No variable is created for data which is invalid or "not ready".

CONFIGURATION DIRECTIVES

In addition to the ALIAS and scaling directives mentioned above, the following will also affect Oregon data. See man page x10cong(5). Directive ORE_LOWBATTERY <percent> - Denes for those sensors which transmit a battery level the percentage at or below which Heyu will raise the "LoBat" ag. The default is 20%. Directive HIDE_UNCHANGED YES - Display transmission in the Monitor and Logle only when theres a change from the previous transmission. Directives ORE_CHGBITS_xx dene the amount of change in the data required for it to be identied as "changed". The parameter for these directives is the number of least signicant bits for the data in question, which correspond to: ORE_CHGBITS_T Temperature 0.1C ORE_CHGBITS_RH Relative Humidity 1% ORE_CHGBITS_BP Barometric Pressure 1hPa ORE_CHGBITS_WGT Weight 0.1kg ORE_CHGBITS_WINDSP Wind Speed 0.1meters/second ORE_CHGBITS_WINDAVSP Wind Average Speed 0.1meters/second ORE_CHGBITS_WINDDIR Wind Direction (varies with sensor model) ORE_CHGBITS_RAINRATE Rainfall Rate (varies with sensor model) ORE_CHGBITS_RAINTOT Total Rain (varies with sensor model) ORE_CHGBITS_UV UV Factor 1 (See the sections WIND SENSORS and RAIN SENSORS for details about change bits for those sensor types.) Example: ORE_CHGBITS_T 2 instructs Heyu to report a temperature as "changed" only when theres a difference of 0.2C or more from the previous value. This avoids the situation where even in a relatively constant temperature environment the reported temperature may ip-op back and forth by 0.1C in successive transmissions. The actual value of the data is stored in the Heyu state tables even though its not identied as changed or displayed in the Monitor/Log le. The default for each of the above directives is 1. Directive ORE_DATA_ENTRY NATIVE|SCALED Denes whether Oregon emulation data values (see below) are entered in Oregon native units (Celsius for Temperature, percent for RH, or hectoPascals for BP) or in the scaled units dened by directives ORE_TSCALE and ORE_BPSCALE. This also applies to TMIN and TMAX setpoint temperatures when

the entered temperature does not have a temperature scale sufx.

CURRENT SENSORS

Heyu supports decoding of signals from the Electrisave CM113 and the newer OWL CM119 current sensors when received by an RFXCOM receiver in variable length packet mode. When Heyu receives a signal from these sensors, you will see displayed in the monitor/logle something similar to: rcva func RFdata : Type ELS_ELEC1 Ch 1 ID 0xF5 Data 0x. or rcva func RFdata : Type OWL_ELEC2 Ch 1 ID 0x24 Data 0x. Map the signal to a Housecode|init (Hu) with an ALIAS directive: ALIAS <label> <Hu> ELS_ELEC1 <ID> or ALIAS <label> <Hu> OWL_ELEC2 <ID> Example: ALIAS MyElectric B6 OWL_ELEC2 0x24 Directive ELS_VOLTAGE <voltage> Denes a nominal AC voltage which is multiplied by the current reading of an Electrisave sensor to display a nominal power. The default (or the value 0.0) omits displaying this power. Example: ELS_VOLTAGE 240.0 Since the time relationship between current and voltage is unknown, the units of the displayed power are just "VA" (Volt-Amperes). However this is probably not too different from Wattage for the typical residence which doesnt have large motors running. Directive ELS_CHGBITS_CURR Denes the amount of change in the Electrisave current required for it to be identied as "changed". The parameter is the number of least bits, each corresponding to 0.1 Amperes. The default is 1. The Electrisave CM113 sensor reports measured current (as func "elsCurr"), whereas the OWL CM119 sensor directly reports Power and total Energy usage computed internally in the sensor as functions "owlPower" and "owlEnergy". Directive OWL_VOLTAGE <voltage> Denes a nominal AC voltage which corrects the computation of Power and Energy by an OWL CM119 sensor for nominal voltage other than the default 230.0 Volts Directive OWL_CHGBITS_POWER <nbits> Directive OWL_CHGBITS_ENERGY <nbits> Dene the amount of change in the reported Power or Energy required for it to be identied as "changed". The parameter is the number of least bits, corresponding to 0.001 kW or 0.0001 KWh respectively. Directive OWL_CALIB_POWER <factor> Directive OWL_CALIB_ENERGY <factor> Dene decimal factors by which the Power and Energy values from an OWL sensor are multiplied by Heyu to get a better approximation of the actual Power and Energy. Since the OWL sensor measures only current and the actual AC voltage will usually vary from the nominal depending on time of day and day of the week, it can be useful to choose calibration factors to make the values reported by Heyu agree with the utility company electric meter when compared over a 24 hour or longer interval. The default factors are 1.0 for both directives. Directive OWL_DISPLAY_COUNT YES|NO Determines whether the raw data count is displayed in the monitor/logle for Owl CM119 sensors. The default is NO. HEYU COMMANDS: The most recent values of current, power, or energy are stored in the state table and can be recovered with the commands:

heyu elscurr <Hu> heyu owlpower <Hu> heyu owlenergy <Hu> HEYU ENVIRONMENT: Any Heyu script can retrieve the Electrisave or Owl data via the following environment variables, where Hu is the Housecode|unit to which the sensor is mapped. X10_Hu_elsCurr x10_<Hu-alias>_elsCurr X10_Hu_owlPower x10_<Hu-alias>_owlPower X10_Hu_owlEnergy x10_<Hu-alias>_owlEnergy Scripts launched by one of the sensor functions elscurr, owlpower, or owlenergy will also have the corresponding environmental variable name without the _Hu_, e.g., X10_owlPower. Additionally available are the signal counters which are decremented and cycled 9-0 (or 15-0 if transmitted by pressing the check/test button). X10_elsSigCount X10_owlSigCount

WIND SENSORS

There are currently three different protocols extant for Oregon Wind Sensors data: Wind1, Wind2, and Wind3. These are identied by "RFdata:Type" and decoded by the Heyu module types: ORE_WIND1 ORE_WIND2 ORE_WIND3 Having identied the protocol and ID byte from the RFdata:Type displayed in the monitor/logle, map the sensor to a housecode|unit address with an ALIAS directive, e.g., ALIAS MyWind D3 ORE_WIND2 0x48 Transmissions from wind sensors are single RF bursts and will be ignored if the <min_count> in directive AUX_REPCOUNTS is set greater than 1. The main difference between protocols insofar as the data is concerned is the wind direction. The Wind1 and Wind2 sensors report the direction as one of 16 compass points 22.5 degrees apart, whereas Wind3 sensors report the direction as degrees 0-359 with a precision of 1 degree. Therefore each bit specied with directive ORE_CHGBITS_WDIR will correspond to 22.5 degrees for Wind1 and Wind2 or 1 degree for Wind3. Directive ORE_WINDDIR_MODE DEGREES|POINTS|BOTH Instructs Heyu whether to display wind direction as degrees (0-359.9) or compass points (e.g., N, NE, NNE, etc.) or both. The default is BOTH. Directive ORE_WINDSCALE <units_label> <scale_factor> Converts the wind sensor native units m/s (meters/second) into different units. Some common examples (courtesy of the Unix units program): ORE_WINDSCALE mph 2.2369363 ORE_WINDSCALE kph 3.6 ORE_WINDSCALE furlongs/fortnight 6012.8848 Directive ORE_WINDSENSOR_DIR <degrees> Oregons setup instructions call for the wind sensor to be mounted pointing due North. If this is not possible, use this directive to dene the direction (+/- 0-359 degrees from due North) your sensor is actually pointing. This will correct the wind direction displayed by Heyu (although not that displayed in a Oregon Weather Base Station). For Wind1 and Wind2 sensors, best results will be obtained if the sensor can be mounted pointing towards one of the 16 compass points. Directive ORE_DISPLAY_BEAUFORT YES|NO
In addition to the scaled wind speeds, the speeds on the (nonlinear) Beaufort scale (0-12) will be displayed in the monitor/logle. The default is NO. Directive ORE_DISPLAY_COUNT YES|NO With the parameter YES, the actual sensor data readings for wind speed and average speed are displayed in square brackets in the monitor/logle. The default is NO. Directive ORE_CHGBITS_WINDSP <nbits> Directive ORE_CHGBITS_WINDAVSP <nbits> Directive ORE_CHGBITS_WINDDIR <nbits> These directives dene the amount of change in the variable required for it to be marked as "changed", expressed as the number of least signicant bits in the difference between successive values. For ORE_CHGBITS_WINDSP and ORE_CHGBITS_WINDAVSP, each bit corresponds to 0.1 meters/sec. For ORE_CHGBITS_WINDDIR and Wind1 or Wind2 sensors, each bit corresponds to 1 compass point (22.5 deg), while for Wind3 sensors, each bit corresponds to 1 degree. HEYU COMMANDS: The lowercase functions orewindavsp, orewindsp, orewinddir can be executed as Heyu commands to recover the most recent data stored in the Heyu state tables. Example: heyu orewindsp E2 The command heyu show oregon displays the stored data for all Oregon sensors in tabular form. The command heyu show sensors displays the Active/Inactive state and battery state of all sensors along with the timestamp of the last received signal. HEYU SCRIPTS: The lowercase functions orewindavsp, orewindsp, and orewinddir can be used in a SCRIPT directive the same as any other Heyu function to launch a Heyu script. Example: SCRIPT E2 orewindsp rcva :: <my command line> Global ags and local ags "lobat" and "changed" can be included in the launch conditions as required. The source "rcva" must be included (unless it has been congured as a default source). HEYU ENVIRONMENT: Any Heyu script can retrieve the Wind data via the following environment variables, where Hu is the Housecode|unit to which the sensor is mapped. X10_Hu_oreWindAvSp x10_<Hu-alias>_oreWindAvSp X10_Hu_oreWindSp x10_<Hu-alias>_oreWindSp X10_Hu_oreWindDir x10_<Hu-alias>_oreWindDir Scripts launched by one of the sensor functions orewindavsp, orewindsp, or orewinddir will also have the corresponding environmental variable name without the _Hu_, e.g., X10_oreWindSp

RAIN SENSORS

There are currently three different protocols extant for Oregon Rain Sensors data: Rain1, Rain2, and Rain3. These are identied by "RFdata:Type" and decoded by the Heyu module types: ORE_RAIN1 ORE_RAIN2 ORE_RAIN3 Having identied the protocol and ID byte from the RFdata:Type displayed in the monitor/logle, map the sensor to a housecode|unit address with an ALIAS directive, e.g., ALIAS MyRain D3 ORE_RAIN2 0x4E Transmissions from rain sensors are single RF bursts and will be ignored if the <min_count> in directive AUX_REPCOUNTS is set greater than 1.
Mechanically, all the sensors work with a bucket arrangement. When a bucket is lled with a certain amount of rain water, it tips and dumps its contents and the tip is counted. The main difference between the protocols insofar as data is concerned is in the native units. For Rain1, the units are millimeters/hr and millimeters with a precision of 1 millimeter(/hr). For Rain2 and Rain3, the units are inches/hr and inches with a precision of 0.001 inch(/hr). What somewhat confuses things is that for Rain2 at least, the total rain count is not incremented by the exact same amount for each tip of the bucket. The increments 39, 40, 43, 44 (i.e., 0.039, 0.040, 0.043, 0.044 inches) appear in what seems to be a complex pattern which is yet to be comprehended. Directive ORE_RAINRATESCALE <units_label> <scale_factor> Directive ORE_RAINTOTSCALE <units_label> <scale_factor> By default the rainfall rate and total rainfall are displayed in the native units, which for the Rain1 protocol is mm(/hr) while for the others it is inches(/hr). This directives allow display in any arbitrary units by providing the name for the units and the scale factor by which the native units are multiplied to convert to the new units. Some common units and scale factors (courtesy of the Unix "units" program): For Rain1: ORE_RAINRATESCALE inches/hr 0.039370079 ORE_RAINTOTSCALE inches 0.039370079 For Rain2 or Rain3: ORE_RAINRATESCALE mm/hr 25.4 ORE_RAINTOTSCALE mm 25.4 Directive ORE_DISPLAY_COUNT YES|NO With the parameter YES, the actual sensor data readings for rain rate and total rain are displayed in square brackets in the monitor/logle. The default is NO. Directive ORE_CHGBITS_RAINRATE <nbits> Directive ORE_CHGBITS_RAINTOT <nbits> These directives dene the difference between the current and previous raw data reading required for the data to be marked as "changed". The default is 1 for both. For Rain1: ORE_CHGBITS_RAINRATE <nbits> (Each bit is 1 mm/hr) ORE_CHGBITS_RAINTOT <nbits> (Each bit is 1 bucket tip = 1 mm) For Rain2 or Rain3: ORE_CHGBITS_RAINRATE <nbits> (Each bit is 0.01 inch/hr) ORE_CHGBITS_RAINTOT <nbits> (Each bit is 1 bucket tip = 0.04 inch) FLAGS: Each sensor has a battery monitor. For Rain2 and Rain3, a low-battery indicator is transmitted and Heyu will display the LoBat ag with the data when it is received. For Rain1, the battery level 0-100% is transmitted (and by default is displayed with the data). The conguration directive ORE_LOWBATTERY denes the level (default 20%) at or below which the LoBat ag is raised and displayed. When the total rain counter rolls over to zero, the Heyu "rollover" ag is raised and displayed. For Rain2, rollover has been determined to occur after an accumulation of 393.70 inches, which appears to be a strange number until the realization that its equivalent to 10000 millimeters. The Rain1 and Rain3 rollover points are assumed to be the same as for Rain2, but this has not been veried. HEYU COMMANDS: The lowercase functions orerainrate and oreraintot can be executed as Heyu commands to recover the most recent data stored in the Heyu state tables. Example: heyu oreraintot E2 The command heyu show oregon displays the stored data for all Oregon sensors in tabular form. The command heyu show sensors displays the Active/Inactive state and battery state of all sensors along

with the timestamp of the last received signal. HEYU SCRIPTS: The lowercase functions orerainrate and oreraintot can be used in a SCRIPT directive the same as any other Heyu function to launch a Heyu script. Example: SCRIPT E2 oreraintot rcva :: <my command line> Global ags and local ags "lobat" and "changed" can be included in the launch conditions as required. The source "rcva" must be included (unless it has been congured as a default source). HEYU ENVIRONMENT: Any Heyu script can retrieve the Wind data via the following environment variables, where Hu is the Housecode|unit to which the sensor is mapped. X10_Hu_oreRainRate x10_<Hu-alias>_oreRainRate X10_Hu_oreRainTot x10_<Hu-alias>_oreRainTot Scripts launched by one of the sensor functions orerainrate oreraintot will also have the corresponding environmental variable name without the _Hu_, e.g., X10_oreRainRate
APPLICABLE OLDER DIRECTIVES for WIND and RAIN sensors.
Directive HIDE_UNCHANGED YES|NO Determines whether unchanged data signals are displayed in the Heyu monitor/logle. Directive INACTIVE_TIMEOUT <hh:mm:ss> Any sensor with a heartbeat will be reported as Inactive if no signals have been received from it within the specied timeout (default is 4 hours). Directive ORE_DISPLAY_BATLVL YES|NO Determines whether the battery level 0-100% is displayed in the monitor/logle for those sensor models which report a battery level as opposed to just a low-battery ag. The default is YES. The LoBat ag is unaffected by this directive. (The battery level dened with directive ORE_LOWBATTERY denes the level at or below which the LoBat ag will be raised.) Directive ORE_DISPLAY_CHAN YES|NO Determines whether the Oregon channel number is displayed in the monitor/logle. (The Wind and Rain sensors have no channel and are assigned by Heyu to be Channel 1.) The default is YES. Directive DISPLAY_SENSOR_INTV YES|NO Determines whether the time elapsed between the current and previous signals is displayed in the monitor/logle. The default is NO.

OREGON SENSOR EMULATION

An external program can store Temp/RH/BP data in the state table for an emulation (dummy) Oregon module for processing by Heyu, just as if the data were received from an actual Oregon sensor. The available emulation modules (described previously) are ORE_TEMU, ORE_THEMU, and ORE_THBEMU which are mapped to a housecode|unit address with an ALIAS directive, similar to an actual Oregon sensor. To store data, use the command: heyu ore_emu Hu <func> <value> where: Hu is the address to which one of the following emulation modules has been mapped with an ALIAS conguration directive, or its alias label. <func> is oretemp, orerh, or orebp. <value> is the numerical value of the Temperature, RH, or BP data. (Temperature may optionally have an appended scale sufx C, F, K, or R.)

The conguration directive ORE_DATA_ENTRY determines the units in which Heyu expects the data values to be entered, unless for Temperature it has been overridden by a scale sufx. With the default "ORE_DATA_ENTRY NATIVE", the data is entered in the native units for Oregon sensors, i.e., Celsius for Temperature, percent for RH, and hectoPascals (hPa) for BP. With "ORE_DATA_ENTRY SCALED", data is entered in the units dened by conguration directives ORE_TSCALE and ORE_BPSCALE. Note that with unit conversion and rounding between scaled and native units, the displayed value of the scaled data may be slightly different than what is entered. Entered BP data is expected to be the local value, without the offset (typically for adjustment to sea level) which is optionally specied with ORE_BPSCALE. (The offset is applied to the value displayed in the monitor or log le and to the Heyu environment variables when a script is launched.) Example: In the Heyu cong le: ALIAS basement D4 ORE_THEMU ORE_DATA_ENTRY SCALED ORE_TSCALE F At the command prompt: heyu ore_emu basement oretemp 65.0 heyu ore_emu basement orerh 50 The signal will appear in the logle and monitor with source SNDC. Remember to include this in the launch conditions if the signal is expected to launch a Heyu script.

MULTIPLE OREGON SENSORS

If multiple Oregon sensors are to be used, they should be different models and/or set to different channel numbers so each has a different transmission interval (and not an interval which is an integer multiple of another interval). Not doing so risks having "blackout" periods during which the RF signals from two or more sensors with the same transmission interval interfere with each other over an extended period of time. The transmission interval for Oregon sensors is typically 30, 40 or 60 seconds offset by an interval depending on the channel number. E.g., here are the nominal intervals in seconds for several Oregon models. (Users owning other models are encouraged to submit the information for those models so we can expand this table.) Model ORE_ Ch 1 Ch 2 Ch 3 Ch 4 Ch 5 Ch 6 Ch 7 Ch 8 Ch 9 Ch 10 -------- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---THR138 TTHRN122N TTHN122N TTHN132N TTHGR122NX THTHGN123N THTHGR228N THTHGR238 TH1 ?? ?? ?? THGR238N THTHGR810 TH93 THGR800 THTHGN800 TH(WMR80A Weather Station) RTGN318 TH(BAR800 Weather Station) RTGR328N THTHGR918N TH(WMR968N Weather Station) BTHR968 THBBTHR918N THB2 38
Rebranded Units: GEONAUTE T(Geonaute WS-300 Weather Station) 63-1091 T(Radio Shack Proj Weather/Clock) n/a T(Brookstone Proj Weather/Clock) Weather sensors: PCR800 RAINWGR800 WINDPCR918N RAINWGR918N WINDCurrent sensors: CM113 ELS_ELEC(WMR80A Weather Station) (WMR80A Weather Station) (WMR968N Weather Station) (WMR968N Weather Station) (Electrisave cent-a-meter)

The STR928N Solar Panel houses the transmitters for both PCR918N (ORE_RAIN1) and THGR918N (ORE_TH6) sensors within the panel housing. The STR938 Solar Panel housing houses the transmitter for the WGR918N (WIND3) anemometer. The length of an Oregon RF transmission depends on the type, but is somewhere around 150-400 milliseconds. With two THR138 sensors set to channels 1 and 2 respectively, one might expect that the two sensors would transmit at the same time _at most_ once every (30 * 29) = 870 seconds. The most likely result of an overlap of the RF transmissions is that the RFXCOM receiver will not recognize the signal as a valid Oregon signal and remain silent, but losing one out of every 30 transmissions is normally not that serious a problem. However consider the case of two sensors with the same nominal transmission interval. Each Oregon sensor has an independent timebase and the transmission intervals will be slightly different. The two sensors may run for a long time without the transmissions overlapping, but one will eventually catch up with the other. Suppose the intervals of two sensors differ by 10 milliseconds. Then when the catchup occurs, the RF signal overlap will last for approximately (3 * 150) = 450 milliseconds divided by 10 milliseconds, or 45 intervals of 30 seconds - a blackout period of about 22 minutes when no signal will be reported. The smaller the difference between sensor intervals, the longer the blackout period will last. If you are forced to run more than one sensor with the same nominal transmission interval, a more precise measurement of the each interval can be obtained from the Heyu monitor by putting the directive "LOGDATE_UNIX YES" in the conguration le. An extended blackout longer than the time set by conguration directive INACTIVE_TIMEOUT (default 4 hours) will generate an Inactive message in the monitor/logle. Although Heyu can be instructed to ignore signals from a neighbors sensors by using the ORE_IGNORE module type, those signals can still interfere with signals from your own sensors and result in a blackout if the transmission intervals are the same.

SPECIAL BWR102 SETUP

The Oregon BWR102 scale has a switch on the scale for units kg, lbs, or stone-lbs, but this controls only the display on the scales LCD. The transmitted data is always in kg. Use the cong directive ORE_WGTSCALE to dene the units for Heyus display. Oregon appears to use the scale factor 2.200 for conversion from kg to lbs rather than the ofcial value 2.2046226. However neither of these produces an exact match to the BWR102 LCD display for weights below about 50 lbs. The BWR102 transmits data as follows: After stepping on the scale and displaying the measurement, the scale retransmits the data up to seven times at approximately 10 or 11 second intervals (for use by the remote display unit provided with the scale). Heyu sets the changed ag for the rst of these regardless of whether the weight in this measurement is the same or different as the previous measurement, i.e., if you
step on the scale twice in a row and get the exact same reading (which is unusual), Heyu will still record the weight as changed. Note: Transmissions from the BWR102 are single RF bursts and will be ignored if the <min_count> in directive AUX_REPCOUNTS is set greater than 1.

EXPERIMENTAL STUFF

Directive "ORE_ID_16 YES" expands the ID of Oregon sensors to 16-bit by using the channel code as the upper byte of a 16-bit ID word and the normal sensor-assigned ID as the lower byte. This may be useful if you have some of the Oregon sensor models which can only generate a very limited number of different IDs. Heyu recognizes protocols for Oregon signals beyond those listed as supported, but by default ignores them. Directive DISPLAY_ORE_ALL YES - Instructs Heyu to display "RFdata" signals with all recognized Oregon protocols even though the support may not yet exist for them in Heyu. Recognized but unsupported protocols are: ORE_DT1 - Real time clock/calendar. ORE_WGT2 - Weight

AUTHORS

Oregon support was added to Heyu by Charles W. Sullivan using the protocols gratefully provided by RFXCOM.

SEE ALSO

http://www.heyu.org heyu(1), x10cong(5), x10sched(5), x10scripts(5), x10aux(5), x10cm17a(5), x10rfxsensors(5), x10rfxmeters(5), x10digimax(5)