Release 0.0.1 Alan Mitchell
Total Page:16
File Type:pdf, Size:1020Kb
bmon Documentation Release 0.0.1 Alan Mitchell Sep 16, 2021 Users 1 User Introduction 3 2 System Administrator Introduction5 3 Developer Introduction 7 4 Contact Information 9 4.1 User Introduction.............................................9 4.2 System Administrator Introduction................................... 10 4.3 How to Install BMON on a Web Server................................. 13 4.4 How to Install BMON on a Local Web Server.............................. 18 4.5 Add Buildings and Sensors....................................... 27 4.6 Sharing BMON across Multiple Organizations............................. 40 4.7 Setting Up Sensors to Post to BMON.................................. 41 4.8 Multi-Building Charts.......................................... 60 4.9 Sensor Alerts............................................... 68 4.10 Creating a Dashboard.......................................... 74 4.11 Transform Expressions.......................................... 76 4.12 Calculated Fields............................................. 80 4.13 Periodic Scripts.............................................. 92 4.14 How to Create Custom Jupyter Notebook Reports........................... 107 4.15 Custom Reports............................................. 108 4.16 Backing Up and Analyzing Data from the System........................... 111 4.17 System Performance with High Loading................................ 113 4.18 Using CSV Transfer........................................... 115 4.19 Developer Introduction.......................................... 120 4.20 BMON Architecture........................................... 120 4.21 Writing Periodic Scripts......................................... 126 4.22 Accessing Data in BMON: API and Python Library.......................... 129 4.23 Contact Information........................................... 135 i ii bmon Documentation, Release 0.0.1 Copyright (c) 2014, Alaska Housing Finance Corporation. All Rights Reserved. BMON is a web-based software application that stores and analyzes sensor data coming from buildings or other facilities. The application was developed by the Alaska Housing Finance Corporation (AHFC) to find ways to reduce the energy use and improve the maintenance of their buildings. The application presents a simple user interface for viewing data, but includes informative charts such as Histograms and Hourly Profile charts for analyzing the data. Alerts can be set up to text or email individuals if sensor values move outside normal ranges. Here is a link to the AHFC BMON Web Site Here is a screenshot of the application being used to look at the electricity usage of the AHFC Headquarters building (the green bands indicate the building’s occupied periods): Note that a major upgrade to Python 3.7 occurred on May 1, 2019. Upgrade of existing systems running the Python 2.7 version will require assistance from the developer, Alan Mitchell, [email protected]. Please contact him before attempting an upgrade. The documentation for the BMON software is divided into three main sections, described below. Users 1 bmon Documentation, Release 0.0.1 2 Users CHAPTER 1 User Introduction This section contains documentation for users who are viewing and analyzing the data in the system. This documen- tation does not address any issues related to installing and configuring the system. 3 bmon Documentation, Release 0.0.1 4 Chapter 1. User Introduction CHAPTER 2 System Administrator Introduction This section describes how to install the BMON application on a web server, which will require some basic skills with Linux system administration. This section also describes how to setup and configure the specific buildings and sensors for your system. The setup of sensors and buildings does not require any sophisticated IT skills; it is accomplished through a web interface after logging on to the system as an administrator. 5 bmon Documentation, Release 0.0.1 6 Chapter 2. System Administrator Introduction CHAPTER 3 Developer Introduction This section provides documentation for developers who want to modify the code of the BMON system. The source code of the project is internally documented with comments, but the documentation in this section explains the overall structure of the application. The GitHub repository holding the source code is located here 7 bmon Documentation, Release 0.0.1 8 Chapter 3. Developer Introduction CHAPTER 4 Contact Information Contact information for key BMON personnel and developers is available here. 4.1 User Introduction A number of training videos have been developed to explain the features of the BMON system. The table below summarizes the available videos. 9 bmon Documentation, Release 0.0.1 Video Title Description Basic Features of This video shows how to select various various reports and graphs for each building. The the AHFC BMON video also explains a number of graphing features, such as zooming, highlighting points, and Web Application hiding data series on the graph. These features are common to all the graphs on the web site, (9 minutes) and this video is an important one to watch prior to watching the videos below. Multiple Building This video explains the graphs that are available to compare energy use across multiple build- Comparisons and ings that are being monitored. It also describes the “Current Values” report, which shows the Current Values current sensor readings for any one building. Report (13 Minutes) “Plot over Time” This video explains the “Plot over Time” graph, also known as the “Time Series” plot. This Chart (Time Series graph lets you display how one or more sensor values change over time. This is the workhorse Graph) graph of the system, so this video is important. (8 minutes) Hourly Profile This video explains the “Hourly Profile” chart. This graph lets you chart how a sensor’s value Chart changes throughout the day (hourly). It also allows you to select particular days to look at, (8 minutes) such as Monday through Friday or just Saturday. Histogram Chart This video explains the “Histogram” chart. This graph is good for learning about the range of (6 minutes) values measured by a sensor. It also shows you the values that are recorded most frequently and least frequently. Download Sensor This video explains how to download sensor data into an Excel spreadsheet. Data as Excel Spreadsheet (5 minutes) 4.2 System Administrator Introduction This documentation explains how to install and configure the system for your particular buildings and sensors. These activities should be the task of one or two system administrators who have more experience with BMON than the general Users who are simply interested in viewing and analyzing the data. The separate system administrator topics are summarized below, and the associated documents are available through the sidebar on the left or by clicking on the section headings below. 4.2.1 BMON Installation This document gives instructions for installing BMON on a web server. Linux skills and preferably some experience with Python and Django are necessary to perform this task. 4.2.2 Local BMON Installation This document gives instructions for installing BMON on a local web server. Linux skills and preferably some expe- rience with Python and Django are necessary to perform this task. 4.2.3 Adding Buildings and Sensors After installing BMON, you will need to configure your Buildings and Sensors in the system. This document shows how to do that using the web-based Admin interface of the BMON system. 10 Chapter 4. Contact Information bmon Documentation, Release 0.0.1 4.2.4 Sharing BMON Across Multiple Organizations A single BMON server can be shared across multiple organizations. This document describes how that is accom- plished. 4.2.5 Setting Up Sensors to Post to BMON A few different sensor types have been set up to work with BMON (e.g. Monnit Wireless Sensors). Other sensors that have access to the Internet can be configured to work with BMON. This document gives details on how to set up sensors in the system. 4.2.6 Multi-Building Charts BMON can produce some reports and graphs that compare data across buildings. These multi-building charts need to be configured through the web-based Admin interface. Single building reports and charts work out-of-the-box without additional configuration. 4.2.7 Sensor Alerts You can have BMON send you a text message or email if important sensor conditions occur, such as Domestic Hot Water temperatures that are too low. This document details how to configure this feature. 4.2.8 Creating A Dashboard A summary “Dashboard” can be created for any of the buildings in the BMON system. Here is an example: This document describes how Dashboards are created. 4.2. System Administrator Introduction 11 bmon Documentation, Release 0.0.1 4.2.9 Custom Reports This document explains how to create Custom Reports. A Custom Report allows you to combine any number of graphs, dashboards, or current value reports onto one page. The various elements can even come from different buildings. 4.2.10 Transform Expressions Some sensors do not send data in a displayable format, some sensors have small errors that need correction. “Trans- form” expressions allow you to convert units or transform values before storage and display in BMON. This document explains how to set up transform values for your sensors. 4.2.11 Calculated Fields This document explains how to work with calculated fields. Occasionally, you may want to calculate a value from multiple different sensors or have one sensor display its value