X10RFXSENSORS(5) File Formats Manual 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, Rela- tive Humidity, and/or Barometric Pressure information, depending on config- uration. 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 re- ceiver 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 ex- ternal 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 gar- bled 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 sen- sor. 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 dis- play 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), Rela- tive 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 "heart- beat" 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 ap- proximate this adjustment for altitude. Typical values for BP versus alti- tude 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 config- ured). 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 sen- sor 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 tempera- ture. If for whatever reason all the required quantities have not yet been stored in the state tables, e.g., after 'heyu initstate', the value dis- played 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 con- figured RFXSensors in tabular form. HEYU SCRIPTS Heyu scripts can be launched by the functions rfxtemp, rfxrh, rfxbp, rfx- pot, 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 environ- ment 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 fol- lowing 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 ex- ternal sensor can encode the analog voltage (0 to 10VDC) from a user-sup- plied electrical device, or the relative setting of a 10K linear poten- tiometer. 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 trans- mitter 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 transmit- ters 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 ad- dress 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 as- signed 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 baromet- ric 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) local X10RFXSENSORS(5)
NAME | DESCRIPTION | SYSTEM REQUIREMENTS | COMPILER OPTION | CONFIGURATION | UNIT SCALING | STORED RFXSENSOR DATA | HEYU SCRIPTS | SCRIPT ENVIRONMENT | CONFIGURATION DIRECTIVES | RFXSENSOR OVERVIEW | AUTHORS | SEE ALSO
Want to link to this manual page? Use this URL:
<https://man.FreeBSD.org/cgi/man.cgi?query=x10rfxsensors&sektion=5&manpath=FreeBSD+Ports+15.1.quarterly>