btmon Configuration Guide

This is a guide to setting up a power monitoring system using Brultech GEM, ECM-1240, or ECM-1220 devices.

btmon.py is a Python script that collects data from Brultech devices then saves the data or uploads the data to online power monitoring services. btmon uses little memory or processing power, so it is well-suited to running on devices such as routers or plug computers. Since it is pure Python it will run on just about anything that has Python, including MacOSX, Windows, Linux.

btcfg.py is a Python script that will query and modify the configuration of Brultech devices. This can be useful when there is no windows computer available to run Brultech's IA software (for ECM devices) or Java available to run Green-Eye Monitor Setup (for GEM devices).

• btmon and btcfg work only with Python 2, not Python 3
• use the --help option for a list of all options
• use the --debug option for more details about what btmon is doing
• use the --skip-upload with the --debug option to see what would be uploaded without actually uploading

btmon is compatible with many online services. See the comments in btmon.py for details about how to create accounts and configure each online service.

Installing btmon:

General Recommendations
Debian Linux
Windows

How to configure the GEM
How to configure the ECM
How to configure network settings

Polarity
Real-Time Mode
Client and Server Modes
Polling versus Blocking
Multiplexing

Run btmon on a router
Run btmon on Windows
Save to RRD from serial ECM-1240
Upload to Smart Energy Groups from ethernet GEM
Save to MySQL from serial GEM
Collect data from multiple GEM via TCP/IP with btmon in server mode
Collect data from multiple ECM via serial
Collect data from multiple ECM via serial with polling
Run multiple instances of btmon

Installation

btmon.py is a single Python script, so installation consists of downloading the script to your computer. It is good practice to put the script into a separate folder since there probably will be a configuration file to go with the script. btcfg.py can be placed in the same folder as btmon. btcfg.py will be useful if the GEM/ECM configuration tools from Brultech will not run (e.g. no Java or no Windows).

Of course, Python must be installed. MacOSX and most flavors of linux come with Python. Python is very easy to install on Windows.

Additional Python modules may be required. For example, if the Brultech device is connected via serial, the Python serial module will be required. If saving to a MySQL database is desired, then the Python MySQLdb module must be installed.

• serial - required if reading data from serial port
• MySQLdb - required if saving to MySQL database
• sqlite3 - required if saving to sqlite database
• rrdtool - required if saving data to Round Robin Database files
• ConfigParser - required if using configuration files

The approach to installing Python modules varies. For example, on Redhat systems one would use yum install python-serial, on Debian systems one would use apt-get install python-serial, and on many systems one could use Python's built-in installer easy_install pyserial.

1. Install Python 2.6 or 2.7. btmon will not work with Python 3.

   sudo apt-get install python2.6
   

2. Create a directory in which to keep btmon and any configuration file(s):

   mkdir btmon
   cp Downloads/btmon.py btmon
   

That's it! Depending on the configuration, you might have to install other Python modules. If btmon complains about a missing module, install that module using apt-get.

1. Install Python 2.6 or 2.7. btmon will not work with Python 3.

   http://python.org/download/windows
   

2. Create a directory in which to keep btmon and any configuration file(s):

   mkdir c:\btmon
   copy Downloads\btmon.py c:\btmon
   

That's it! Depending on the configuration, you might have to install other Python modules. If btmon complains about a missing module, install that module using easy_install.

Configuring the GEM or ECM

The examples in this guide require setting the real-time mode, send interval, and packet format.

There are three tools for configuring a GEM:

• web browser directly to GEM (only for GEM with ethernet option)
• Green-Eye Monitor Setup - this is a Java application from Brultech
• btcfg.py - this is a Python script

The GEM has many settings, such as real-time mode, per-channel type and range, polarity, etc. See the Brultech documentation for details about all of the configuration options.

The examples in this guide require setting the real-time mode and send interval.

There are two tools for configuring an ECM:

• ECM-1240 IA - this is a Windows application from Brultech
• btcfg.py - this is a Python script

The ECM has many settings, such as real-time mode, channel polarity, etc. See the Brultech documentation for details about all of the configuration options.

Some GEM have a built-in serial-to-ethernet device. Any ECM can be connected to a serial-to-ethernet device as well. Typically this is a WizNET or similar that converts the GEM serial to TCP/IP. Some devices convert serial to wired ethernet, others convert serial to wireless ethernet.

The serial-to-ethernet device has a number of parameters, including:

• client/server mode
• IP address of device, and whether to use DHCP or a fixed IP address
• port on which to listen when device is in server mode
• IP address and port of server when device is in client mode
• wireless network settings

