Intro

The FHmonitor package runs on a Raspberry Pi that is communicating with an atm90e32 chip over SPI. We use Circuit Setup’s energy meter, which uses the atm90e32. Current Transformers (CTs) that are plugged into the energy meter clamp onto the power lines. The CTs provide a signal to the elecriticy monitor that is then interpreted into power line measurements like voltage and current.

The FHmonitor package:

• reads power readings from the electricity monitor.

• stores readings into the mongodb running on the Raspberry Pi.

The Hardware

Before using the FHmonitor package, you must have a running energy monitor. The energy monitor consists of:

• Raspberry Pi 3 Model B+

• Circuit Setup’s energy meter

• An LED of any color. The LED helps with debugging.

• A resistor between 400 and 1K ohm.

Hardware Setup Steps

• Set up the Raspberry Pi.

• Connect the Hardware.

Once the hardware is setup, the CTs need to be installed. Circuit Setup has an excellent write up on installing CTs

Calibrating the Meter

Getting good readings from the atm90e32 assumes the parameters defined in calibration.json are set to reflect the environment in which the meter will be taking readings. The various calibration parameters are:

• Frequency of AC coming into your home - lineFreq: Since we are in North America where the AC frequency is 60Hz, We set this to 4485. The rest of the world is at 50Hz. If that is how your home’s power is configured, change this value in calibration.json to 389.

• Gain for the CT clamps - PGAGain: The default setting is for homes that have 100 amp service - 21. Many houses are big and/or suck up more electricity than a 100 amp service provides. The PGAGain must be set to 42 for homes with electricity service between 100-200 amps.

• Gain adjustment for Voltage Readings - VoltageGain: This value depends on the power 9v/12v power supply being used with the energy meter. One of CircuitSetup’s web pages provides default values for some common power supplies. We decided to standardize on the Jameco 9V power supply, part no. 157041.

• Gain adjustment for Current Readings - CurrentGain: This value depends CT (Current Transformer) being used. We are using the SCT-016.

NOTE: We used the command line utilities:

calibrate_voltage
calibrate_current

discussed below to set VoltageGain and CurrentGain. Also Note: CircuitSetup’s firmware for the energy meter uses a current gain setting for each of the CTs. We simplified this to use just one parameter - CurrentGain - for both CTs.

calibrate_voltage

After starting up the venv and pip installing FHmonitor, the calibrate_voltage command is available. This command runs a python script that will adjust the VoltageGain value within calibration.json. Prior to using the command, you should have the energy meter plugged into a Kill-A-Watt. The Kill-A-Watt will be the reference voltage. Running the command with the -s (–save) option will figure out the new VoltageGain value and then update calibration.json. If the -s option is not specified, the new VoltageGain value will not be saved.

calibrate_current

calibrate_current is similar in concept to calibrate_voltage. Instead of using voltage readings, current readings are used. The CT can be plugged into either of the CT plugs on the meter. We use a test wire assembly to read the current of a device (for example a lamp) using a CT.

systemd service

The systemd service, FHmonitor_main.service starts a shell script, run_FHmonitor_main.sh. The shell script starts FHmonitor_main.py.

start_service

Use the command:

(venv)$ start_service

To start the FHmonitor_main.service systemd service. The code for start_service. At the end of start_service, the service status is given. The PID will be shown in the results. To make sure your service is still running, find the PID and use the command:

(venv)$ journalctl _PID=<PID number>

stop_service

Use the command:

(venv)$ stop_service

To execute the OS command for stopping the FHmonitor_main.service systemd service. The code for stop_service

status_service

Use the command:

(venv)$ status_service

To execute the OS command for checking the status of the FHmonitor_main.service systemd service. The code for status_service

hello_monitor

Once the:

• monitor is plugged in with the CTs strapped around the power lines.

• the venv has been installed and activated.

• the FHmonitor package has been installed.

Type:

(venv)$hello_monitor

If all is working, you should get reasonable active and reactive power readings.

The code for hello_monitor.

Monitor class

The class you will use the most is Monitor. This class contains methods to:

