Available Sensor Readers

This document summarizes the Sensor Reader classes that are currently available for the Mini-Monitor. Each of these classes knows how to read data from a particular type of device. As described on the main Software document, a Reader is enabled in the READERS variable found in the Mini-Monitor settings file.

Starting with Version 1.7, Mini-Monitor has an additional method to acquire sensor data, separate from the Sensor Reader classes described in the prior paragraph. Scripts or programs can be written to publish data to the Mini-Monitor MQTT broker (for more about the MQTT broker, see the Notes for Developers. That sensor data is then posted directly to a BMON server without the use of a Reader class. This technique is used to read data from Utility Meters, this script is discussed later in this document.

Sensor Reader Classes

Each section below describes a Reader and lists the sensor information that is returned by the Reader. For each sensor read by the Reader, the following information is returned:

Sensor ID: This is a string ID that identifies the particular sensor being read.

Value: This is the current numeric sensor reading.

Reading Type: This indicates the type of value being read by the sensor, with the following three possibilities:

  • VALUE: An analog value that varies continuously across a range of possible values. For this Reading Type, the Mini-Monitor will average all of the sensor values that are read during a logging period and post that average value to the BMON web database.
  • STATE: Discrete values that indicate the sensor is in a particular mode or state. Examples include On/Off switch values, or alarm states for a particular device. During one logging period, the Mini-Monitor will post a reading to BMON every time the sensor state value changes. In addition, the Mini-Monitor will always post the last state value read during the logging period.
  • COUNTER: A sensor having a Reading Type of counter is one that accumulates a count of some quantity, e.g. energy used or gallons of flow. For counter sensors, the Mini-Monitor will post the last counter value read during a logging period.

Currently Available Sensor Readers

1-Wire Sensor Reader

Class Name: ha7s.HA7Sreader

This Reader was named after the Embedded Data Systems HA7S hardware module used to read the 1-Wire sensors and reads Maxim DS18B20 1-Wire Temperature Sensors (Family Code 28) and sensors utilizing the Maxim DS2406 1-Wire chip (Family Code 12) to sense the On/Off state of a device. Analysis North sells an easily-installed motor/pump/zone valve/gas valve sensor utilizing this chip that can interface to the Mini-Monitor through the 1-Wire network.

The Mini-Monitor hardware components associated with this Reader are the CV3 and PS2 components described in the Hardware document. The Reader returns the current sensor readings for all of the compatible 1-Wire sensors on the network. The table below shows the information returned for each compatible type of 1-Wire sensor:

Sensor Type Sensor ID Value Reading Type
Family Code 28 Temperature Sensors Unique 1-Wire ID of the Sensor, e.g. 28.EFED4C 050000 Temperature in degrees F VALUE
Family Code 12 Switch/State Sensors Unique 1-Wire ID of the Sensor, e.g. 12.FDF4A0 000000 The state of Channel A of the Sensor: 1 for High Voltage, 0 for Low Voltage STATE

Sage 2.1 Boiler Control (used in Burnham Alpine Boilers)

Class Name: sage_boiler.Sage21Reader

This reader reads numerous values present in a Sage 2.1 Boiler Control, which is the boiler control used by Burnham Alpine condensing boilers. The values are read through an RS-485 connection to the boiler, using the MODBUS protocol. The Sage 2.1 control is manufactured by Honeywell and is known as the SOLA control when sold directly by Honeywell. The MODBUS manual for the Honeywell SOLA boiler controller can be found here.

The RS485 connection to the boiler is on the left side of the boiler. There are two RJ45 jacks (8-pin network-type jacks). A standard CAT-5/6 network cable can be used to connect to the boiler, and the top jack, labeled “Boiler-to-Boiler” must be used. Also, you must set the “Boiler Address” to 1 in order to read data from the boiler. This is done on the “Adjust”, “Sequence Slave”, “Boiler Address” menu item available through the touch screen control on the boiler. The Factory default for this setting is “None”, so it must be changed in order for the monitoring system to work.

The table below shows the values that are read from the controller. Refer to MODBUS manual for more detail on the values. The Sensor ID values all start with the <LOGGER_ID>, which is the unique ID value that is entered into the Mini-Monitor settings file, as described in the Software document. For example, if the LOGGER_ID for a particular Mini-Monitor is Burton152, the first sensor value in the table below will have the Sensor ID of Burton152_firing_rate.

Sensor ID Value Reading Type
<LOGGER_ID>_alert_code Boiler alert code, if any; see Table 11 in MODBUS manual STATE
<LOGGER_ID>_firing_rate Boiler firing rate in % of maximum VALUE
<LOGGER_ID>_limits Indicates when a Boiler Limit, such as Outlet High Temperature Limit, is reached STATE
<LOGGER_ID>_demand_source Source of demand that that caused the boiler to fire, either Space Heat or Domestic Hot Water STATE
<LOGGER_ID>_outlet_temp Boiler outlet temperature, degrees F. VALUE
<LOGGER_ID>_flame_signal Flame signal, Volts VALUE
<LOGGER_ID>_inlet_temp Boiler return water temperature, degrees F. VALUE
<LOGGER_ID>_stack_temp Boiler stack temperature, degrees F. VALUE
<LOGGER_ID>_ch_setpoint Space Heating boiler temperature setpoint, degrees F. VALUE
<LOGGER_ID>_dhw_setpoint DHW boiler temperature setpoint, degrees F. VALUE
<LOGGER_ID>_active_setpoint Currently active boiler setpoint, degrees F. VALUE
<LOGGER_ID>_lockout_code Boiler Lockout code, if any; see Table 9 in MODBUS manual STATE
<LOGGER_ID>_alarm_reason Indicates whether the Alarm is a Lockout or an Alert STATE
<LOGGER_ID>_ch_demand Indicates if there is a call for space Heat STATE
<LOGGER_ID>_dhw_demand Indicates if there is a call for DHW heat STATE
<LOGGER_ID>_outdoor_temp Outdoor temperature as read by boiler outdoor temperature sensor, degrees F. VALUE
<LOGGER_ID>_alarm_code Boiler alarm code, if any STATE

AERCO BMS II Boiler Manager

Class Name: aerco_boiler.BMS2reader

This reader reads values present in an AERCO BMS II Boiler Manager, which controls a bank of AERCO boilers. The AERCO BMS II manual is here, and Appendix H contains documentation of the MODBUS registers. The Reader obtains values from the controller using the MODBUS protocol across an RS232 connection to the boiler.

The table below shows the values that are read from the controller. Refer to the BMS II manual for more detail on the values. The Sensor ID values all start with the <LOGGER_ID>, which is the unique ID value that is entered into the Mini-Monitor settings file, as described in the Software page.

Sensor ID Value Reading Type
<LOGGER_ID>_firing_rate Firing rate as a % of maximum. All boilers fired have this same firing rate, as the load is spread evenly across fired boilers VALUE
<LOGGER_ID>_boilers_fired The number of boilers currently fired STATE
<LOGGER_ID>_firing_rate_tot The firing rate times the number of boilers fired, % VALUE
<LOGGER_ID>_header_temp Temperature of the boiler outlet header, degrees F. VALUE
<LOGGER_ID>_outdoor_temp Outdoor temperature as read by the controller outdoor temperature sensor, degrees F. VALUE
<LOGGER_ID>_header_setpoint Target setpoint temperature for the boiler outlet header, degrees F. VALUE
<LOGGER_ID>_boilers_online Number of boilers online and able to be fired STATE
<LOGGER_ID>_fault_code ode Indicates type of fault that has occurred STATE
<LOGGER_ID>_lead_boiler Number of the Lead boiler, 1 - 32 STATE
<LOGGER_ID>_boiler1_status Gives online and firing status of Boiler #1 STATE
<LOGGER_ID>_boiler2_status Gives online and firing status of Boiler #2 STATE
<LOGGER_ID>_io_status Gives status of the boiler relays STATE

Sensaphone Reader

Class Name: SensaphoneReader

This reader reads values from the Sensaphone Infrastructure Management System host unit (IMS-4000). The reader uses the Simple Network Management Protocol (SNMP) to access the IMS-4000 host, which in turn is connected to up to 32 different remote sites. Each remote site can have up to 8 environmental sensors. The manual for the IMS-4000 can be found here.

The reader will access and return data for each of the sensors attached to each remote site connected to the IMS-4000. There are a variety of sensors that can be connected at each site, including sensors that monitor temperature, relative humidity, flow, presence of water, and more. For details on the values reported by individual sensors, see the IMS-4000 manual. Each of these sensors is named by the user; the sensor IDs reported in the mini-monitor program are named using the following pattern:


Note that underscores are used in place of spaces in this naming pattern. Currently, due to the limitations of the SNMP interface, all recorded data is reported as integers of the “VALUES” reading type.

System Information Reader

Class Name: sys_info.SysInfo

This Reader reports some basic information about the Mini-Monitor hardware and software. It reads the values directly from the Raspberry Pi without the need for any additional attached hardware. Here are the values reported:

Sensor ID Value Reading Type
<LOGGER_ID>_uptime Number of seconds that the Pi has been operating since the last reboot COUNTER
<LOGGER_ID>_cpu_temp CPU temperature of the Pi, degrees C. VALUE
<LOGGER_ID>_version Mini-Monitor software version number. STATE

Power Outage Monitor Reader

Class Name: outage_monitor.OutageMonitor

This reader was designed to sense the presence or absence of AC Mains Power. A power sensor is used to put a 3.3V signal on the Raspberry Pi pin 16 (BCM numbering) when AC power is present and a 0V signal on the pin when power is absent. This reader will report the state of the pin:

Sensor ID Value Reading Type
<LOGGER_ID>_state 1 = Pin 16 in High state, 3.3V; 0 = Pin 16 in Low state 0 V. STATE

This reader could be used for any sort of digital input on Pin 16.

Other Sensor Readers

There are a number of other sensor readers that have been created for specific projects and not documented here in detail. Those Readers include ones for reading thermistors connected to a Labjack U3 data acquisition board and reading gauge air pressure measured by an Energy Conservatory DG-700 Pressure Gauge. You can find these in the readers directory of the project code.

Scripts that Post Data directly to the MQTT Broker

Script to Read Utility Meter Radio Transmissions

The Mini-Monitor is able to read Utility meters (natural gas, electric, and water) that utilize the Itron ERT radio transmission format to broadcast their readings in the 900 MHz ISM band to meter readers driving through the neighborhood. The hardware required for receiving these transmissions is described in the Hardware document. To enable and configure the Meter Reading script, see the Mini-Monitor section in the Software document.

Utility meters are typically counters that accumulate the total amount of gas, electricity, or water consumed. Instead of reporting a cumulative amount, this script determines the rate of change in the meter reading and reports that value, expressed in change in meter reading per hour. For example, if a natural gas meter reads 10,123 cubic feet at Noon and then reads 10,145 cubic feet at 12:30 pm, the change in reading was 22 cubic feet and it occurred over a half hour period. The script will report a value of 44 cubic feet per hour, since this is the rate of change expressed using an hourly time base. Multipliers are available in the Settings file to translate these values to other units (such as Btu/hour), if desired.

Here is the summary table showing the fields reported by the script. An example of a Sensor ID for an installation with a LOGGER_ID of 123main would be 123main_12_32707556. The 12 is the Commodity Type transmitted by the meter and 32707556 is the ID of the meter. The Commodity Type and the Meter ID are generally found on the nameplate of the meter.

Sensor ID Value Reading Type
<LOGGER_ID>_<COMMODITY_TYPE>_<METER_ID> Meter Reading Change per Hour VALUE

Here is a table showing how Commodity Type numbers translate into actual metered commodities:

Commodity Commodity Type Numbers
Electric 04, 05, 07, 08
Gas 02, 09, 12
Water 11, 13