There are a number of tools available to configure the serial-to-ethernet device. These can be downloaded from the device vendor or from Brultech. For example, WIZnet makes the source available for their configuration tool, so it is available on multiple platforms:

• Wiznet Configurator.app - MacOSX application
• WIZ1xxSR Configuration Tool - Windows application

The examples in this guide require setting the client/server mode, IP address, and port.

Configuration Tips

Two channels on the ECM-1240 and 32 channels on the GEM count not just power, but also power direction. Each channel has two counters. The absolute counter increments when power flows. The polarized counter increments when power flows in one direction, but not in the other. The polarity of the channel indicates whether the power should be considered positive or negative.

There are many ways to configure the polarity.

• orientation of the CT
• position of the CT leads
• the per-channel polarity toggle in the GEM configuration
• the --reverse-polarity option to btmon

btmon interprets the polarized counter differently than the GreenEyeMonitor setup tool. btmon interprets an increase to the polarized counter as 'positive' energy. GreenEyeMonitor interprets an increase to the polarized counter as 'negative' energy. As a result, the polarity reported by btmon will be the inverse of the polarity reported by GreenEyeMonitor.

Use the --reverse-polarity option to make the polarity reported by btmon match the polarity reported by GreenEyeMonitor and other Brultech tools.

GEM and ECM-1240 devices have a real-time mode. When in real-time mode, the device emits packets at a regular interval. When the device is not in real-time mode it will not emit a packet until a packet is requested.

When configuring a GEM/ECM, first ensure that the device is not in real-time mode. If the device is in real-time mode when configuration commands are sent, the real-time packets can interfere with communications.

When communicating via TCP/IP, the GEM/ECM can be in either client or server mode. When the GEM/ECM is in server mode, it responds to requests - the computer running btmon must initiate the request for communication. When the GEM/ECM is in client mode, the GEM/ECM initiates the communication.

Server mode is typical for most installations. Client mode is useful when a firewall is betwen the GEM/ECM and the computer on which btmon is running, or when there are multiple GEM and a single instance of btmon.

The --ip-mode option to btmon specifies the mode for btmon, not the GEM/ECM. So if the GEM/ECM is in server mode, btmon should be in client mode.

1. GEM is in server mode
   • IP address of GEM is 192.168.X.Y
   • GEM is listening on port 5000
   • btmon should be run in client mode like this:

     btmon.py --device-type=gem --ip --ip-mode=client --ip-host=192.168.X.Y --ip-port=5000
     

2. GEM is in client mode
   • server address in the GEM configuration should be the IP address of the computer on which btmon is running
   • port in the GEM configuration should be arbitrary port number over 1000, say 6000
   • btmon should be run in server mode like this:

     btmon.py --device-type=gem --ip --ip-mode=server --ip-port 6000
     

Technically it is the serial-to-ethernet hardware (e.g. WizNET) that has client/server modes - the GEM/ECM communicates via serial with the WizNET, and the WizNET communicates with other devices via TCP/IP.

btmon can either accept real-time packets from the GEM/ECM (the GEM/ECM must be in real-time mode) or it can poll for data (the GEM/ECM must *not* be in real-time mode).

The polling mode is useful if there are multiple computers that need to communicate with a single GEM/ECM. In most cases btmon should be in blocking mode, accepting real-time packets from the GEM/ECM.

Polling is specified with the --serial-poll-interval=X (for serial connections) or --ip-poll-interval=X (for TCP/IP connections) option.

Multiple GEM/ECM can share a single serial connection. For example, up to 4 ECM-1240 can be connected to one serial port, or multiple GEM can be connected to a single WizNET.

Although multiplexing is possible, it is not encouraged. When devices are multiplexed they are prone to cause contention - the result is packet loss. Instead of reliably receiving a packet every 10 seconds, the data collector may experience periods of multiple minutes where no data are received.

btmon cannot communicate with multiple device types on a single connection. For example, if a GEM and ECM-1240 are both connect to a single WizNET, btmon can collect from one or the other but not both. If the GEM emits ECM binary packets then btmon can collect from both devices, but this configuration is not encouraged.

When polling multiplexed devices, a list of one or more device identifiers must be specified. The identifiers for the ECM-1240 are 0xfc, 0xfd, 0xfe, or 0xff. The identifier for the GEM is the serial number.

Example Configurations

This example shows how to run btmon on an ASUS router with Tomato USB, collecting data from a Green-Eye Monitor attached via ethernet and uploading data to COSM (pachube).

Hardware: ASUS N16 router
Software: Tomato USB v1.28 with optware

