Extension to the WeeWX weather system for collecting data and generating reports for the Brultech GEM energy monitors.

This is a extension for the WeeWX weather system for the Brultech GEM energy monitor. While an energy monitor is very different from a weather station, WeeWX is a very flexible system and has no trouble running the driver. The extension includes three parts:

• A driver for the GEM energy monitor. The driver is designed to poll your energy monitor at regular intervals, typically every 10-15 seconds, then pass the data on to the rest of the WeeWX system.

• A database schema designed for the monitor. Because the types used by an energy monitor are so radically different from a weather station, this extension includes a specialty schema (called gem_schema), specifically designed for the Brultech monitors. It will be used to initialize a separate database from the conventional WeeWX weather database, allowing both to be run simultaneously. By default, it will include space for 32 channels.

• A WeeWX skin, called SeasonsPower, designed to display current, week, month, and year energy use. It also includes monthly energy summaries. It can easily be customized by following the directions in the WeeWX Customization Guide.

What follows are directions for installing the extension. It consists of five parts:

1. Configuring your Brultech monitor
2. Installing WeeWX
3. Installing the extension, either by using the WeeWX installer, or manually.
4. Select database options
5. Start up WeeWX

The Brultech energy monitors come with a bewildering array of modes and options. To keep things simple, this driver makes two assumptions:

• The device will always be in server mode.
• The device driver will always poll the device.

This makes it pretty easy to configure the device:

