home | help 
X10RFXMETERS(5) 	       File Formats Manual		 X10RFXMETERS(5)

NAME
     x10rfxmeters - RFXMeter 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.

     RFXMeters are remote RF sensors which transmit encoded data  from	electric
     power,  water,  gas, or other metering modules, 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 RFXMeters with Heyu requires a 433.92 MHz RFXCOM X10 RF receiver and
     Heyu version 2.2 or greater.

COMPILER OPTION
     Support  for RFXMeters 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.

HEYU CONFIGURATION
     It  is  assumed  that a working installation of Heyu version 2.2 or greater
     exists on the computer, and that the user	has  a	basic  familiarity  with
     Heyu.

     The Heyu configuration file should include the directive:
       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.

     Start Heyu with 'heyu start', then open another xterm window and start  the
     Heyu Monitor.

     Wait  for the RFXMeter to make a transmission, at which time you should see
     in the Monitor widow something like this (ignoring the date and time):

       rcva func       RFdata : Type RFXMeter ID 0x08 Data 0xADB92C07

     Map the RFXMeter ID to an otherwise unused housecode and  unitcode  address
     with  an ALIAS directive, using one of the following module types depending
     on whether the RFXMeter is monitoring Electric Power, Water, or Gas (or  is
     just used to count pulses):
       RFXPOWER <ID>
       RFXWATER <ID>
       RFXGAS <ID>
       RFXPULSE <ID>

     Example using housecode|unit C5 and the above ID:
       ALIAS MyElectric  C5  RFXPOWER  08

     Run  'heyu restart'.  The next time the RFXMeter transmits, you should then
     see in the Monitor window:

       rcva func       rfxPower : hc C unit 5 Meter 99.876 kWh (MyElectric)

     If instead of electric power the RFXMeter is monitoring Water or  Gas  con-
     sumption and the following mapping is used:
       ALIAS MyGas  C5	RFXGAS 08

     You would instead see in the Monitor window:
       rcva func       rfxGas : hc C unit 5 Counter 99876 pulses (MyGas)

UNIT SCALING
     While  the  RFXPower  module is already calibrated in kWh, the scale factor
     for Water, Gas, or Pulse metering must be supplied.  For this, one  of  the
     following configuration directives is used:
       RFX_WATERSCALE  <Water_unit>  <scale_factor>
       RFX_GASSCALE  <Gas_unit>  <scale_factor>
       RFX_PULSESCALE  <Pulse_unit>  <scale_factor>

     For  example  a gas meter often has a series of dials and an optical sensor
     can presumably be mounted to provide one pulse for  each  rotation  of  the
     smallest  dial.   On one type of gas meter in the USA, each rotation of the
     smallest dial corresponds to 0.5 cubic feet of gas, so the directive to use
     would be:
       RFX_GASSCALE  cu_ft  0.5

     And (after 'heyu restart') you will then see:
       rcva func       rfxGas : hc C unit 5 Meter 49938.0 cu_ft (MyGas)

ROLLOVER
     The counter in a RFXMeter module counts from zero to  a  maximum  value  of
     16777215  (0xFFFFFF),  corresponding  in  the  case  of RFXPower modules to
     16777.215 kWh, then rolls over to zero.  When Heyu detects that a	reported
     count  is	less  than  the  previous count it sets a local "rollover" flag.
     Note that this includes the case where the user has reset	the  counter  to
     zero during RFXMeter configuration.

POWER PANEL TOTALS
     If  two  or  three  RFXPower  modules are installed in adjacent slots in an
     RFXMeter transmitter, Heyu assumes they  are  being  used	to  monitor  the
     phases  in  a  two or three phase power panel or breaker box.  It will then
     sum the readings from each of the phases and display the total in the  Heyu
     Monitor  and log file as a "Panel".  Panels are numbered starting with 0 in
     the event there are multiple RFXMeter transmitters, each with two or  three
     RFXPower modules.

STORED RFXMETER DATA
     If  the  Heyu  Engine daemon is running, the most recent transmissions from
     RFXMeters are stored in the Heyu state tables and can be recovered with the
     following state commands:
       heyu rfxpower Hu  (for Power)
       heyu rfxwater Hu  (for Water)
       heyu rfxgas   Hu  (for Gas)
       heyu rfxpulse Hu  (for pulse count)
       heyu rfxcount Hu  (raw counter of any RFXMeter)
       heyu rfxpanel [N] (Power panel [N] total - default N is Panel 0)

     The command 'heyu show rfxmeters' will display the meter readings	for  all
     configured RFXMeters in a tabular format.

