Welcome to FHmonitor’s documentation!

FHmonitor

https://img.shields.io/pypi/v/FHmonitor.svg https://img.shields.io/travis/bitknitting/FHmonitor.svg Documentation Status

FHmonitor (FitHome monitor):

  • Is a Python Package written for the FitHome Experience.

  • Assumes the package is running on a Raspberry Pi.

  • Reads the active and reactive power registers of the atm90e32 and stores the readings into a mongo database.

  • Free software: MIT license

  • Documentation: https://FHmonitor.readthedocs.io.

Features

Credits

Our code stands on the shoulders of Tisham Dhar’s work. In particular the atm90e26 Arduino library.

Another package we learned from was Circuit Setup’s atm90e32 Arduino library.

This package was created with Cookiecutter and the audreyr/cookiecutter-pypackage project template.

FHmonitor package

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.

_images/Electricity_Monitor_Rasp_Pi.png

The Hardware

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

Hardware Setup Steps

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.

_images/test_wiring_to_measure_current.jpg

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)[source]

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 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()[source]

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()[source]

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')[source]

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)[source]

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()[source]

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[source]

Bases: FHmonitor.store.Store

Storing to Firebase is not implemented at this time.

class FHmonitor.store.MongoDB(path_str, db_str, collection_str)[source]

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)[source]

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[source]

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()[source]

Contributing

Contributions are welcome, and they are greatly appreciated! Every little bit helps, and credit will always be given.

You can contribute in many ways:

Types of Contributions

Report Bugs

Report bugs at https://github.com/bitknitting/FHmonitor/issues.

If you are reporting a bug, please include:

  • Your operating system name and version.

  • Any details about your local setup that might be helpful in troubleshooting.

  • Detailed steps to reproduce the bug.

Fix Bugs

Look through the GitHub issues for bugs. Anything tagged with “bug” and “help wanted” is open to whoever wants to implement it.

Implement Features

Look through the GitHub issues for features. Anything tagged with “enhancement” and “help wanted” is open to whoever wants to implement it.

Write Documentation

FHmonitor could always use more documentation, whether as part of the official FHmonitor docs, in docstrings, or even on the web in blog posts, articles, and such.

Submit Feedback

The best way to send feedback is to file an issue at https://github.com/bitknitting/FHmonitor/issues.

If you are proposing a feature:

  • Explain in detail how it would work.

  • Keep the scope as narrow as possible, to make it easier to implement.

  • Remember that this is a volunteer-driven project, and that contributions are welcome :)

Get Started!

Ready to contribute? Here’s how to set up FHmonitor for local development.

  1. Fork the FHmonitor repo on GitHub.

  2. Clone your fork locally:

    $ git clone git@github.com:your_name_here/FHmonitor.git

  3. Create a virtual environment and install developer dependencies:

    $ python3 -m venv venv
$ source venv/bin/acivate
(venv) $ cd FHmonitor/
(venv)$ pip3 install -r requirements_dev.txt

  4. Create a branch for local development:

    $ git checkout -b name-of-your-bugfix-or-feature

    Now you can make your changes locally.

  5. When you’re done making changes, check that your changes pass flake8 and the tests, including testing other Python versions with tox:

    $ flake8 FHmonitor tests
$ python setup.py test or pytest
$ tox

    To get flake8 and tox, just pip install them into your virtualenv.

  6. Commit your changes and push your branch to GitHub:

    $ git add .
$ git commit -m "Your detailed description of your changes."
$ git push origin name-of-your-bugfix-or-feature

  7. Submit a pull request through the GitHub website.

Pull Request Guidelines

Before you submit a pull request, check that it meets these guidelines:

  1. The pull request should include tests.

  2. If the pull request adds functionality, the docs should be updated. Put your new functionality into a function with a docstring, and add the feature to the list in README.rst.

  3. The pull request should work for Python 3.5, 3.6, 3.7 and 3.8, and for PyPy. Check https://travis-ci.com/bitknitting/FHmonitor/pull_requests and make sure that the tests pass for all supported Python versions.

Tips

To run a subset of tests:

$ pytest tests.test_FHmonitor

Deploying

A reminder for the maintainers on how to deploy. Make sure all your changes are committed (including an entry in HISTORY.rst). Then run:

$ bump2version patch # possible: major / minor / patch
$ git push
$ git push --tags

Travis will then deploy to PyPI if tests pass.

Credits

Development Lead

Contributors

None yet. Why not be the first?

History

0.0.1 (2020-03-01)

  • First release on PyPI.

Indices and tables