NAME

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 file 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 configuration file:
TTY_AUX <serial_port or network_address:port> RFXCOM
where <serial_port> is the port where the RFXCOM receiver is connected, or <network_address:port> is where the RFXLAN receiver is listening. The RFXCOM receiver connects to a USB port but includes a USB->Serial converter chip, while the RFXLAN connects over a network.

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 identified by the mnemonic ORE_TH1.

Map the Oregon ID to an otherwise unused housecode and unitcode address with an ALIAS directive in your Heyu configuration file 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 file (if thus configured).

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 configured 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 configuration file 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
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 neighbor´s sensor. An unused Housecode/Unit address must be sacrificed. 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: It´s 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 defined 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 configuration file. When the data value reported by the sensor falls below or above the respective setpoint, corresponding local flags 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 flag will be raised. If the crawl-space humidity exceeds 90%, the RHMAX flag will be raised. And if the D5 sensor reports an attic temperature outside the range 60F - 90F, then the appropriate TMIN or TMAX flag will be raised.

If the temperature scale suffix (C, F, K, or R) is omitted from the setpoint, the config directive "ORE_DATA_ENTRY NATIVE|SCALED" determines whether the scale is the native Celsius scale or that defined by directive ORE_TSCALE.

The only scale for relative humidity is %, which may optionally be omitted.

The barometric pressure scale defined by the ORE_BPSCALE directive may optionally include an offset to adjust for altitude. If the specified 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 specified by BPMIN corresponds to the adjusted value displayed by Heyu, whereas a setpoint specified by BPMINL corresponds to the local value displayed on the sensor´s LCD screen.

A BP setpoint may include the suffix for the units defined in the ORE_BPSCALE directive or the native units "hPa". If the setpoint is specified without a units suffix, the config directive "ORE_DATA_ENTRY NATIVE|SCALED" determines whether the scale is the native "hPa" or that defined 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 flags, and the global security flags. They may also optionally include the local flags.
Examples:
SCRIPT L9 oretemp rcva armed away tmin :: my_oretemp.sh
SCRIPT L9 orerh changed rcva :: my_orerh.sh

Local flags 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 flags without the "Hu" identification, 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 x10config(5).

Directive ORE_LOWBATTERY <percent> - Defines for those sensors which transmit a battery level the percentage at or below which Heyu will raise the "LoBat" flag. The default is 20%.

Directive HIDE_UNCHANGED YES - Display transmission in the Monitor and Logfile only when there´s a change from the previous transmission.

Directives ORE_CHGBITS_xx define the amount of change in the data required for it to be identified as "changed". The parameter for these directives is the number of least significant 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 there´s 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 flip-flop back and forth by 0.1C in successive transmissions.

The actual value of the data is stored in the Heyu state tables even though it´s not identified as changed or displayed in the Monitor/Log file.

The default for each of the above directives is 1.

Directive ORE_DATA_ENTRY NATIVE|SCALED
Defines 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 defined 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 suffix.

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/logfile 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>
Defines 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 doesn't have large motors running.

Directive ELS_CHGBITS_CURR
Defines the amount of change in the Electrisave current required for it to be identified 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>
Defines 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>
Define the amount of change in the reported Power or Energy required for it to be identified 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>
Define 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/logfile 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 identified by "RFdata:Type" and decoded by the Heyu module types:
ORE_WIND1
ORE_WIND2
ORE_WIND3

Having identified the protocol and ID byte from the RFdata:Type displayed in the monitor/logfile, 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 specified 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>
Oregon´s setup instructions call for the wind sensor to be mounted pointing due North. If this is not possible, use this directive to define 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/logfile. 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/logfile. The default is NO.

Directive ORE_CHGBITS_WINDSP <nbits>
Directive ORE_CHGBITS_WINDAVSP <nbits>
Directive ORE_CHGBITS_WINDDIR <nbits>
These directives define the amount of change in the variable required for it to be marked as "changed", expressed as the number of least significant 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 flags and local flags "lobat" and "changed" can be included in the launch conditions as required. The source "rcva" must be included (unless it has been configured 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 identified by "RFdata:Type" and decoded by the Heyu module types:
ORE_RAIN1
ORE_RAIN2
ORE_RAIN3

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 filled 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/logfile. The default is NO.

Directive ORE_CHGBITS_RAINRATE <nbits>
Directive ORE_CHGBITS_RAINTOT <nbits>
These directives define 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 flag 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 configuration directive ORE_LOWBATTERY defines the level (default 20%) at or below which the LoBat flag is raised and displayed.

When the total rain counter rolls over to zero, the Heyu "rollover" flag 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 it´s equivalent to 10000 millimeters. The Rain1 and Rain3 rollover points are assumed to be the same as for Rain2, but this has not been verified.

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 flags and local flags "lobat" and "changed" can be included in the launch conditions as required. The source "rcva" must be included (unless it has been configured 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/logfile.

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 specified timeout (default is 4 hours).

Directive ORE_DISPLAY_BATLVL YES|NO
Determines whether the battery level 0-100% is displayed in the monitor/logfile for those sensor models which report a battery level as opposed to just a low-battery flag. The default is YES. The LoBat flag is unaffected by this directive. (The battery level defined with directive ORE_LOWBATTERY defines the level at or below which the LoBat flag will be raised.)

Directive ORE_DISPLAY_CHAN YES|NO
Determines whether the Oregon channel number is displayed in the monitor/logfile. (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/logfile. 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 configuration 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 suffix C, F, K, or R.)

The configuration 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 suffix.
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 defined by configuration 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 specified with ORE_BPSCALE. (The offset is applied to the value displayed in the monitor or log file and to the Heyu environment variables when a script is launched.)

Example:
In the Heyu config file:
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 logfile 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 T1 30 29 31
THRN122N T2 78
THN122N T2 39 41 43
THN132N T2 39 41 43
THGR122NX TH1 39 41 43
THGN123N TH1 39 41 43
THGR228N TH1 39 41 43
THGR238 TH1 ?? ?? ??
THGR238N TH1 39 41 43
THGR810 TH2 53 59 61 67 71 79 83 87 91 93
THGR800 TH2 53 59 61
THGN800 TH2 53 59 61 (WMR80A Weather Station)
RTGN318 TH3 53 59 61 67 71 (BAR800 Weather Station)
RTGR328N TH3 53 59 61 67 71
THGR328N TH4 53 59 61 67 71
THGR918N TH6 37 (WMR968N Weather Station)
BTHR968 THB2 38
BTHR918N THB2 38

Rebranded Units:
GEONAUTE T2 78 (Geonaute WS-300 Weather Station)
63-1091 T2 39 41 43 (Radio Shack Proj Weather/Clock)
n/a T1 30 29 31 (Brookstone Proj Weather/Clock)

Weather sensors:
PCR800 RAIN2 47 (WMR80A Weather Station)
WGR800 WIND2 14 (WMR80A Weather Station)
PCR918N RAIN1 47 (WMR968N Weather Station)
WGR918N WIND3 14 (WMR968N Weather Station)

Current sensors:
CM113 ELS_ELEC1 6 (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 configuration file.

An extended blackout longer than the time set by configuration directive INACTIVE_TIMEOUT (default 4 hours) will generate an Inactive message in the monitor/logfile.

Although Heyu can be instructed to ignore signals from a neighbor´s 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 scale´s LCD. The transmitted data is always in kg. Use the config directive ORE_WGTSCALE to define the units for Heyu´s display.

Oregon appears to use the scale factor 2.200 for conversion from kg to lbs rather than the official 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´ flag for the first 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.