用于 Nodoshop 版 Opentherm Gateway (OTGW) 的 ESP8266 设备板固件
Disclaimer: This is a development build, it is in Alpha state. This means it is not released nor supported at this point.
The 2.0.0 is unreleased software in the ALPHA state, only available for alpha testers at this point.
For the current 1.x.x releases, use the
otgw-1.x.xwork branch or the published releases.
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 that drives OpenTherm directly, without a PIC, also exists. It is a prototype and nothing more at this time.
Version 2.0.0 is a major platform release. It targets the ESP32-S3 in the traditional OTGW with PIC; the ESP8266 is no longer a 2.0.0 build target. The firmware builds from a single source tree via PlatformIO. If you are coming from a v1.x ESP8266 build, see Migrating from ESP8266 (1.x).
pio run -e esp32.platformio.ini builds the esp32 environment (default). The whole codebase builds from a single source tree.One small MQTT breaking change: three OT-bus presence topics (boiler_connected, thermostat_connected, otgw_connected) moved out of the hardware-specific otgw-pic/* and otgw-otdirect/* subtrees into the generic value namespace, regardless of hardware variant. Home Assistant users are unaffected (entity unique_ids are stable, discovery auto-republishes). The firmware self-heals retained payloads on the deprecated topics at first MQTT reconnect. Custom MQTT consumers should update their topic patterns: see the migration guide and ADR-084. REST API and settings.ini format are unchanged from v1.x.
The supported hardware is the NodoShop OTGW with the PIC co-processor and an ESP32-S3 (LOLIN S3 Mini) in the module socket:
| Feature | ESP32-S3 OTGW with PIC |
|---|---|
| OpenTherm via PIC co-processor | Yes (required) |
| Wi-Fi | Yes |
| OLED display | Yes |
| SAT thermostat | Yes |
| Dallas sensors | Yes |
| S0 pulse counter | Yes |
A prototype ESP32 board with onboard OpenTherm also exists. It is a prototype and nothing more at this time.
Firmware v1.x ran on the ESP8266 module that shipped on earlier NodoShop OTGW boards:
| NodoShop OTGW version | ESP8266 module (v1.x) |
|---|---|
| 1.x through 2.0 | NodeMCU ESP8266 |
| 2.3 and later | Wemos D1 mini ESP8266 |
The ESP8266 is no longer a 2.0.0 build target. To move an existing OTGW to v2.0.0, swap the Wemos D1 mini ESP8266 for a LOLIN S3 Mini (ESP32-S3) drop-in: it keeps the same OTGW board and PIC co-processor, and the firmware builds for it from the same source tree. Settings files from v1.3.x load without modification.
This ESP32-S3 plus PIC combination is what the firmware supports.
SAT is an embedded heating controller that runs entirely on the device. It replaces the room thermostat's role in controlling the boiler: it computes the optimal boiler flow temperature from outdoor temperature and room temperature error, learns your heating system's behaviour over time, and keeps your home at the target temperature without needing Home Assistant or any external controller to be involved in the control loop.
SAT combines a weather-compensated heating curve with a PID v3 controller. The heating curve calculates a base flow setpoint from outdoor temperature using a configurable coefficient. The PID loop adds a correction on top, based on the difference between actual and target room temperature. Over several days, the auto-tune function analyses heating cycles and adjusts PID gains automatically.
For detailed setup including OPV calibration and Home Assistant automation examples, see the SAT integration guide.
When SAT is enabled and MQTT is configured, Home Assistant receives:
climate entity with target temperature control and heat/off mode selectionCommands via MQTT or the REST API (/api/v2/sat/*) control all SAT parameters at runtime.
| Reference | Link |
|---|---|
| MQTT topics | docs/api/MQTT.md |
| Full SAT topic list | backlog/docs/doc-1 - sat-mqtt-topics.md |
| REST API | docs/api/openapi.yaml |
| OPV calibration guide | backlog/docs/doc-2 - sat-opv-calibration.md |
| Preset configuration | backlog/docs/doc-4 - sat-preset-configuration.md |
Recommended (downloads and flashes the latest release):
python3 flash_esp.pyBuild from source and flash:
pio run -e esp32 --target upload # ESP32See docs/FLASH_GUIDE.md for full instructions including filesystem flashing.
On first boot the device creates an access point named -. Connect to it. A captive portal opens where you enter your home Wi-Fi credentials. On an ESP32 board with a W5500 and an Ethernet cable plugged in, wired Ethernet is used directly and the Wi-Fi setup is optional.
Navigate to http:/// or http://otgw.local/. The dashboard shows the live OpenTherm log, temperatures, and boiler status.
Go to Settings and fill in your MQTT broker details. Enable HA Discovery. Click Save. Home Assistant discovers the device within seconds.
Go to Settings > Devices and Services > MQTT. The OTGW device appears with 250+ entities already created and ready to use.
Open http:/// and go to Settings.
| Setting | Description | Example |
|---|---|---|
| MQTT Broker | IP or hostname of your broker | 192.168.1.100 |
| MQTT Port | Broker port | 1883 |
| MQTT User | Broker username | mqttuser |
| MQTT Password | Broker password | (your password) |
| MQTT Top Topic | Prefix for all published topics | OTGW |
| MQTT Unique ID | Identifier for this device in HA | otgw |
| HA Discovery | Enables auto-discovery payloads | checked |
暂无开放 Issues,或尚未同步最近议题。