Flash OTGW Firmware on ESP32-S3 with Localtonet

Revision pin, evidence boundary, and tutorial scope

The ESP32-S3 information in this guide is tied to the OTGW-firmware repository and its dev branch as reviewed on 20 August 2026. At that review point, the repository identified itself as OTGW-firmware v2.0.0 and described the code as unreleased, unsupported alpha software intended for alpha testers. A branch is a moving reference rather than an immutable release. Before building anything, record the exact commit shown by GitHub or by your local Git checkout so that your build, issue report, and any later recovery attempt refer to the same source.

The repository evidence supplied for this revision establishes the supported processor family, board arrangement, PlatformIO environment name, and build command. It also establishes that a root-level flash_esp.py file exists. It does not provide the script's current contents, supported Python version, Python package requirements, serial-port prompts, binary-selection rules, erase behavior, bootloader sequence, success transcript, post-write restart sequence, or rollback process. It likewise does not document an ESP32-S3 upload command in the extracted README content.

This narrower scope is intentional. It gives you a reproducible way to identify the correct project line, reject an incompatible ESP8266 release, inspect the two installation mechanisms separately, establish a local verification checklist, and configure Localtonet after the gateway works. It does not turn undocumented behavior into instructions.

Understand the firmware and remote-access architecture

An OpenTherm Gateway sits between a compatible thermostat and boiler and monitors or influences their OpenTherm communication. In the supported v2.0.0 arrangement described by the project, the existing PIC co-processor continues to handle the traditional OTGW side while a LOLIN S3 Mini runs the network-facing ESP32-S3 firmware.

The firmware lists a browser interface, REST API v2, MQTT integration with Home Assistant discovery, a TCP serial bridge on port 25238, a Telnet debug log on port 23, webhook callbacks, over-the-air firmware and filesystem updates, graphs, settings, and live OpenTherm logging. This guide considers only the HTTP service. It does not instruct you to publish the serial bridge, Telnet service, MQTT broker connection, or any direct OpenTherm control protocol.

Remote HTTP access uses three separate components:

Confirm the exact hardware before replacing a module

The project distinguishes several hardware generations. Firmware v1.x ran on ESP8266 modules. NodoShop OTGW versions 1.x through 2.0 used a NodeMCU ESP8266, while version 2.3 and later used a Wemos D1 mini ESP8266. The reviewed v2.0.0 migration description specifically calls the LOLIN S3 Mini a replacement for the old Wemos D1 mini.

That wording does not establish a universal drop-in conversion for the earlier NodeMCU-based versions. If your OTGW is version 1.x through 2.0, do not assume that a LOLIN S3 Mini fits the socket, orientation, electrical connections, or enclosure used by the NodeMCU module. Obtain board-specific confirmation before purchasing, inserting, or powering the ESP32-S3 module.

For version 2.3 and later Wemos-based boards, the project describes the LOLIN S3 Mini as the migration replacement while retaining the same OTGW board and PIC co-processor. Even then, inspect the repository hardware support information and ESP8266 migration guidance for the exact revision you plan to use. Do not infer module orientation or boot controls from the fact that two modules have similar form factors.

Also plan for heating-system continuity. Module replacement, erasure, failed startup, or a mismatched build can make the gateway unavailable. Before changing the hardware, establish how your thermostat and boiler behave when the OTGW or network module is offline. That behavior depends on the physical installation and is not controlled by Localtonet.

Acquire and pin the OTGW-firmware source

Start at the primary OTGW-firmware repository. The reviewed project uses the dev branch for the 2.0.0 alpha line. Do not select the latest stable release merely because GitHub gives it greater visual prominence, since v1.7.4 targets ESP8266.

The repository exposes the relevant files directly: the dev README, the current PlatformIO configuration, and the current Python flashing script. Inspect these files at the same recorded commit. If GitHub shows that one changed after the others were reviewed, re-evaluate the procedure rather than assuming compatibility.

Prepare the workstation without inventing dependencies

