X10RFXSENSORS(5)

NAME
x10rfxsensors - RFXSensor 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.

RFXSensors are remote RF sensors which transmit encoded Temperature, Relative Humidity, and/or Barometric Pressure information, depending on configuration. When equipped with a compatible RF receiver, Heyu can receive and decode this information. An overview of these sensors appears further down in this page.

SYSTEM REQUIREMENTS
To use RFXSensors with Heyu requires a W800RF32A/AE or an RFXCOM X10 RF receiver with a carrier frequency matching that of the RFXSensor transmitter and Heyu version 2.2 or greater.

COMPILER OPTION
Support for RFXSensors 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
Start Heyu, including the Heyu Auxilliary daemon. Then open another xterm window and start the Heyu Monitor.

The following examples use RFXSensor data for a system comprised of an RFXSensor transmitter with a Relative Humidity sensor plus a connected external Temperature/Barometric Pressure sensor.

Press the recessed reset button on the RFXSensor transmitter and something like the following should appear in the Heyu Monitor window (ignoring the dates and times):

  rcva RFXSensorXmitter : Type 3, version 10, sample_mode fast
  rcva RFXSensorInit : ID 0x00, chip DS2438, serial_no 8755651
  rcva RFXSensorInit : ID 0x04, chip DS2438, serial_no 8107391
  rcva func RFdata : Type RFXSensor ID 0x00* Data 0x1429
  rcva func RFdata : Type RFXSensor ID 0x02 Data 0x3AC3
  rcva func RFdata : Type RFXSensor ID 0x01 Data 0x3047
  rcva func RFdata : Type RFXSensor ID 0x04* Data 0x146D
  rcva func RFdata : Type RFXSensor ID 0x06 Data 0x3ACB
  rcva func RFdata : Type RFXSensor ID 0x05 Data 0x1768

