百科.dev
全部条目在线工具AI 编程趋势榜开源项目技术资讯提交条目
登录
< 返回工具列表
O

OTGW-firmware

> 编程语言
开源

用于 Nodoshop 版 Opentherm Gateway (OTGW) 的 ESP8266 设备板固件

199 stars0 点赞1 次浏览
访问官网GitHub

工具介绍

用于 Nodoshop 版 Opentherm Gateway (OTGW) 的 ESP8266 设备板固件

OTGW-firmware v2.0.0

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.x work 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.


What's New in v2.0.0

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).

Highlights

  • 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.

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.


Features at a Glance

Core features

  • Full OpenTherm bus monitoring: all 80+ message IDs decoded in real time
  • MQTT integration with 250+ Home Assistant auto-discovery entities
  • Web interface: live OT log, real-time graphs, dark/light theme, settings panel
  • REST API v2 with consistent JSON and proper HTTP status codes
  • SAT (Smart Autotune Thermostat): weather-compensated PID heating controller
  • DS18B20 Dallas temperature sensors with custom labels (up to 16)
  • S0 pulse-counting energy meter
  • SSD1306 OLED display (128x64, I2C, 4 pages)
  • OTA firmware and filesystem updates via the web interface
  • TCP serial bridge on port 25238 (OTmonitor, HA built-in integration)
  • Telnet debug log on port 23
  • Webhook callbacks on OpenTherm status bit changes
  • Triple-reset Wi-Fi credential recovery
  • Optional HTTP Basic Auth for settings and maintenance endpoints

Hardware Support

Platform overview

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.

Migrating from ESP8266 (1.x)

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: Smart Autotune Thermostat

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.

What SAT does

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.

Key capabilities

  • Weather compensation: configurable heating curve coefficient; curve recommendation based on error statistics
  • PID v3 control: proportional + integral + derivative correction with automatic gain tuning
  • Two control modes: continuous modulation (direct boiler modulation) and PWM flame cycling (on/off duty cycle)
  • Heating system types: radiators, underfloor heating, heat pump
  • Six presets: comfort, eco, away, sleep, activity, home, each with a configurable target temperature
  • Multi-zone room temperature: averages readings from up to four sources (OT, MQTT, BLE, Dallas)
  • BLE room sensor (ESP32 only): reads temperature and humidity from a Xiaomi LYWSD03MMC via BTHome v2
  • Solar gain compensation: detects solar gain from indoor temperature rise rate and sun elevation angle; reduces setpoint to prevent overheating
  • Summer Simmer Index: calculates perceived outdoor heat; suppresses heating when the index stays above a threshold
  • Summer suppression: independent outdoor-temperature-based heating cutoff with configurable duration threshold
  • Pressure monitoring: tracks system pressure; raises alarm on low pressure or fast pressure drop
  • OPV calibration: finds the boiler's Overpressure Valve temperature so SAT stays below it
  • Six safety layers: flame health, CH circuit sync, setpoint mismatch, pressure, cycle classification, overshoot detection
  • Open-Meteo integration: optional free weather API for outdoor temperature when no local source is available
  • OpenWeatherMap (OWM) support: optional API key for outdoor temperature fallback, rate limited to one call per 15 minutes

Quick start

  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.

For detailed setup including OPV calibration and Home Assistant automation examples, see the SAT integration guide.

Home Assistant integration

When SAT is enabled and MQTT is configured, Home Assistant receives:

  • A climate entity with target temperature control and heat/off mode selection
  • 40+ sensor and binary_sensor entities for SAT state, diagnostics, and settings
  • BLE sensor entities (ESP32 only): temperature and humidity per sensor

Commands 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

Quick Start

1. Flash the firmware

Recommended (downloads and flashes the latest release):

bash
python3 flash_esp.py

Build from source and flash:

bash
pio run -e esp32 --target upload    # ESP32

See docs/FLASH_GUIDE.md for full instructions including filesystem flashing.

2. Connect to Wi-Fi

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.

3. Open the Web UI

Navigate to http:/// or http://otgw.local/. The dashboard shows the live OpenTherm log, temperatures, and boiler status.

4. Configure MQTT

Go to Settings and fill in your MQTT broker details. Enable HA Discovery. Click Save. Home Assistant discovers the device within seconds.

5. Check Home Assistant

Go to Settings > Devices and Services > MQTT. The OTGW device appears with 250+ entities already created and ready to use.


Setting Up MQTT with Home Assistant

Prerequisites

  • Home Assistant with the MQTT integration installed (Settings > Devices and Services > MQTT).
  • An MQTT broker running (Mosquitto add-on, or an external broker).
  • Your OTGW device connected to the same network.

Step 1: Configure MQTT in the web UI

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

Step 2: Verify in Home Assistant

Issues· 0 开放

查看全部 Issues在 GitHub 打开

暂无开放 Issues,或尚未同步最近议题。

> 标签

C++esp8266home-assistanthome-automationhomeassistant

暂无评论,来聊聊你的看法吧

> 工具信息

发布日期2026年8月1日
最后更新2026年9月18日
分类编程语言
定价开源

> 相关工具

T
TypeScript
JavaScript 的超集,为前端与全栈提供静态类型
P
Python
通用编程语言,广泛用于 Web、数据与 AI
G
Go
Google 推出的简洁高效系统语言