The PlatformIO route requires a working PlatformIO installation. The Python route requires Python 3 because the previously published invocation uses python3. The evidence supplied for this article does not define a minimum PlatformIO version, supported Python minor versions, a requirements file to install, USB driver packages, or supported host operating systems.

Before connecting to a heating controller, verify that the chosen revision itself documents those requirements. If flash_esp.py imports packages that are not part of Python's standard library, install only the dependencies specified by that revision. Do not respond to a missing import by installing similarly named packages from an unverified source.

• Use a USB cable that supports data, not a charge-only cable.
• Confirm that the operating system detects a new USB or serial device when the board is attached.
• Record the detected device name before running any tool.
• Disconnect unrelated serial devices to reduce the risk of selecting the wrong target.
• Do not assume that automatic reset or bootloader entry works until the exact board instructions confirm it.
• Do not power the installed gateway simultaneously from conflicting sources.

Keep the Python and PlatformIO installation paths separate

Earlier versions of this article combined the Python script and PlatformIO into one apparent six-step procedure. That was misleading because they are alternative paths, and the available primary evidence does not establish equivalent behavior. Review the path you intend to use independently.

Python script path

The repository contains flash_esp.py, but file presence alone does not prove that the script downloads a release, selects the correct artifact, prompts for a serial port, erases flash, writes every required partition, or restarts the device. Those behaviors must be verified from the script at your pinned commit.

A previously cited invocation was:

python3 flash_esp.py

Do not treat that single command as sufficient authorization to run the current script. Confirm its current interface and dependencies from the pinned file first. In particular, this guide does not describe it as a release installer because the supplied primary evidence does not verify that characterization.

PlatformIO source-build path

The reviewed README explicitly documents the PlatformIO environment name and build command:

pio run -e esp32

The environment is named esp32 even though the supported module uses an ESP32-S3. Run the command from the root of the matching source checkout, where its platformio.ini is present. A successful build establishes that PlatformIO compiled the selected environment. It does not establish that any bytes were written to the board.

After any documented write completes, follow that revision's restart procedure. Do not disconnect during a write, and do not assume a successful tool exit proves that the firmware boots, communicates with the PIC, joins Wi-Fi, starts HTTP, or observes the OpenTherm bus. Each of those is a separate checkpoint.

Verify startup and HTTP locally before considering a tunnel

The reviewed dev README lists Wi-Fi, a web interface, REST API v2, AP fallback mode in beta, and triple-reset Wi-Fi credential recovery. It does not provide the exact first-boot access-point name, captive-portal address, credentials, field labels, LED sequence, or timing in the supplied extract. For that reason, this guide does not present a speculative captive-portal walkthrough.

Likewise, the supplied evidence does not establish otgw.local as a guaranteed hostname for this alpha revision. Discover the gateway through the router or DHCP server and use its assigned LAN IP address unless the exact revision explicitly documents and successfully advertises a local hostname.

Local verification sequence

1. Follow the pinned revision's documented restart and Wi-Fi provisioning procedure.
2. Confirm that the device appears in the intended network's DHCP or client list.
3. Record the assigned LAN IP address.
4. From a computer on the same network, open the documented HTTP address at that IP.
5. Confirm that the web interface loads consistently after a refresh.
6. Inspect the live OT log or status views and confirm that the values are plausible for the installation.
7. Use only a REST API v2 route documented by the pinned revision and confirm its method, response, and authentication behavior locally.
8. Repeat the HTTP test from the separate computer that will run our Localtonet client.

If the HTTP service uses the standard HTTP port, a local test has the following form:

http://<otgw-lan-ip>/

If the selected revision or configuration uses another port, include that actual port and use the same value later as the Localtonet target. Do not infer a port from another firmware generation.

Consider assigning a predictable address through a DHCP reservation in your normal network administration system. Localtonet cannot reach an old IP address after the OTGW receives a different lease. The reservation procedure depends on your router or DHCP server.

Configure Localtonet only after local verification

With Localtonet, the client on your LAN establishes an outbound connection to one of our relay servers. The resulting HTTP tunnel provides a public URL without inbound router port forwarding, inbound firewall changes, VPN setup, or a public IP address. The tunnel is available only while the selected client is connected and the tunnel is running.

Before creating it, complete the route-by-route security review in the next section. If status pages, APIs, streams, settings, maintenance actions, or write-capable routes remain publicly usable without suitable authentication, keep the OTGW LAN-only rather than proceeding.

See our HTTP tunnel documentation for the current dashboard workflow. HTTP tunnels can use a generated subdomain, a selected subdomain where supported, or a custom domain. Check the current documentation before configuring custom-domain DNS.

Decide whether the OTGW is safe to make public

A heating controller is a sensitive administrative service. Its pages may disclose temperatures, schedules, equipment state, network configuration, and operational history. An API or settings route may also allow changes with physical consequences. A public URL changes the threat model even when it is intended for short-term maintenance.

The reviewed OTGW project description states that HTTP Basic Authentication is optional for settings and maintenance endpoints. That is a limited claim. It does not establish that the main status interface, REST API, live log, real-time streams, every write route, or every static resource requires authentication.

Minimum pre-exposure review

• Enable the firmware's supported authentication for settings and maintenance endpoints.
• Use a strong, unique password that is not reused elsewhere.
• Open the root page in a private browser session and record whether it requires credentials.
• Test each API route you intend to use without credentials, then with invalid and valid credentials.
• Check live logs, graphs, event streams, downloads, upload functions, settings, maintenance, OTA, and restart actions separately.
• Verify both read and write methods. A protected settings page does not prove that its underlying API is protected.
• Do not publish Telnet on port 23 or the TCP serial bridge on port 25238 as part of this HTTP workflow.
• Stop the tunnel immediately if a route exposes sensitive data or accepts an unauthorized change.

The public browser-facing connection uses the tunnel's HTTPS address. The local target described here remains the OTGW's HTTP service on the LAN. Keep the helper host and OTGW on a trusted or appropriately segmented network. Do not claim that the local HTTP hop becomes encrypted merely because the public address uses HTTPS.

Define recovery and rollback before writing firmware

The supplied project evidence does not establish a complete ESP32-S3 rollback procedure. It does not say whether settings survive every flashing method, which partitions must be preserved, whether the Python script performs an erase, how to recover a board that no longer enumerates normally, or how to return safely from v2.0.0 to an older module.

Therefore, a responsible installation plan needs explicit answers before the first write:

• What exact commit or artifact is being installed?
• Which board revision and module are present?
• How does that board enter its ROM bootloader?
• Which serial device belongs to the board?
• Which images and partition addresses will be written?
• What output proves that every required write completed?
• How is the board restarted after writing?
• How are Wi-Fi and application settings backed up or recreated?
• How is a failed board returned to a flashable state?
• How will heating continue while the gateway is unavailable?

Network recovery should also be planned separately. The dev README mentions triple-reset Wi-Fi credential recovery and beta AP fallback, but the exact trigger timing and resulting configuration are not established here. Preserve local network access to the Localtonet host so that you can stop the tunnel even if the OTGW becomes unresponsive.

Troubleshoot hardware, firmware, LAN, and tunnel layers separately

Work from the device outward. A public tunnel cannot fix a wrong module, failed write, missing Wi-Fi configuration, broken PIC communication, or unreachable LAN service.

When local HTTP works but public HTTP does not

Start on the helper computer. If it cannot open the OTGW's LAN URL, our relay cannot forward to it. If that local request succeeds, confirm the device token selection, client connection, relay selection, exact target IP and port, and tunnel running state. Saving the configuration is not the same as starting it.

When authentication differs between routes

Treat each route as a separate security finding. A login prompt on the settings page does not prove that REST, live streams, OTA handlers, or write operations are protected. Stop the tunnel while investigating. If comprehensive authorization cannot be established, keep the interface private.

When the OTGW address changes

Update the target or create a DHCP reservation through your router. Local hostname discovery can vary between computers, containers, and VLANs, so a predictable LAN IP is generally easier to validate from the Localtonet host.

Frequently asked questions