Note: The "RFXSensorInit" messages will not appear when using a W800RF32A/AE receiver or an RFXCOM receiver in 32-bit mode. They are garbled with these receivers and appear to Heyu as RF noise. (Heyu doesn't need this data.)

The asterisk (*) adjoining the IDs 0x00 and 0x04 in the RFdata entries identifies them as the base addresses of the transmitter and external sensor. The RFXSensorInit provides the same information. If you have more than one RFXSensor transmitter, repeat the above with each to verify that the base addresses for all sensors are unique.

Now map each transmitter and each external sensor to an otherwise unused housecode|unit X10 address with ALIAS directives in the Heyu configuration file using module type RFXSENSOR, e.g.,

  ALIAS House L9 RFXSENSOR 0x00 TH
  ALIAS Basement C7 RFXSENSOR 0x04 TB

where the format for this directive is:
  ALIAS <label> <hcode|unit> RFXSENSOR <base_addr> <sensor_type>

<sensor_type> is one of the following:
  TH for a Temperature and Humidity sensor
  TB for a Temperature and Barometric Pressure sensor
  TV for a Temperature and A/D Voltage sensor
  TP for a Temperature and Potentiometer sensor
  TT for a Dual Temperature sensor
  T for a Temperature-only sensor (1-Wire DS18B20 chip)

Run 'heyu restart' to incorporate the configuration file changes in Heyu's processes, then again press the reset button on each transmitter. The display in the Heyu Monitor window should now look like this:

  rcva RFXSensorXmitter : Type 3, version 10, sample_mode fast
  rcva RFXSensorInit : ID 0x00, chip DS2438, serial_no 8755651
  rcva RFXSensorInit : ID 0x04, chip DS2438, serial_no 8107391
  rcva func rfxTemp : hc L unit 9 Temp 20.125C (House)
  rcva func rfxVs : hc L unit 9 Vs 4.70V (House)
  rcva func rfxRH : hc L unit 9 RH 105.48% (House)
  rcva func rfxTemp : hc C unit 7 Temp 20.375C (Basement)
  rcva func rfxVs : hc C unit 7 Vs 4.70V (Basement)
  rcva func rfxBP : hc C unit 7 BP 547.6 hPa (Basement)

where the functions displayed are Temperature, Supply voltage (Vs), Relative Humidity (RH), and Barometric Pressure (BP).

An RFXSensor rfxTemp temperature message will be displayed whenever the sampled temperature changes by an amount determined by the 1-Wire chip (as described in the RFXSensor data sheet). The rfxVs supply voltage message (and low battery signal, if any) appears only at reset and at the "heartbeat" intervals (40 or 80 minutes).

UNIT SCALING
The native units for output of RFXSensors are Celsius for temperature, hPa (hectoPascals) for Barometric Pressure, and Volts for A/D Voltage. These may be scaled by Heyu to different units with the following configuration file directives:

Directive RFX_TSCALE <temp_scale>

where <temp_scale> is F[ahrenheit], C[elsius], K[elvin], or R[ankine].
Example:
  RFX_TSCALE F

Directive RFX_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.
Some examples:
  RFX_BPSCALE mmHg 0.75006158
  RFX_BPSCALE inHg 0.029529983 1.06
  RFX_BPSCALE millibars 1.0

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.

Directive RFX_VADSCALE <Vad_unit> <scale_factor>

where <Vad_unit> is the name of the new unit, e.g., mV, and <scale_factor> is the number by which the A/D Voltage is multipled to get its value in the new unit.
Example:
  RFX_VADSCALE mV 1000.0

STORED RFXSENSOR DATA
If the Heyu Engine daemon is running, current RFXSensor 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 following Heyu state commands. Scaled values are displayed for rfxtemp, rfxbp, rfxvad, and rfxtemp2. The others are not scaled. Hu is the Housecode|Unit address to which the sensor has been mapped in the ALIAS directive.
  heyu rfxtemp Hu - Temperature
  heyu rfxtemp2 Hu - Second Temperature
  heyu rfxrh Hu - Relative Humidity
  heyu rfxbp Hu - Barometric Pressure
  heyu rfxvad Hu - A/D Voltage
  heyu rfxpot Hu - Potentiometer setting
  heyu rfxvs Hu - Supply Voltage
  heyu rfxvadi Hu - Internal A/D Voltage (unscaled)
  heyu rfxlobat Hu - Low Battery indicator (Boolean).

Note that computation of barometric pressure requires the supply voltage. Computation of relative humidity requires the supply voltage and temperature. If for whatever reason all the required quantities have not yet been stored in the state tables, e.g., after 'heyu initstate', the value displayed will be "----" or "Not Ready".

Also note that rfxlobat (low battery) is a separate function and not a flag as it is with X10 security sensors.

The command 'heyu show rfxsensors' will display stored data from all configured RFXSensors in tabular form.

HEYU SCRIPTS
Heyu scripts can be launched by the functions rfxtemp, rfxrh, rfxbp, rfxpot, rfxvad, rfxlobat, and rfxtemp2 the same as any other Heyu function. The source keyword "RCVA" must be included in the launch conditions.
Example:
  SCRIPT L9 rfxtemp rcva :: my_rfxtemp.sh

SCRIPT ENVIRONMENT
Any Heyu script has access to the stored RFXSensor values through environment variables linked to the housecode|unit (Hu) and its alias mapped to each RFXSensor.
  X10_Hu_Temp x10_<Hu_alias>_Temp
  X10_Hu_Temp2 x10_<Hu_alias>_Temp2
  X10_Hu_RH x10_<Hu_alias>_RH
  X10_Hu_BP x10_<Hu_alias>_BP
  X10_Hu_Pot x10_<Hu_alias>_Pot
  X10_Hu_Vad x10_<Hu_alias>_Vad
  X10_Hu_Vadi x10_<Hu_alias>_Vadi
  X10_Hu_Vs x10_<Hu_alias>_Vs
  X10_Hu_LoBat x10_<Hu_alias>_LoBat (Boolean)

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 RFXSensor data. See man page x10config(5). Directive HIDE_UNCHANGED YES|NO

RFXSENSOR OVERVIEW
RFXSensors are manufactured by RFXCOM (http://www.rfxcom.com) They consist of an RF transmitter to which may be optionally connected external sensors. Models are available which transmit at a frequency of 310 MHz for use in North America and at a frequency of 433.92 MHz for use elsewhere in the world. The RF signals can be received by a W800RF32A/AE or RFXCOM X10 RF receiver employing the same carrier frequency.

RFXSensor RF transmitters have a built-in 1-Wire temperature sensor chip. The current model ("Type 3") transmitter includes an A/D converter and may optionally include a Relative Humidity (RH) sensor chip. The analog output of the RH sensor chip is encoded by the A/D converter.

The RFXSensor External Sensor modules have a built-in 1-Wire temperature sensor chip, optionally an A/D converter, and optionally either a Relative Humidity (RH) sensor chip or a Barometric Pressure (BP) sensor chip. The analog output of the RH or BP chip is encoded by the A/D converter.

In the absence of a RH or BP chip, the A/D converter in a tranmitter or external sensor can encode the analog voltage (0 to 10VDC) from a user-supplied electrical device, or the relative setting of a 10K linear potentiometer.

A total of 64 RFXSensor modules are supported, which may include up to:
  8 RFXSensor Type 3 RF Transmitters, each with up to 7 RFXSensor
  External Sensor modules connected in a daisy chain configuration.
     - or -
  32 RFXSensor Type 1 or 2 RF Transmitters (both now discontinued),
  each with a single connected RFXSensor External Sensor module.

RF signals from RFXSensors include an address which identifies the transmitter or external sensor, and type of signal. Each transmitter has a "base address" which is user configurable (per the RFXSensor data sheet) and which must be different for each transmitter. Type 3 transmitters have a base address which is 0x00 or a multiple of 0x20. Type 1 or 2 transmitters have a base address which is 0x00 or a multiple of 0x08. External sensors have a base address assigned by the transmitter which is the base address of the transmitter plus a multiple of 0x04.

When delivered from the factory, transmitters will usually have a base address of 0x00 although this is not guaranteed.

Note that for a Type 3 transmitter with more than one connected external sensor, there is no definitive relationship between the base address assigned to a particular external sensor and its position in the daisy chain. Furthermore, adding an additional external sensor may change the addresses previously assigned to other sensors in the chain. Some experimentation by the user may be necessary to determine which address is assigned to which external sensor if it's not obvious from the temperature readings.

Each 1-Wire chip encodes a unique serial number which is included in the power-up and reset message transmission, and which can be received by an RFXCOM X10 receiver operating in variable-length message mode. It may come in handy to record this serial number somewhere, perhaps even on a label affixed to the sensor.

Temperature signals are transmitted at the base address. For sensors with an A/D converter, the A/D voltage signal is transmitted at the base address plus 1 and a Supply voltage signal at the base address plus 2. Software, Heyu in this case, uses the address as an ID and decodes the A/D voltage signal according to the kind of sensor, i.e., whether humidity or barometric pressure or potentiometer setting or just as a voltage.

AUTHORS
RFXSensor support was added to Heyu by Charles W. Sullivan

SEE ALSO
http://www.rfxcom.com/sensors
http://www.rfxcom.com/documents/RFXSensor.pdf
http://www.heyu.org
heyu(1), x10config(5), x10sched(5), x10scripts(5), x10aux(5), x10cm17a(5), x10rfxmeters(5)