HEYU SCRIPTS
     The  functions  rfxpower,	rfxwater,  rfxgas,  and  rfxpulse can be used in
     launch conditions to launch Heyu scripts the same as any other  Heyu  func-
     tion.  The source keyword "RCVA" must be included in the launch conditions.
     Example:
       SCRIPT  C5  rfxpower rcva :: my_power_script.sh

     Any  of  the usual flags may be included in the launch condition, including
     the rollover flag set after an RFXMeter counter rolls over to zero.
     Example:
       SCRIPT  C5  rfxpower rollover rcva :: my_rollover_script.sh

SCRIPT ENVIRONMENT
     Any Heyu script has access to the stored RFXMeter values  through	environ-
     ment  variables  linked  to the housecode|unit (Hu) and its alias mapped to
     each RFXMeter.

       X10_Hu_Power   x10_<Hu_alias>_Power
       X10_Hu_Water   x10_<Hu_alias>_Water
       X10_Hu_Gas     x10_<Hu_alias>_Gas
       X10_Hu_Pulse   x10_<Hu_alias>_Pulse
       X10_Hu_Count   x10_<Hu_alias>_Count

     Example:
       SCRIPT A1 on sndc :: echo "Gas used: "$x10_MyGas_Gas | mail

RFXMETER CONFIGURATION
     Configuring the RFXMeter is a matter of pushing or  not  pushing  the  MODE
     button on the RFXMeter transmitter in response to transmitted prompts.

     When  the button is to be pushed, it generally has to be done within 5 sec-
     onds.  Or if the button is not to be pushed, it's necessary to wait 5  sec-
     onds for the next prompt.

     To  help  avoid confusion and frustration with this process, a special Heyu
     Monitor feature has been implemented.  If the monitor is started  with  the
     parameter "rfxmeter", i.e.,
       heyu monitor rfxmeter

     then only RFXMeter messages are displayed and their format is simplified as
     follows:

       The usual date, time, and signal source are omitted.

       Normal data transmissions are displayed as:
	 RFXMeter ID nn, Counter nnnn pulses

       Instructional messages and prompts from the RFXMeter are
	 translated and displayed.

     With  this  special monitor window open, start the configuration process by
     powering down the RFXMeter for at least 10 seconds, then hold down the MODE
     button on the device while restoring the power. When the green LED  lights,
     release  the  button. Following display of the firmware identification, the
     prompts will begin.

     The order the configuration items will appear is:
       Set Interval
       Set Address
       Power Calibration
       Reset Counter to zero

     Note: Power calibration requires a precision wattmeter and is normally  un-
     necessary since the unit is precalibrated at the factory.

RFXMETER OVERVIEW
     RFXMeters	are  manufactured by RFXCOM (http://www.rfxcom.com) They consist
     of an RF transmitter with up to three plug-in modules.  The transmitter op-
     erates at a carrier frequency of 433.92 MHz.  Plug-in modules are available
     for metering power consumption and for counting pulses from optical sensors
     or switch contacts attached to other types of meters such as water  or  gas
     meters.   Counter	values	are saved in non-volatile memory in the event of
     power interruption.

     Multiple RFXMeter transmitters may be used with a total of up to 256  plug-
     in modules. (This many would use all 256 X10 Housecode/Unit addresses.)

     The RFXMeter transmits its data packet at user configurable intervals of 30
     seconds, 1, 6, 12, 15, 30, 45, or 60 minutes.

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

SEE ALSO
     http://www.rfxcom.com/sensors
     http://www.rfxcom.com/documents/RFXMeter.pdf
     http://www.rfxcom.com/documents/RFXPwr%20module.pdf
     http://www.rfxcom.com/documents/RFXPulse%20module.pdf
     http://www.heyu.org
     heyu(1),  x10config(5), x10sched(5), x10scripts(5), x10aux(5), x10cm17a(5),
     x10rfxsensors(5)

				      local			 X10RFXMETERS(5)
home | help