OTGW-firmware (ESP8266) for NodoShop OpenTherm Gateway
This repository contains the ESP8266 firmware for the NodoShop OpenTherm Gateway (OTGW). It runs on the ESP8266 "devkit" that is part of the NodoShop OTGW and turns the gateway into a standalone network device.
⚠️ This is the development branch (
dev). Active development for the next release (v1.7.0-beta.4) happens here. For the latest stable release, see v1.6.1.
What's New in v1.6.1
v1.6.1 is a focused follow-up to v1.6.0. It makes MQTT on-change publishing the default, redesigns the boiler-unsupported diagnostics panel, and lands a set of MQTT and Web UI reliability fixes.
MQTT
- On-change publishing is now the default (ADR-081): the new
MQTTonChangePublishingsetting defaults totruewithMQTTinterval=60. Changed values publish immediately; unchanged values refresh once per minute as a heartbeat instead of on every repeated frame, cutting broker traffic while keeping Home Assistant fresh. A Publish on change checkbox and tooltips were added to Settings > MQTT. ExistingMQTTinterval=0installs are migrated once to60on upgrade. - Truncated-publish protection: a partial or failed chunk write now drops the TCP connection instead of finalising a truncated discovery or value publish.
- Publish timing jitter: periodic timers are spread with a small random offset so they no longer fire together and cause a burst-publish heap spike.
Web UI and diagnostics
- Redesigned boiler-unsupported panel: the "Boiler does not implement these OpenTherm messages" notice is now a clean table (MsgID, Description, OpenTherm Name, Direction) with human-readable names, styled as a notice card in light and dark themes.
- Styling updates reliably after a flash: CSS is served with
no-cache+ ETag revalidation instead of a long browser cache (one hard refresh may be needed the first time after upgrading). - Mobile settings layout and statistics table column resizing fixes; boiler tooltip exposed.
Tooling
scripts/capture-mqtt-debug.bat: Windows helper to capture MQTT debug output for issue reports.
Full release notes: RELEASE_NOTES_1.6.1.md
Breaking changes: docs/BREAKING_CHANGES.md
Full per-commit detail: CHANGELOG.md. Architectural rationale in the linked ADRs under docs/adr/.
What's New in v1.6.0
v1.6.0 is a significant feature release that delivers MQTT/HA reliability fixes, static IP address configuration, a bilateral OpenTherm bus support map, and systematic mainloop performance improvements. Shipped after 25 beta builds and extensive community testing.
MQTT and Home Assistant
- HA entities no longer flap
unavailable(ADR-074, regression fix): availability now reflects the MQTT link; OT-bus liveness moves tootgw_connected. Contract change: migrate consumers reading the base topic as OT-bus liveness tootgw_connected. - HA capability-flag bits 2-5 (cooling, OTC active, CH2 active, summer/winter) fixed (ADR-076): no longer stuck at
unknown. - MQTT proxy-answer routing fixed (ADR-075): MsgIDs without a boiler response route correctly.
- Pure JIT MQTT discovery (ADR-073): OT MsgID configs publish on first MsgID reception, not at boot.
- HA PIC-control entities:
buttonandselectentities for PIC reset and mode controls under pseudo-ID 251. - Standalone HA discovery topic wiper: clean stale retained topics from the broker after an upgrade.
Settings and networking
- Static IP address settings (TASK-548, TASK-709): fixed IP, subnet, gateway, and DNS servers with a "Use DHCP" toggle, DHCP-prefill, and segmented octet inputs with ARIA accessibility.
Web UI and diagnostics
- Bilateral OT-bus support map (#640): see which MsgIDs your thermostat and boiler are exchanging, with "T / B / T+B" labels in telnet and
GET /api/v2/otgw/support-map. - Statistics table drag-to-resize columns (TASK-703): column widths saved in localStorage.
- LittleFS size display fixed (TASK-701): was reporting 1 MB instead of 2 MB.
- OT log auto-scroll preserved (TASK-701): no longer resets on tab switch.
- "Update Firmware" button visible on touch-capable desktops (#575).
logHeapStatslifetime counters (TASK-697): correct monotonic totals, not ephemeral window resets.
Performance
- Mainloop responsiveness: four audit rounds removed all blocking
delay()calls from the cooperative path, boundedhandleOTGW()drains, removedStringfrom hot paths, and madeemergencyHeapRecovery()a real recovery routine (TASK-651, 671, 673, 674).
Full release notes: RELEASE_NOTES_1.6.0.md
Breaking changes: docs/BREAKING_CHANGES.md
Full per-commit detail: CHANGELOG.md under ## [1.6.0]. Architectural rationale in the linked ADRs under docs/adr/.
What's New in v1.5.0
v1.5.0 is the first stable release of the 1.5.x long-term-support line on Arduino Core 2.7.4. It ships 29 beta builds worth of fixes, MQTT improvements, and Home Assistant discovery refinements.
- Sibling-suffix MQTT topic shape (ADR-070/071):
TSet_thermostat/TSet_boilerinstead ofTSet/thermostat/TSet/boiler— source-variant entities now actually register in HA for the first time. - Worldview semantics for /thermostat and /boiler (ADR-069): each sub-topic reflects the correct actor perspective.
- Human-readable HA discovery friendly names (ADR-072): entity names use spaces and Title Case;
unique_idunchanged so automations are unaffected. - HA discovery for diagnostic topics: PIC and firmware metrics publish proper HA sensors.
- GET /api/v2/debug: one-call diagnostic dump for troubleshooting and field support.
- MQTT topic flapping fixed (ADR-066): base topic uses Read-Ack and Write-Data only;
bSlaveEchoesValueper-MsgID flag gates the boiler echo path. - TSet flip for heat-pump stability: MsgID 1
bSlaveEchoesValue=falsestops flapping on non-echoing boilers. - No-Python flash and build scripts:
flash_otgw.sh/flash_otgw.batandbuild.sh/build.bat. - Arduino Core 2.7.4 baseline: partition layout retained at
eesz=4M2M— no filesystem partition reformat needed when upgrading from v1.4.1.
Full release notes: RELEASE_NOTES_1.5.0.md
Breaking changes: docs/BREAKING_CHANGES.md
Latest stable release: v1.6.1
v1.6.1 is the current stable release on main. MQTT on-change publishing is now the default, with a redesigned boiler-unsupported diagnostics panel and a set of MQTT and Web UI reliability fixes on top of v1.6.0.
Full release notes: RELEASE_NOTES_1.6.1.md Download: GitHub Releases
Previous stable release: v1.6.0
v1.6.0 delivered the MQTT and HA reliability overhaul, static IP support, bilateral OT-bus diagnostics, and mainloop performance improvements, shipped after 25 beta builds.
Full release notes: RELEASE_NOTES_1.6.0.md Download: GitHub Releases
Previous stable releases: v1.5.x
v1.5.0 was the first stable release of the 1.5.x LTS line on Arduino Core 2.7.4. v1.5.0-fix and v1.5.0-fix2 added maintenance fixes on top. Partition layout retained at eesz=4M2M — no filesystem reformat needed when upgrading from v1.4.1.
Full release notes: docs/releases/RELEASE_NOTES_1.5.0.md Maintenance tags: v1.5.0-fix, v1.5.0-fix2
What was new in v1.3.4
Version 1.3.4 fixes MQTT throttle slot suppression, adds Debug Info tooltips, renames "OTGW Connected" to "OpenTherm Active", and adds thermostat-only MQTT support. Full release notes: RELEASE_NOTES_1.3.4.md
What was new in v1.3.3
Version 1.3.3 adds PIC-less OTGW support and fixes the dashboard showing empty values for unsupported OpenTherm message IDs. Full release notes: RELEASE_NOTES_1.3.3.md
What was new in v1.3.2
Version 1.3.2 fixes the persistent file explorer failures reported after v1.3.1. Full release notes: RELEASE_NOTES_1.3.2.md
What was new in v1.3.1
Version 1.3.1 was a stability release fixing command queue reliability, CS override interference, and serial coordination issues reported after v1.3.0. Full release notes: RELEASE_NOTES_1.3.1.md
What was new in v1.3.0
Version 1.3.0 is a major feature release building on v1.2.0 with PIC settings visibility, safer upgrades, better recovery, optional admin protection, fuller PS=1 integration, and significantly lower RAM pressure. Full release notes: RELEASE_NOTES_1.3.0.md / Breaking Changes Log
Highlights
- PIC Gateway Settings Panel: All 15 PIC configuration registers (setpoint override, GPIO, LEDs, tweaks, smart power, thermostat detection, etc.) are now exposed via REST API (
/api/v2/pic/settings), MQTT, and a new "Gateway Settings" section in the Web UI. Settings are read on-demand from the PIC (one PR= every 3s, full cycle ~45s) and cached in the browser with localStorage for up to 7 days. Live values show in green, cached in amber. - Single-Click GitHub Release OTA: The update page now lists GitHub releases with Installed/Update/Rollback badges. One-click download and flash with semver-aware version comparison including pre-release tags.
- Optional Protected Admin Endpoints: Settings, maintenance, file-management, reboot, and OTA routes can now be protected with HTTP Basic Auth.
- Configurable MQTT Publish Gating: OpenTherm and
PS=1summary publishing can now be rate-limited to reduce MQTT broker load and WiFi chatter, with better status republish behavior after boot and reconnect. - Full
PS=1Summary Integration:PS=1output is now translated into the normal data pipeline, published to MQTT, and exposed to Home Assistant discovery. - Web UI Enhancements: Light/dark theme toggle, one-shot OTGW PIC commands from the monitor page, richer settings tooltips, gateway mode indicator, WebSocket connection status with tooltips, simulation badge, and improved heap/device reporting.
- Safer OTA / LittleFS Updates: Reboot verification via
/api/v2/health, browser backups ofsettings.inianddallas_labels.ini, Dallas labels auto-preserved through localStorage, hardened filesystem flashing against WiFi reconnect corruption. - Triple-Reset WiFi Recovery: Three quick hardware resets within 10 seconds clear stored WiFi credentials and reopen the captive portal without requiring a reflash.
- Non-Blocking WiFi Reconnect: The blocking 30-second reconnect loop is replaced with a state machine, preventing main-loop freezes on a heating system controller.
- Security Hardening: Centralized HTTP Basic Auth enforcement for all POST/PUT API endpoints. CORS wildcard replaced with dynamic origin validation. Webhook hostname SSRF prevention via DNS resolution. XSS fix in statistics table. Boot command and MQTT payload validation. ~450 lines of dead code removed.
- Memory and Stability: ArduinoJson removed, settings/state reorganized into structs, String class eliminated from hot paths including CSRF validation. MQTT autodiscovery memory reduced via streaming. ~1,400 bytes of stack pressure eliminated through centralized buffers. Fixed
millis()wraparound bug, f8.8 negative value encoding, and OT message parse validation. - No New Breaking Changes: For v1.2.0 users, this release adds features and hardening without introducing new MQTT topic, REST API, or settings-format breaks.
What was new in v1.2.0
Version 1.2.0 was the protocol-alignment and discovery release. It expanded Home Assistant coverage across the OpenTherm specification and tightened MQTT, REST API, and Web UI behavior. Full release notes: RELEASE_NOTES_1.2.0.md
Highlights
- Complete Home Assistant discovery expansion: 309 auto-discovery configurations across 80+ OpenTherm message IDs, covering heating, cooling, solar, DHW, ventilation, CH2, humidity, counters, and system status.
- OpenTherm v4.2 alignment: Added missing IDs
39and93-97, corrected types and units, and introduced compatibility handling for legacy IDs50-63. - MQTT / webhook / diagnostics improvements: Added optional source-separated MQTT topics, webhook support, safer MQTT auto-configuration, and richer serial/WebSocket diagnostics.
- v2-only API baseline:
/api/v0/and/api/v1/were removed in favor of/api/v2/, with related device-info key updates for raw API consumers. - Upgrade note: v1.2.0 introduced real migration items for MQTT topics, Home Assistant entities, and some raw API fields. See RELEASE_NOTES_1.2.0.md and docs/fixes/opentherm-v42-mqtt-breaking-changes.md.
What was new in v1.1.0
Version 1.1.0 builds on the stable v1.0.0 foundation with Dallas temperature sensor enhancements, a complete RESTful API v2, WebUI data persistence, and 20 bug fixes from a comprehensive codebase review. Full release notes: RELEASE_NOTES_1.1.0.md
Dallas Sensors, RESTful API v2, and 20-Bug Codebase Overhaul
v1.1.0 delivers custom labels and real-time graphs for Dallas temperature sensors, a fully RESTful API v2 with 13 new endpoints (compliance score 5.4 → 8.5/10), and resolution of 20 bugs spanning memory safety, data integrity, concurrency, and security.
- Dallas Sensor Custom Labels & Graphs — Inline label editing in the Web UI, stored in
/dallas_labels.iniwith zero backend RAM, automatic backup/restore during filesystem flash, and real-time graph visualization with 16-color palette. REST API:GET/POST /api/v2/sensors/labels. - RESTful API v2 — 13 new endpoints with consistent JSON errors, proper HTTP status codes (202 for async), CORS/OPTIONS support, RESTful resource naming (
messages/{id},commands,device/info). All frontend calls migrated to v2. See ADR-035. - 20-bug codebase review — Memory safety (OOB write, stack overflow), data integrity (MQTT hour bitmask, −127°C sensor published to MQTT), concurrency (ISR race in S0 counter), security (reflected XSS), reliability (file descriptor leak, null pointer crash, 750ms blocking sensor read), GPIO output feature fix, flash wear reduction (20 writes → 1). Full details: Codebase Review.
- WebUI Data Persistence — Automatic
localStoragepersistence with debounced saves, dynamic memory management, normal/capture modes, and auto-restoration on page load. - Heap Memory Monitoring — 4-level health system (CRITICAL/WARNING/LOW/HEALTHY) with adaptive throttling and WebSocket backpressure control (ADR-030).
- Browser Debug Console (
otgwDebug) — Full diagnostic toolkit in the browser console:status(),info(),settings(),wsStatus(),logs(),api(),health(),sendCmd(),exportLogs(), and more. - PS Mode detection — Automatic detection of
PS=1; hides the OT log section, disables WebSocket streaming, suppresses time-sync commands. - MQTT auth fix — Whitespace automatically trimmed from MQTT credentials, fixing auth failures when upgrading from v0.10.x.
Notes for upgraders from v1.0.x
No breaking API or MQTT changes. A filesystem flash and hard browser refresh (Ctrl+F5) are recommended. The v0 and unversioned REST API endpoints deprecated in this release were removed in v1.2.0 (return 410 Gone).
🏁 Introduced in v1.0.0
Version 1.0.0 was a major milestone delivering improved stability, a modern user interface, and robust integration.
📝 Full release notes: RELEASE_NOTES_1.0.0.md
Highlights
- Real-Time Graphs & Statistics: Live boiler data visualization (temperatures, setpoints) with responsive graphs and a long-term statistics dashboard.
- Modern Web UI: Fully integrated Dark Mode, responsive mobile design, redesigned File System Explorer, and WebSocket-based live log viewer.
- Improved Flashing: Reliable web-based firmware and filesystem flashing with health-check reboot verification. New
flash_esp.pyscript for easy updates. - MQTT Auto Discovery: Added Outside Temperature override (
outside) support; static 1350-byte MQTT buffer prevents heap fragmentation. - Binary Safety: Critical fix for Exception (2) crashes during PIC flashing (
strncmp_P→memcmp_P). - Connectivity & Security: Rewritten Wi-Fi logic with improved watchdog handling; CSRF protection, masked password fields, input sanitization.
- Gateway Mode: Reliable detection using
PR=Mcommand. NewNTPsendtimesetting.
Features at a glance
Home Assistant integration via MQTT
The recommended way to integrate with Home Assistant. The firmware publishes all OpenTherm data to MQTT and supports automatic discovery of entities.
- 309 auto-discovery configurations across 80+ OpenTherm message IDs -- heating, cooling, solar thermal, DHW, ventilation, CH2, humidity, operational counters, fault diagnostics.
- Climate entity with temperature override support.
- Configurable publish interval to reduce broker load while keeping data fresh.
- Source-separated MQTT topics (optional) for per-device breakdown.
- Webhook support for triggering HTTP calls on status bit changes (flame on, fault detected, etc.).
See Setting up MQTT with Home Assistant below for configuration steps.
Web interface
- Live OpenTherm message log via WebSocket (port 81), with filtering, pausing, and raw message decoding.
- Real-time graphs for boiler temperatures, setpoints, water pressure, and modulation level (ECharts).
- Dallas temperature sensors shown in graphs with custom labels and a 16-color palette.
- Dark/light theme toggle with per-browser persistence.
- PIC gateway settings panel -- all 15 PIC configuration registers readable from the browser.
- File system explorer with upload, download, and delete.
- Firmware and filesystem OTA updates with health-check verification after reboot.
REST API
A documented, versioned REST API for automation and integration beyond MQTT.
- All endpoints under
/api/v2/with consistent JSON responses and proper HTTP status codes. - OpenTherm data queries by message ID or label.
- Command submission, settings management, sensor label CRUD, PIC settings readout.
- CORS support for browser-based tools.
- REST API reference -- full endpoint documentation with examples for Home Assistant, Python, and JavaScript.
- OpenAPI 3.0 specification -- machine-readable spec for Swagger UI, Postman, or code generation.
MQTT reference
Full MQTT topic documentation including namespace conventions, published topics, command topics, and Home Assistant discovery details.
Ser2net / OTmonitor
- TCP serial socket on port 25238 for OTmonitor and other tools that speak the OTGW serial protocol.
- Command queue coordination: the firmware detects ser2net traffic and pauses its own queued commands to avoid PIC serial bus conflicts (ADR-059).
NTPsendtimesetting available to disable time synchronization when your ser2net workflow handles time independently.
Dallas temperature sensors
- DS18B20/DS18S20/DS1822 support with Home Assistant auto-discovery.
- Custom labels editable in the Web UI (click to rename). Stored in
/dallas_labels.iniwith zero backend RAM usage. - Automatic backup and restore of labels during filesystem flash.
- REST API:
GET/POST /api/v2/sensors/labels. See Dallas sensor API and sensor documentation.
S0 pulse counter
- kWh meter pulse counting on a configurable GPIO pin.
Stability and memory
- Extensive use of PROGMEM to keep string literals in flash, not RAM.
- ArduinoJson removed;
Stringclass eliminated from all hot paths. - Non-blocking WiFi reconnect state machine -- heating continues while WiFi recovers.
- Triple-reset WiFi recovery: three quick resets reopen the captive portal without reflashing.
- Heap monitoring with adaptive throttling and WebSocket backpressure.
- Optional HTTP Basic Auth for settings and maintenance endpoints.
Setting up MQTT with Home Assistant
Prerequisites
- Home Assistant with MQTT integration installed (Settings > Devices & Services > MQTT).
- An MQTT broker running (e.g., Mosquitto add-on in Home Assistant, or an external broker).
- Your OTGW device connected to the same network.
Step 1: Configure MQTT in the OTGW Web UI
Open http://<device-ip>/ in your browser and go to Settings.
| Setting | What to enter | Example |
|---|---|---|
| MQTT Broker | IP address or hostname of your broker | 192.168.1.100 |
| MQTT Port | Broker port (usually 1883) | 1883 |
| MQTT User | Broker username (if authentication is enabled) | mqttuser |
| MQTT Password | Broker password | •••••• |
| MQTT Top Topic | Prefix for all topics published by the gateway | OTGW |
| MQTT Unique ID | Unique identifier for this device | otgw |
| HA Discovery | Enable Home Assistant MQTT auto-discovery | Checked |
Click Save and the device will connect to your broker. The status bar at the bottom of the Web UI shows MQTT connection state.
Step 2: Verify in Home Assistant
After saving, Home Assistant should discover the OTGW device within a few seconds:
- Go to Settings > Devices & Services > MQTT.
- Look for a new device named after your OTGW.
- Click it to see all discovered entities -- heating status, temperatures, setpoints, modulation, flame, DHW, and more.
If your boiler supports cooling, solar thermal, ventilation, or a second heating circuit, those entities appear automatically too. No manual YAML configuration needed.
Step 3: Tune the publish interval
By default, Publish on change (Settings > MQTT) is enabled: the gateway publishes immediately when an OpenTherm value changes and republishes unchanged values every 60 seconds as a heartbeat. This keeps data fresh while avoiding the high MQTT traffic of publishing every repeated OpenTherm frame.
With Publish on change enabled the gateway will:
- Publish immediately when a value changes.
- Re-publish unchanged values once per Publish Interval as a heartbeat (so Home Assistant does not mark sensors as unavailable).
A value of 10-60 is a good starting point. Adjust based on how responsive you need your automations to be. Unticking Publish on change restores legacy behaviour: every OpenTherm frame is published as it arrives.
When upgrading from a release that published every frame (MQTTinterval=0), the gateway migrates that setting once to 60 seconds with Publish on change enabled. Untick it afterwards if you prefer the old behaviour.
Step 4: Optional -- send commands from Home Assistant
The gateway accepts commands on its MQTT subscribe topic. The topic structure is:
<TopTopic>/set/<UniqueId>/<command>
Common commands:
| Command | Description | Example payload |
|---|---|---|
setpoint |
Temporary temperature override (TT) | 21.5 |
constant |
Constant temperature override (TC) | 22.0 |
outside |
Override outside temperature (OT) | 15.5 |
hotwater |
DHW control: 0=off, 1=on, P=push, A=auto |
1 |
maxchsetpt |
Max CH water setpoint (SH) | 60 |
maxdhwsetpt |
Max DHW setpoint (SW) | 55 |
Example automation -- sync outside temperature from another sensor:
automation:
- alias: "Sync Outside Temperature to OTGW"
trigger:
- platform: state
entity_id: sensor.outdoor_temperature
action:
- service: mqtt.publish
data:
topic: "OTGW/set/otgw/outside"
payload: "{{ states('sensor.outdoor_temperature') }}"
For more examples: Outside Temperature Override | Hot Water Control
Alternative: OpenTherm Gateway integration (no MQTT)
If you prefer not to use MQTT, Home Assistant has a built-in OpenTherm Gateway integration that connects directly via the TCP serial socket:
socket://<device-ip>:25238
Use port 25238, not 23. Port 23 is the telnet debug console.
This integration provides basic thermostat control but does not expose the full range of OpenTherm data that MQTT auto-discovery covers.
Quick start
- Flash the firmware to your ESP8266.
- Recommended: Use the included script:
python3 flash_esp.py(downloads and flashes the latest release). python3 flash_esp.py --buildto build from source instead.- See FLASH_GUIDE.md for detailed instructions.
- Recommended: Use the included script:
- Connect to WiFi: The device starts an AP named
<hostname>-<mac>. Connect and configure your WiFi credentials. - Open the Web UI at
http://<device-ip>/and configure MQTT (see above). - Check Home Assistant for auto-discovered entities.
Hardware support
Starting with hardware version 2.3, the included ESP8266 devkit changed from NodeMCU to a Wemos D1 mini. Both are supported.
| NodoShop OTGW version | ESP8266 devkit |
|---|---|
| 1.x--2.0 | NodeMCU ESP8266 devkit |
| 2.3--2.x | Wemos D1 mini ESP8266 devkit |
For NodoShop boards in the Wemos D1 mini family, the firmware assumes the standard ESP8266 UART0 pins (TX/GPIO1, RX/GPIO3) for PIC communication plus D5/GPIO14 for PIC reset. A Wemos D1 mini Pro uses the same D1 mini-family footprint and pin mapping, so there is no separate board profile or pin-remap option in the firmware. If a Mini Pro still reports picavailable=false, the next step is a boot-time serial capture and hardware continuity/orientation check rather than a firmware pin-definition change.
Connectivity summary
| Port | Protocol | Purpose |
|---|---|---|
| 80 | HTTP | Web UI and REST API |
| 23 | Telnet | Debug logging |
| 25238 | TCP | OTGW serial interface (OTmonitor, HA OpenTherm integration) |
| -- | MQTT | Home automation integration (recommended) |
The firmware also exposes a Wi-Fi configuration portal (AP mode) when it cannot connect to a saved network.
Security note
The Web UI and APIs are designed for use on a trusted local network. Do not expose the device directly to the internet; use a VPN for remote access. A reverse proxy can help with HTTP UI/API access, but WebSocket features assume plain HTTP/WS and may not work through an HTTPS proxy.
Protected endpoints (optional)
Set an endpoint password in Settings (field: httppasswd) to require HTTP Basic Auth for:
- Settings (reading and changing device configuration)
- File management (upload/delete)
- Reboot and wireless reset
- OTA firmware updates
- Webhook test
Read-only monitoring (sensor values, device status, WebSocket connection) stays open.
Documentation
| Topic | Link |
|---|---|
| Wiki (recommended starting point) | https://github.com/rvdbreemen/OTGW-firmware/wiki |
| REST API reference | docs/api/README.md |
| OpenAPI specification | docs/api/openapi.yaml |
| MQTT topic reference | docs/api/MQTT.md |
| Dallas sensor labels API | docs/api/DALLAS_SENSOR_LABELS_API.md |
| Webhook documentation | docs/features/webhook.md |
| Flash guide | docs/guides/FLASH_GUIDE.md |
| Local build guide | docs/guides/BUILD.md |
| Code quality checker | docs/process/EVALUATION.md |
| Architecture Decision Records | docs/adr/README.md |
| WebSocket architecture | docs/api/WEBSOCKET_FLOW.md |
| Upgrading from 0.9.x / 0.10.y | docs/archive/upgrade-from-0.x.md |
| Release notes index (current + archive) | docs/releases/README.md |
| Documentation link policy | docs/process/DOCUMENTATION_LINKS_POLICY.md |
Important warnings
- Do not flash OTGW PIC firmware over Wi-Fi using OTmonitor. You can brick the PIC. Use the built-in PIC firmware upgrade feature instead.
- Dallas GPIO default changed in v1.0.0: Default pin moved from GPIO 13 (D7) to GPIO 10 (SD3). If upgrading from an older version, verify your wiring or change the setting back to 13.
- REST API v0/v1 removed in v1.2.0: Only
/api/v2/remains. See the REST API reference. - MQTT topic spelling corrections in v1.2.0: A few typos were fixed (
eletric_production->electric_production, etc.). Delete orphaned HA entities and let discovery recreate them. See breaking changes details.
History and scope
The OpenTherm Gateway itself (hardware + PIC firmware + OTmonitor tooling) originates from Schelte Bron's OTGW project. This firmware builds on that ecosystem by running on the ESP8266 inside the NodoShop OTGW to expose OTGW data and controls over the network.
This project is primarily designed for the NodoShop OTGW hardware with an ESP8266 (NodeMCU / Wemos D1 mini). If you have a different OTGW build, it may work, but NodoShop OTGW compatibility is the main target.
Release history
Release notes for all versions are in docs/releases/. Prebuilt firmware binaries are on the GitHub releases page.
For historical versions (v1.3.x and older), links intentionally point to docs/releases/archive/ because those notes are archived.
Version history (click to expand)
| Version | Highlights |
|---|---|
| 1.5.x | Stable LTS line on Arduino Core 2.7.4. v1.5.0 introduced reboot reliability hardening, tighter MQTT publish gating, HA discovery for stats topics, WebUI design system, and boot/loop diagnostics. 1.5.0 v1.5.0-fix2 |
| 1.4.x | Arduino Core 3.1.2 baseline, SimpleTelnet migration, MQTT HA discovery streaming rewrite (309 configs / 80+ msgIds), WiFi reconnect hardening, heap-aware discovery drip, retained-discovery self-heal, unified time-boundary dispatcher, OpenTherm v4.2 alignment. 1.4.1 |
| 1.3.x | PIC gateway settings panel, optional HTTP Basic Auth, configurable MQTT publish gating, full PS=1 integration, triple-reset WiFi recovery, non-blocking WiFi reconnect, MQTT uptime/version publishing, PIC-less OTGW support, ser2net command queue coordination. 1.3.0 1.3.1 1.3.2 1.3.3 1.3.4 1.3.5 |
| 1.2.0 | Complete HA discovery expansion (309 configs, 80+ message IDs), OpenTherm v4.2 alignment, webhook support, source-separated MQTT topics, v0/v1 API removed. Notes |
| 1.1.0 | Dallas sensor custom labels and graphs, RESTful API v2 (13 new endpoints), WebUI data persistence, browser debug console, PS mode detection, 20 bug fixes. Notes |
| 1.0.0 | Milestone release: real-time graphs, modern Web UI with dark mode, WebSocket live log, MQTT auto-discovery, interactive flashing tool, PROGMEM memory safety. Notes |
| 0.10.3 | MQTT password masking, HA discovery template improvements, status function fixes. |
| 0.10.2 | PIC firmware update fix, filesystem update with latest PIC firmware. |
| 0.10.1 | Build process improvements, VH status parsing fix, WiFi quality indicator. |
| 0.10.0 | PIC16F1847 (6.x firmware) support, DHCP NTP override, S0 pulse counter, Dallas auto-configure. |
| 0.9.x | JIT HA auto-discovery, climate entity, MQTT set commands, time setup, NTP improvements. |
| 0.8.x | MQTT topic convention change, HA device grouping, climate entity, PIC firmware integration, Dallas sensors, command queue. |
| 0.7.x | LittleFS migration, ser2net on port 25238, ventilation/heat recovery message IDs, PIC reset on boot. |
| 0.6.x | Standalone Web UI, OTA support. |
| 0.5.x | REST API v1, settings UI. |
| 0.4.x | Ser2net, REST API v0. |
| 0.2--0.3 | MQTT integration, serial stream. |
| 0.0.1 | Initial OT protocol parsing. |
Community and support
- Discord: https://discord.gg/zjW3ju7vGQ
- Issues / bug reports: https://github.com/rvdbreemen/OTGW-firmware/issues
Credits
Shoutout to early adopters helping me out testing and discussing the firmware in development. For pushing features, testing and living on the edge.
Reaching version 1.0.0 wouldn't have been possible without the community. So shoutout to the following people for the collaboration on development:
- @hvxl for all his work on the OTGW hardware, PIC firmware and ESP coding.
- @sjorsjuhmaniac for improving the MQTT naming convention and HA integration, adding climate entity and otgw device
- @vampywiz17 early adopter and tester
- @Stemplar reporting issues realy on
- @proditaki for creating Domiticz plugin for OTGW-firmware
- @tjfsteele for endless hours of testing
- @DaveDavenport for fixing all known and unknown issues with the codebase, it's stable with you
- @DutchessNicole for fixing the Web UI over time
- @RobR for his work in the s0 counter implementation
- @GeorgeZ83 for improving Home Assistant MQTT integration and climate entity support
And for all those people that keep reporting issue, pushing for more and helping other in the community all the time.
A big thank should goto Schelte Bron @hvxl for amazing work on the OpenTherm Gateway project and for providing access to the upgrade routines of the PIC. Enabling this custom firmware a reliable way to upgrade you PIC firmware. If you want to thank Schelte Bron for his work on the OpenTherm Gateway project, just head over to his homepage and donate to him: https://otgw.tclcode.com/
Buy me a coffee
In case you want to buy me a coffee, head over here:
License
MIT. See LICENSE.