This API facilitates access to much of the telemetry data produced by my US Boiler/Burnham Alpine boiler via the "Boiler to Boiler" RJ45 port. The built-in "Sage2" controller exposes nearly all the data available on the boiler's LCD display over this interface.
This has only been tested with my ALP105BW-4T02, but will probably work for other Sage2-era boilers. A register-scanning routine is included to discover additional registers on other Sage2 versions and models.
This code works well via a cron script (log_thingspeak.py) to log readings from my boiler to thingspeak.com.
- Debug installation issues, e.g. short cycling
- Track operation and usage
- Mini-Monitor contains a simpler minimalmodbus-based API (minimalmodbus supports only Modbus/RTU)
- Sage2 Controller Modbus Interface Documentation (circa 2012)
- Honeywell SOLA Modbus Inferface Specification
- Found in excellent Mini-Monitor docs linked above!
- modbus-tk is a uniform Modbus RTU and TCP implementation in python
The boiler has two RJ45 ports
| Port | Protocol | Purpose |
|---|---|---|
| White | EnviraCom | Suitable for connection to Sage Zone Control panels and a specfic model of Honeywell thermostat (TH9421C1004, now obsolete and not available for sale). Be careful connecting to this port as EnviraCom uses 24VAC signalling |
| Black | RS485 | API access, Boiler to Boiler communication over Modbus/RTU at 38.4kbps |
Both ports are intended to daisy chain multiple controls/boilers together using a bus topology using splitters, e.g. http://www.l-com.com/ethernet-modular-tee-adapter-8x8m-8x8kf-8x8kf
Any RS485 interface should work. Mine is a bare-wire USB-RS485 FTDI Adapter with a suitably crimped RJ45 jack.
The API works with either a directly connected serial interface (via PySerial), or a Modbus/TCP bridge (bridging Modbus over Ethernet makes it easier to develop software without being physically connected to the boiler). mbusd or any hardware Modbus/RTU to Modbus/TCP bridge will work.
This API accesses the entire array of Modbus registers using a handful of Modbus reads and caches results with a configurable TTL. Reading and reporting all known registers takes a few hundred milliseconds.
API contains a __main__ that dumps current boiler state and illustrates usage:
$ python sage_boiler.py localhost
Reading Raw Value Units
--------------------------------- ----- ---------------------- -------
Active CH Hysteresis (off) 44 39.9 F
Active CH Hysteresis (on) 38 38.8 F
Active CH Operating Point 735 164.3 F
Active CH Setpoint 734 164.1 F
Active DHW Hysteresis (off) 55 41.9 F
Active DHW Hysteresis (on) 38 38.8 F
Active DHW Operating Point 795 175.1 F
Active DHW Setpoint 767 170.1 F
Active LL Operating Point -400 -40 F
Active LL Sensor 5 Header Sensor (S5)
Active LL Setpoint 777 171.9 F
Active Sensor (CH) 5 Header Sensor (S5)
Active Sensor (DHW) 2 Outlet Sensor (S3S4)
Active System Hysteresis (off) 44 39.9 F
Active System Hysteresis (on) 38 38.8 F
Active System Operating Point 735 164.3 F
Active System Sensor 5 Header Sensor (S5)
Active System Setpoint 734 164.1 F
Burner State 12 Run
Cycle Count (Boiler Pump) 2202 2202 cycles
Cycle Count (Burner) 4270 4270 cycles
Burner Run Time 2735 2735 hours
Cycle Count (CH Pump) 78 78 cycles
Cycle Count (DHW Pump) 879 879 cycles
Demand (CH) 1 On
Demand (DHW) 0 Off
Demand (Frost) 0 Off
Demand (LL) 0 Off
DHW Priority Timer 0 0.0 sec
Firing Rate (Measured) 2555 57 %
Firing Rate (Requested) 2537 57 %
Flame Signal 1305 13.1 μA
Header Sensor 735 164.3 F
Header Sensor State 1 Normal
Outdoor Sensor -122 10.0 F
Outdoor Sensor State 1 Normal
Pump Status (Boiler) 124 On, from burner demand
Pump Status (CH) 123 Off, not needed
Pump Status (DHW) 123 Off, not needed
4-20mA Remote Control Input State 2 Open
Requested Rate (CH) 2537 57 %
Return Sensor 719 161.4 F
Return Sensor State 1 Normal
Setpoint Source (CH) 3 Outdoor Reset Setpoint
Setpoint Source (DHW) 1 CH Setpoint
Setpoint Source (LL) 1 CH Setpoint
Stack Sensor 750 167 F
Stack Sensor State 1 Normal
Supply Sensor 795 175.1 F
Supply Sensor State 1 Normal
A trivial logging script that stores a subset of the available data using SQLite3
is included in log_sqlite3.py. This script can be run periodically by cron.
For example, on a Linux host the user might issue crontab -e to edit their crontab and add the following line to log the state of the boiler every minute:
* * * * * ~/sage2-boiler/log_sqlite3.py
Be sure the required libraries listed in requirements.txt are installed and available
Alternatively, log_influxdb.py logs all of the available data to an InfluxDB instance.
Run log_influxdb.py --help for a list of options. It also requires the InfluxDB python
client library; see the script header comment for details.