OTGW Firmware

Abstract

1. Introduction

OTGW-firmware turns the NodoShop OpenTherm Gateway into a networked smart heating controller. It runs on an ESP32-S3 (LOLIN S3 Mini) in the traditional NodoShop OTGW with the PIC co-processor, monitors the OpenTherm bus between your thermostat and boiler, and connects your entire heating system to your home automation platform via MQTT, a browser-based web interface, and a REST API. That combination is the supported hardware.

A prototype ESP32 board with onboard OpenTherm also exists. It is a prototype and nothing more at this time.

A prototype ESP32 board that drives OpenTherm directly, without a PIC, also exists. It is a prototype and nothing more at this time.

2. Objective

A ESP8266 devkit firmware for the Nodoshop version of the Opentherm Gateway (OTGW)

This project demonstrates how C++, ESP8266, MQTT can be applied to a real-world Internet of Things (IoT) problem.

3. Key Features / Modules

• ESP32-S3 platform: Native ESP32 support on the traditional OTGW with PIC, using a LOLIN S3 Mini in place of the old Wemos D1 mini. This is the supported hardware. Build with pio run -e esp32.
• OTDirect: ESP32-only direct GPIO OpenTherm master/slave. Five operating modes let the ESP32 act as thermostat, boiler, gateway, monitor, or a combined master+slave pair, all without a PIC co-processor.
• Ethernet (W5500): Wired Ethernet via W5500 SPI on ESP32 hardware that provides it. The firmware auto-detects cable presence and switches between Ethernet and Wi-Fi, with transparent failover in both directions.
• BLE temperature sensors: On ESP32, up to four Xiaomi LYWSD03MMC sensors are read passively over Bluetooth LE using the BTHome v2 protocol. Room temperature and humidity feed directly into SAT and Home Assistant.
• OLED display: 128x64 SSD1306 I2C display on both platforms. Four information pages (status, temperatures, network, boiler). Button cycles pages; display auto-off after configurable timeout.
• SAT enhancements: Summer Simmer Index, improved solar gain compensation, expanded multi-zone support, and BLE sensor integration.
• 250+ Home Assistant entities: Full climate entity, all SAT entities, pressure monitoring, BLE sensor entities, and OLED status — all via MQTT auto-discovery.
• Wi-Fi resilience: AP fallback mode (beta) keeps the web UI reachable when the home network is unavailable. Wi-Fi signal quality indicator in the web UI header. Triple-reset credential recovery.
• PlatformIO build: platformio.ini builds the esp32 environment (default). The whole codebase builds from a single source tree.
• Full OpenTherm bus monitoring: all 80+ message IDs decoded in real time

4. Technology Stack

5. System Requirements

General requirements for this technology stack — check the README for exact versions.

• Arduino IDE / PlatformIO or a C++ compiler (g++)
• Target board (e.g. Arduino, ESP32) where applicable
• Git (to clone the repository)

6. Installation & Setup

git clone https://github.com/rvdbreemen/OTGW-firmware.git
cd OTGW-firmware

1. Open the OTGW web interface and go to SAT in the navigation.
2. Enable SAT and set your target room temperature.
3. Select your heating system type (radiators / underfloor / heat pump).
4. Enter your boiler capacity in kW.
5. Set an initial heating curve coefficient (start with 1.0 for radiators, 0.6 for underfloor; the curve recommendation will guide further tuning).
6. Save. SAT takes over the flow setpoint immediately. Let auto-tune run for a few days to optimize PID gains.

Full setup instructions are in the project README.

7. Future Enhancements

Suggested extensions you can add to make this your own project.

• Add a mobile dashboard using Blynk or Firebase
• Store readings in a cloud database for history charts
• Add alerts via SMS / Telegram when thresholds are crossed

8. Viva / Review Questions

Common questions examiners ask for projects in this domain.

1. Which microcontroller / board and sensors are used and why?
2. How does the device send data (Wi-Fi, MQTT, HTTP, Bluetooth)?
3. Where is the sensor data stored and visualised?
4. How is power consumption managed?
5. How would you secure the device and its communication?

9. Source Code & License

This project is developed by rvdbreemen and published on GitHub under the GNU General Public License v3.0. Please follow the license terms and credit the original author when you use or modify this code.