1. Install TomatoUSB
2. Install optware on USB drive on the router
3. Put the GEM into server mode, listening on port 5000
4. Set the GEM packet type to Green-Eye Binary with Date
5. Put the GEM into real-time mode, emitting a packet every 30 seconds
6. Do a quick test by running btmon like this:

   btmon.py --ip --ip-mode=client --ip-host=X.X.X.X --ip-port=5000 --print
   

7. Put this into the file config.cfg:

   [source]
   device_type = gem
   ip_read = true
   ip_host = X.X.X.X
   ip_port = 5000
   ip_mode = client
   [pachube]
   pachube_out = true
   pbe_token = ZZZZZ
   pbe_feed = YYYYY
   

8. Start btmon like this:

   btmon.py -c config.cfg
   

9. Configure btmon to run on startup (see the optware documentation)

This example shows how to run btmon on Windows, collecting data from an ECM-1240 attached by serial to COM1 and uploading data to emoncms.

1. Install pre-requisites:

   Python 2.7

   http://python.org/download/windows

   pyserial (for reading from serial port)

   http://sourceforge.net/projects/pyserial/files/pyserial

2. Install btmon:

   mkdir c:/Program Files/btmon/bin
   copy btmon-x.y.z.py c:/Program Files/btmon/bin/btmon.py
   

3. Put the ECM-1240 into real-time mode, emitting a packet every 10 seconds
4. Do a quick test by running btmon like this:

   btmon.py --serial --serial-port=COM1 --print
   

5. Create a configuration file config.cfg:

   [source]
   serial_read = true
   serial_port = COM1
   [oem]
   oem_out = false
   oem_url=http://emoncms.org/input/post
   oem_token = XXXXXX
   

6. Start btmon like this:

   btmon.py -c config.cfg
   

This example shows how to run btmon on a Linux system, collecting data from an ECM-1240 attached by USB-serial adapter to /dev/ttyUSB0 and saving to RRD files on local disk.

1. Put the ECM-1240 into real-time mode, emitting a packet every 10 seconds
2. Do a quick test by running btmon like this:

   btmon.py --serial --serial-port=/dev/ttyUSB0 --print
   

3. Put this into the file config.cfg:

   [source]
   device_type = ecm1240
   serial_read = true
   serial_port = /dev/ttyUSB0
   [rrd]
   rrd_out = true
   rrd_dir = /var/rrd
   

4. Start btmon like this:

   btmon.py -c config.cfg
   

This example shows how to run btmon, collecting data from a Green-Eye Monitor attached by ethernet and uploading data to Smart Energy Groups.

1. Put the GEM into server mode, listening on port 5000
2. Set the GEM packet type to Green-Eye Binary with Date
3. Put the GEM into real-time mode, emitting a packet every 45 seconds
4. Do a quick test by running btmon like this:

   btmon.py --device-type=gem --ip --ip-mode=client --ip-host=X.X.X.X --ip-port=5000 --print
   

5. Put this into the file config.cfg:

   [source]
   device_type = gem
   ip_read = true
   ip_host = X.X.X.X
   ip_port = 5000
   ip_mode = client
   [seg]
   smartenergygroups_out = true
   seg_upload_period = 180
   seg_token = XXXXXXX
   

6. Start btmon like this:

   btmon.py -c config.cfg
   

This example shows how to run btmon, collecting data from a Green-Eye Monitor attached by USB-serial adapter to /dev/ttyUSB0 and saving to local MySQL database.

1. Set the GEM packet type to Green-Eye Binary with Date
2. Put the GEM into real-time mode, emitting a packet every 30 seconds
3. Do a quick test by running btmon like this:

   btmon.py --device-type=gem --serial --serial-port=/dev/ttyUSB0 --print
   

4. Configure mysql

   # mysql -u root -p
   mysql> create user gemuser identified by 'gempass';
   mysql> grant usage on gem.* to gemuser@localhost identified by 'gempass';
   mysql> grant all privileges on gem.* to gemuser@localhost;
   

5. Put this into the file config.cfg:

   [source]
   device_type = gem
   serial_read = true
   serial_port = /dev/ttyUSB0
   [mysql]
   mysql_out = true
   mysql_user = gemuser
   mysql_passwd = gempass
   mysql_database = gem
   

6. Start btmon like this:

   btmon.py -c config.cfg
   

This example shows how to run btmon in server mode, collecting data from two Green-Eye Monitors via TCP/IP. In this example, btmon runs on a computer with IP address 192.168.X.Y.

1. On the first GEM, set the packet type to Green-Eye Binary with Date
2. Put the GEM into real-time mode, emitting a packet every 30 seconds
3. Configure the GEM to run in client mode with server at 192.168.X.Y and port 2000
4. Do a quick test by running btmon like this:

   btmon.py --device-type=gem --ip --ip-mode=server --ip-port=2000 --print
   