1. Set the GEM to "server mode". Using a browser, connect to your GEM (http://192.168.1.104, in my case) and go to the "Application Settings" page. Set it to server mode, using port 8000:

   

   Click Apply.

2. Then click on the "Device Management" tab, and click the "Restart" button under Restart Module.

   

The monitor will reboot and be ready to receive commands from the driver. That's it for the monitor.

Next step is to install WeeWX.

It is strongly recommended that you use the "setup.py" method for installing WeeWX. All of the instructions that follow assume this.

Follow the instructions in the setup.py install guide and install WeeWX. When asked, specify that the Simulator driver be used. When you're done, WeeWX will be installed in /home/weewx.

By default, when WeeWX is installed, it installs the Seasons skin and activates it. You will need to deactivate it. In the WeeWX configuration file weewx.conf, generally located in /home/weewx/weewx.conf, set option enable to false for the Seasons report. When you're done, it will look like this:

    ...
    [[SeasonsReport]]
        # The SeasonsReport uses the 'Seasons' skin, which contains the
        # images, templates and plots for the report.
        skin = Seasons
        enable = false
        lang = en
        unit_system = us

Next step is to install the weewx-brultech extension itself, either by using the WeeWX installer, or manually.

This section describes how to install weewx-brultech using the WeeWX installer.

Download the weewx-brultech package and install it using the WeeWX installer:

cd /home/weewx
wget https://github.com/tkeffer/weewx-brultech/archive/master.zip
./bin/wee_extension --install=master.zip

When you're done with the installation, your WeeWX configuration will be set up to use the Brultech driver. However, you still have to configure the driver. Do this by using the wee_config utility with the --reconfigure option:

./bin/wee_config --reconfigure

It will give you the opportunity to change various settings. Eventually, it will ask about options for the Brultech driver:

Specify the IP address (e.g., 192.168.0.10) or hostname of the Brultech monitor.
host [192.168.1.104]: 192.168.0.7
Specify the port
port [8000]: 
Saved backup to /home/weewx/weewx.conf.20211025164234

In this example, we have changed the host from 192.168.1.104 to 192.168.0.7, but accepted the default port (8000).

This section describes how to manually configure WeeWX to use this extension.

Download the weewx-brultech package and unpack it

cd /home/weewx
wget https://github.com/tkeffer/weewx-brultech/archive/master.zip
tar xvf master.zip

Put the files brultech.py and gem_schema.py in the user subdirectory. Typically,

cd /home/weewx/weewx-brultech-master
cp bin/user/brultech.py /home/weewx/bin/user
cp bin/user/gem_schema.py /home/weewx/bin/user

Copy the StandardPower skin over:

cp -r skins/StandardPower /home/weewx/skins

This section is about manually configuring the configuration file, weewx.conf, usually found in /home/weewx/weewx.conf.

1. Add section [Brultech]

   Insert a new stanza [Brultech] into your weewx.conf file that looks like this:

   [Brultech]
   
       # See README.md for instructions on how to configure the Brultech devices!!
   
       # Power is computed as the difference between energy records. How old a 
       # record can be and still be used for this calculation:
       stale = 1800
   
       # How often to poll the device for data
       poll_interval = 5
   
       # Max number of channels to emit. Limit is set by hardware (48 for GEM).
       max_channels = 32
   
       # The type of packet to use. Possible choices are GEMBin48NetTime, GEMBin48Net,
       # or GEMAscii:
       packet_type = GEMBin48NetTime
   
       # Max number of times to try an I/O operation before declaring an error
       max_tries = 3
   
       driver = user.brultech
   
       # The type of connection to use. It should match a section below. 
       # Right now, only 'socket' is supported.
       connection = socket
   
       # The following is for socket connections: 
       [[socket]]
           host = 192.168.1.104
           port = 8000
           timeout = 20
           # After sending a command, how long to wait before looking for a response    
           send_delay = 0.2
   
       [[sensor_map]]

   Be sure to set options host and port to their proper values for your network configuration.

2. Set station type

   Tell WeeWX to use the Brultech device driver by setting station_type, under section [Station], to Brultech:

   [Station]
   
      ...
   
      # Set to type of station hardware. There must be a corresponding stanza
      # in this file with a 'driver' parameter indicating the driver to be used.
      station_type = Brultech

3. Configure new binding

   Under stanza [DataBindings], add a new database binding bt_binding for the Brultech device. It should look like this:

   [DataBindings]
   
    ...
   
       [[bt_binding]]
           # The database must match one of the sections in [Databases].
           database = bt_sqlite
           # The name of the table within the database
           table_name = archive
           # The manager handles aggregation of data for historical summaries
           manager = weewx.manager.DaySummaryManager
           # The schema defines the structure of the database.
           # It is *only* used when the database is created.
           schema = user.gem_schema.schema

4. Configure new database

   Under stanza [Databases], add a new database bt_sqlite:

   [Databases]
   
   ...
   
       [[bt_sqlite]]
           database_name = weepwr.sdb
           database_type = SQLite  

5. Use the new binding

   Under stanza [StdArchive], set the option data_binding to bt_binding. This will cause new data to be archived in the database dedicated to Brultech data.

   [StdArchive]
   
       ...
   
       data_binding = bt_binding         

6. Configure and activate the SeasonsPower skin

   Add a subsection to [StdReport] for the SeasonsPower skin, and activate it by setting enable to True:

   [StdReport]
    
       ...
    
       [[PowerReport]]
           skin = SeasonsPower
           enable = True
           data_binding = bt_binding
           [[[Units]]]
               [[[[Groups]]]]
                   group_energy2 = kilowatt_hour

   Incidentally, while you're in there, make sure that any "weather" skins have been deactivated --- they won't work with the data from the energy monitor!

7. Make sure the configuration service runs

   Because of its many specialized types, the Brultech driver requires setting up some custom configurations. This is done by the service brultech.BrultechService. You must add it to the list of services to run by adding it to data_services. So, now your [Engine] section looks something like this:

   [Engine]
   
      [[Services]]
          # This section specifies the services that should be run. They are
          # grouped by type, and the order of services within each group
          # determines the order in which the services will be run.
          prep_services = weewx.engine.StdTimeSynch,
          data_services = user.brultech.BrultechService
          process_services = weewx.engine.StdConvert, weewx.engine.StdCalibrate, weewx.engine.StdQC, weewx.wxservices.StdWXCalculate
          ...

The default schema works well for most applications. However, you may want to tune it for special cases. Take a look in the schema's file, usually located in /home/weewx/bin/user/gem_schema.py, and you will see a number of options. Here are their meanings

You're done installing and configuring the extension. You can start WeeWX either directly from the command line, or start it as a daemon. Instructions are in the WeeWX User's Guide, in the section Running WeeWX.

The driver can emit the following types:

where NN is the channel number. NB: the channel number uses no leading zero. For example, it is ch2_volt, NOT ch02_volt.

So, for example:

• ch14_p_energy2 would be the accumulated polarized energy in channel 14.
• ch2_a_energy2 would be the accumulated absolute energy in channel 2.
• ch2_ad_energy2 would be the absolute energy used during the archive interval in channel 2.

The Brultech energy monitors emit accumulated energy in units of watt-seconds. Accumulated energy is the amount of energy that has flowed through the channel since the monitor was reset. Because a watt-second is a small amount of energy, and it may be years since your monitor was reset, this can often be a very large number. Fortunately, the Brultech monitors reserve five bytes for this value, so it can count up to over 300,000 kWh. A typical home might use 10,000 kWh per year, so the value is unlikely to rollover for years.

WeeWX uses accumulated energy to calculate delta energy, which is the amount of energy that flowed through the channel in an archive interval (typically 5 minutes). It is the difference in accumulated energy between the beginning and the end of the interval.

To calculate the amount of power used over, say, a month, you can either take the difference in accumulated energy, or you can sum the smaller delta energies for the month. Here's an example using channel 8:

By default, both values are stored in the database. The skins that come with weewx-brultech use accumulated energy.

They each have their advantages.

The calculation is very efficient: only two numbers need be looked up in the database. By contrast, using delta energies requires summing all the records.

If the computer running WeeWX goes down during the time period, but the energy monitor stays up, it won't affect the final result. This is because you only need the first and last value for the time period to calculate the total energy used.

Of course, if the monitor goes down, you will miss energy used during that time period no matter which method you use.

If you have technical problems with your monitor and must do a system reset, the counters will go to zero. This means that if you try to calculate total energy used over a period that includes the reset, and you do the calculation by calculating differences in accumulated energy, you will get a large negative number. By contrast, if you sum the delta energies, you will get the correct answer.

The same thing can happen if the battery in your GEM fails. It is responsible for maintaining the count should the power fail.