X10OREGON(5)X10OREGON(5)NAMEx10oregon - 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 vari‐
ables. 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 com‐
piler 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 familiar‐
ity 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 mod‐
ule 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 con‐
figured).
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 con‐
figured Oregon units in tabular form.
UNIT SCALING
The native units for output of Oregon sensors are Celsius for tempera‐
ture, hPa (hectoPascals) for Barometric Pressure, and kilograms for
Weight. (See the sections WIND SENSORS and RAIN SENSORS for informa‐
tion 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_fac‐
tor> 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 multi‐
plied 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 sup‐
ported 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 sen‐
sors which may not be under your control, e.g., signals from a nearby
neighbor´s sensor. An unused Housecode/Unit address must be sacri‐
ficed. 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 sec‐
ond 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 Pres‐
sure.
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" deter‐
mines 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 pres‐
sure. 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 suc‐
cessive 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 hec‐
toPascals for BP) or in the scaled units defined by directives
ORE_TSCALE and ORE_BPSCALE. This also applies to TMIN and TMAX set‐
point temperatures when the entered temperature does not have a temper‐
ature 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 resi‐
dence 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 calibra‐
tion 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/log‐
file 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 fol‐
lowing 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 trans‐
mitted 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 dis‐
played 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 direc‐
tion as one of 16 compass points 22.5 degrees apart, whereas Wind3 sen‐
sors 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 differ‐
ent units. Some common examples (courtesy of the Unix ´units´ pro‐
gram):
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 sen‐
sor 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/log‐
file. 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 sig‐
nificant 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 exe‐
cuted 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 environ‐
ment 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
Having identified the protocol and ID byte from the RFdata:Type dis‐
played in the monitor/logfile, 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 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 arbi‐
trary 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" pro‐
gram):
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 mil‐
limeters. 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 environ‐
ment 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 moni‐
tor/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 moni‐
tor/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 emula‐
tion 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 Tempera‐
ture 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 dis‐
played 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 over‐
lap of the RF transmissions is that the RFXCOM receiver will not recog‐
nize the signal as a valid Oregon signal and remain silent, but losing
one out of every 30 transmissions is normally not that serious a prob‐
lem.
However consider the case of two sensors with the same nominal trans‐
mission 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 millisec‐
onds 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 "LOG‐
DATE_UNIX YES" in the configuration file.
An extended blackout longer than the time set by configuration direc‐
tive INACTIVE_TIMEOUT (default 4 hours) will generate an Inactive mes‐
sage 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 mea‐
surement 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 proto‐
cols are:
ORE_DT1 - Real time clock/calendar.
ORE_WGT2 - Weight
AUTHORS
Oregon support was added to Heyu by Charles W. Sullivan using the pro‐
tocols gratefully provided by RFXCOM.
SEE ALSO
http://www.heyu.org
heyu(1), x10config(5), x10sched(5), x10scripts(5), x10aux(5),
x10cm17a(5), x10rfxsensors(5), x10rfxmeters(5), x10digimax(5)
local X10OREGON(5)
