bmonreporter

This script creates the "Energy Reports" for BMON Building Monitoring applications. It is meant to be run periodically; it is currently run once per day at 3 am. The script is generally configured to store the final produced reports in an web-accessible AWS S3 bucket, which is then accessed by the BMON application to allow users to view the reports. The 'ENERGY_REPORTS_URL' in the BMON settings file points at the URL of the S3 bucket.

Reports are generated by running Jupyter Notebooks that produce the graphs, tables, and text that make up the report. Notebooks can be run at the "building" level or the "organziation" level. A Building notebook is run for every building on a BMON server. Organization notebooks are run for each Organization. The report notebooks are stored in Git repositories along with some additional configuration information that indicates which BMON sites to run reports against. Here is an example of a Git repository that contains suitable Jupyter Notebooks and configuration info.

The configuration of this bmonreporter script is done with a YAML configuration file, patterned after this sample configuration file. The main purpose of the configuration file is to identify the Git repositories containing Jupyter Notebooks to process. Multiple Git repositories can be processed by one run of bmonreporter.

bmonreporter runs with Python 3.7+ and is installed by:

pip install bmonreporter

The server where bmonreporter is installed must have all of the Python packages used by the Jupyter Notebooks that are processed from the targeted Git repositories. Also, reports produced by bmonreporter and the log files for the script are generally stored in AWS S3 buckets. So, the server must have suitable priveleges to write to those buckets. bmonreporter uses the AWS command line utility to store files into S3 buckets. This utility is installed when bmonreporter is installed, but the utility must be configured according to this page, and this configuration process will configure proper credentials for writing to S3 buckets. bmonreporter uses a profile named "bmonreporter", so that profile must be set up in the AWS config and credentials files.

Use of bmonreporter just involves running the script with a command line argument pointing to the configuration file:

bmonreporter <path to configuration file>

for example:

bmonreporter /home/joeuser/config.yaml