• Take an active and reactive power reading (see take_reading()).

  • Before taking a reading, the energy meter must be initialized (see init_sensor()).

• Store the reading into the mongo db running on the Raspberry Pi (see store_reading()).

  • Before storing readings, the mongo db must be opened (see open_db()).

class FHmonitor.monitor.Monitor(led_pin=None)

Take active and reactive power readings from an atm90e32 and store the readings in the Rasp Pi’s mongodb.

Example:

m = Monitor()
m.init_sensor()

Make sure to read all the parameters that can be input to init_sensor(). The values depend on the Power Transformer and CTs being used.

The blink() method is useful to turn on and off the LED (for debugging purposes).

blink(ntimes=1)

Blink the monitor’s LED. Uses Python’s Timer object so that blinking does not pause data capture and storage.

Parameters

ntimes (int, optional) – Number of times to blink, defaults to 1

close_db()

It is more efficient to keep the mongodb open while using it. However, if you know you will not be doing any more transactions, it is good to clean up the connections.

init_sensor()

Initialize the atm90e32 by setting the calibration registry properties. Calibration is discussed within our FitHome wiki .

Parameters

• lineFreq – 4485 for 60 Hz (North America, Default), 389 for 50 Hz (rest of world)

• PGAGain – Programmable Gain - 0 for 10A (1x), 21 for 100A (2x, Default), 42 for 100A - 200A (4x)

• VoltageGain – Dependent on transformer being used. Should be measured prior to taking readings. See the Calibration discussion linked to above.

• CurrentGainCT1 – Dependent on the CTs being used. Should be measured prior to taking readings. See the Calibration discussion linked to above.

• CurrentGainCT2 – Similar to CurrentGainCT1, but for the second CT.

Returns

True if meter is initialized. False if meter could not be initialized.

open_db(mongodb='mongodb://localhost:27017/', db='FitHome', collection='aggregate')

Opens and maintains an instance to the mongo database where the power readings will be stored.

Parameters

• mongodb – URI to the mongo database running on the Raspberry Pi

• db – Database within mongodb that holds the readings.

• collection – name of the collection where the readings are held.

Returns

True if the database can be opened.

store_reading(Pa, Pr)

Store the active and reactive power readings into the mongodb database.

Parameters

• Pa – A floating value representing the active power reading. Obtained through a call to take_reading().

• Pr – A floating value representing the reactive power reading. As with Pa, use take_reading() to retrieve the value from the energy meter.

Returns True if the readings could be stored.

take_reading()

Read the active and reactive power readings from the atm90e32 registers.

Returns

(Pa, Pr) Where Pa is the float value for the active power reading and Pr is the float value for the reactive power reading.

Store class

The Monitor class uses an implementation of the Store abstract class to store power readings into a datastore. The only data store currently available is the mongo db. We originally started with a Firebase DB, but decided running everything on a Raspberry Pi was much easier. Mongo db can be run on the Raspberry Pi at no additional $ cost.

class FHmonitor.store.FirebaseDB

Bases: FHmonitor.store.Store

Storing to Firebase is not implemented at this time.

class FHmonitor.store.MongoDB(path_str, db_str, collection_str)

Bases: FHmonitor.store.Store

Implements the Store base class for mongo db.

The __init__ method initializes a connection to the mongodb collection. An exception occurs if the path_str does not connect to a running mongodb service.

Parameters

• path_str – e.g.: “mongodb://localhost:27017/”

• db_str – Name of the db in mongodb, e.g.: “FitHome”.

• collection_str – Name of the collection within the mongodb db e.g.: “aggregate”

save(data)

Save the data to the connected mongo db.

Parameters

data – Dictionary containing active and reactive power readings. e.g.: reading = {“Pa”: Pa, “Pr”: Pr, } Where Pa and Pr values were obtained using the FHmonitor module.

Returns

True if the readings are inserted into the collection. False if the collection does not exist or if inserting the readings fails.

class FHmonitor.store.Store

Bases: object

The Store class is used as an abstract class so that different back ends - for example, mongodb ,CSV, or Firestore - can be used to store the active and reactive power readings from Circuit Setup’s atm90e32 meter.

save()