5. Configure the second GEM as the first (binary packet, real-time, client)
6. Check the btmon output to ensure that it is receiving data from both GEMs
7. Put this into the file config.cfg:

   [source]
   device_type = gem
   ip_read = true
   ip_port = 2000
   ip_mode = server
   

8. Start btmon like this:

   btmon.py -c config.cfg
   

This example shows how to run btmon, collecting data from two ECM-1240 via a single serial.

1. Enable real-time mode on each ECM-1240 with a period of 30 seconds
2. Check communication with the ECM by running btmon like this:

   btmon.py --device-type=ecm1240 --serial --serial-port=/dev/ttyUSB0 --print
   

3. Put this into the file config.cfg:

   [source]
   device_type = ecm1240
   serial_read = true
   serial_port = /dev/ttyUSB0
   

4. Start btmon like this:

   btmon.py -c config.cfg
   

This example shows how to run btmon, collecting data from two ECM-1240 via a single serial using polling.

1. Disable real-time mode on each ECM-1240
2. Set the command byte on the first ECM-1240 to fc
3. Set the command byte on the second ECM-1240 to fd
4. Check communication with the first ECM by running btmon like this:

   btmon.py --device-type=ecm1240 --serial --serial-port=/dev/ttyUSB0 --serial-poll-interval=30 --device-list=fc --print
   

5. Check communication with the second ECM by running btmon like this:

   btmon.py --device-type=ecm1240 --serial --serial-port=/dev/ttyUSB0 --serial-poll-interval=30 --device-list=fd --print
   

6. Check communication with the both ECM by running btmon like this:

   btmon.py --device-type=ecm1240 --serial --serial-port=/dev/ttyUSB0 --serial-poll-interval=30 --device-list=fc,fd --print
   

7. Put this into the file config.cfg:

   [source]
   device_type = ecm1240
   serial_read = true
   serial_port = /dev/ttyUSB0
   serial_poll_interval = 30
   device_list = fc,fd
   

8. Start btmon like this:

   btmon.py -c config.cfg
   

This example shows how to run two instances of btmon. The first instance collects data from a GEM and saves data to a local sqlite database. The second instance collects data from the database and uploads to Smart Energy Groups, OpenEnergyMonitor, and COSM.

First configure the collect instance:

1. Put the GEM into real-time mode, emitting a packet every 30 seconds
2. Configure the GEM to run in server mode listening on port 5000
3. Do a quick test by running btmon like this:

   btmon.py --device-type=gem --ip --ip-mode=client --ip-port=5000 --print
   

4. Verify that saving to sqlite works like this:

   btmon.py --device-type=gem --ip --ip-mode=client --ip-port=5000 --sqlite
   

5. Put this into the file collect.cfg:

   [source]
   device_type = gem
   ip_read = true
   ip_port = 5000
   [sqlite]
   sqlite_out = true
   

6. Start btmon like this:

   btmon.py -c collect.cfg
   

Configure and test the Smart Energy Groups upload:

1. Set up an account at SmartEnergyGroups using the instructions in btmon.py
2. Do a quick test by running btmon like this:

   btmon.py --device-type=gem --sqlite-src --smartenergygroups-out --seg-token=SEG_TOKEN
   

3. Verify that data are uploaded to Smart Energy Groups

Configure and test the Open Energy Monitor upload:

1. Set up an account at OpenEnergyMonitor using the instructions in btmon.py
2. Do a quick test by running btmon like this:

   btmon.py --device-type=gem --sqlite-src --oem-out --oem-token=OEM_TOKEN
   

3. Verify that data are uploaded to OpenEnergyMonitor

Configure and test the COSM upload:

1. Set up an account at COSM using the instructions in btmon.py
2. Do a quick test by running btmon like this:

   btmon.py --device-type=gem --sqlite-src --pachube-out --pbe-token=COSM_TOKEN
   

3. Verify that data are uploaded to COSM

When testing the uploads, it might help to specify the --debug option.

Put it all together:

1. Put this into the file upload.cfg:

   [source]
   device_type = gem
   sqlite_read = true
   [seg]
   smartenergygroups_out = true
   seg_token = SEG_TOKEN
   [oem]
   oem_out = true
   oem_token = OEM_TOKEN
   [cosm]
   pachube_out = true
   pbe_token = COSM_TOKEN
   

2. Start btmon like this:

   btmon.py -c upload.cfg
   

Copyright © Matthew Wall, all rights reserved
$Id: btmon-howto.html 540 2013-03-06 14:21:45Z mwall $
Last modified: