X10OREGON(5) File Formats Manual X10OREGON(5) 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 Humid- ity, 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 sen- sors, 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 re- ceiver 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 re- ceiver. 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 RFX- COM 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 win- dow 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 dae- mons. 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 cor- responding to the displayed function labels. In the following, "Hu" is the Housecode|Unit address to which the sensor has been mapped in the ALIAS di- rective, 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 sen- sors.) 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_fac- tor> 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 ap- proximate this adjustment for altitude. Typical values for BP versus alti- tude 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 sig- nals 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 sec- tion "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 set- points 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 configura- tion 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 condi- tions 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 ex- ceeds 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 set- point, 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 op- tionally 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 dis- played 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_BP- SCALE 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 direc- tive 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 key- word "RCVA" and may optionally include the keyword "changed", any of the 16 common flags, and the global security flags. They may also optionally in- clude 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 envi- ronment 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" iden- tification, 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 fol- lowing will also affect Oregon data. See man page x10config(5). Directive ORE_LOWBATTERY <percent> - Defines for those sensors which trans- mit 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 Log- file 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 situa- tion where even in a relatively constant temperature environment the re- ported 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 hectoPas- cals 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 ac- tual 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 sig- nal 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 Sen- sors 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 di- rection (+/- 0-359 degrees from due North) your sensor is actually point- ing. 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) Beau- fort 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 sen- sors in tabular form. The command 'heyu show sensors' displays the Active/Inactive state and bat- tery 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 Sen- sors 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 displayed 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 con- tents 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 millime- ters 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 pro- viding 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 in- dicator 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 dis- played with the data). The configuration directive ORE_LOWBATTERY defines the level (default 20%) at or below which the LoBat flag is raised and dis- played. 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 af- ter 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 sen- sors in tabular form. The command 'heyu show sensors' displays the Active/Inactive state and bat- tery 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 moni- tor/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 unaf- fected 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 sig- nals 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 em- ulation (dummy) Oregon module for processing by Heyu, just as if the data were received from an actual Oregon sensor. The available emulation mod- ules (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 con- figuration directives ORE_TSCALE and ORE_BPSCALE. Note that with unit con- version 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 (typ- ically 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. Remem- ber 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 transmis- sion 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 in- terfere with each other over an extended period of time. The transmission interval for Oregon sensors is typically 30, 40 or 60 sec- onds 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 some- where around 150-400 milliseconds. With two THR138 sensors set to channels 1 and 2 respectively, one might ex- pect 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 transmis- sion 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 millisec- onds, 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 trans- mission 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 pro- duces 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 dis- playing 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 ig- nored 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 sup- ported, 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), x10config(5), x10sched(5), x10scripts(5), x10aux(5), x10cm17a(5), x10rfxsensors(5), x10rfxmeters(5), x10digimax(5) local X10OREGON(5)
NAME | DESCRIPTION | SYSTEM REQUIREMENTS | COMPILER OPTION | CONFIGURATION | STORED OREGON DATA | UNIT SCALING | SUPPORTED OREGON MODEL NUMBERS | TEMPERATURE, HUMIDITY, and BAROMETRIC PRESSURE SETPOINTS | HEYU SCRIPTS | SCRIPT ENVIRONMENT | CONFIGURATION DIRECTIVES | CURRENT SENSORS | WIND SENSORS | RAIN SENSORS | APPLICABLE OLDER DIRECTIVES for WIND and RAIN sensors. | OREGON SENSOR EMULATION | MULTIPLE OREGON SENSORS | SPECIAL BWR102 SETUP | EXPERIMENTAL STUFF | AUTHORS | SEE ALSO
Want to link to this manual page? Use this URL:
<https://man.FreeBSD.org/cgi/man.cgi?query=x10oregon&sektion=5&manpath=FreeBSD+Ports+15.1.quarterly>