Build a network-connected OpenTherm gateway, verify it locally, and only then enable controlled remote HTTP access
OTGW-firmware turns supported NodoShop OpenTherm Gateway hardware into a networked heating controller with a browser interface, REST API, MQTT integration, and real-time OpenTherm monitoring. This guide focuses on the supported ESP32-S3 arrangement: a traditional NodoShop OTGW with its PIC co-processor and a LOLIN S3 Mini in the module socket. We explain the current firmware maturity, the documented flashing paths, first-boot Wi-Fi configuration, local verification, and practical troubleshooting. Once the gateway works on the local network, we show how to reach its HTTP service through Localtonet from a separate computer on the same LAN.
📋 What's in this guide
Understand the OTGW remote-access architecture
An OpenTherm Gateway sits between a compatible thermostat and boiler and observes or influences their OpenTherm communication. OTGW-firmware adds network services around that gateway. On the supported ESP32-S3 configuration, the LOLIN S3 Mini runs the network-facing firmware while the existing PIC co-processor handles the OpenTherm side of the traditional NodoShop OTGW design.
The firmware provides several integration surfaces. These include a browser-based interface, a REST API, MQTT integration with Home Assistant discovery, a TCP serial bridge, a Telnet debug log, and webhook callbacks for selected OpenTherm status changes. This article uses the HTTP interface because it is the natural match for browser access and REST requests. It does not expose the serial bridge on port 25238 or the Telnet service on port 23.
Remote access involves three separate components. The OTGW device hosts the firmware and HTTP service. A second machine on the same network runs our Localtonet client and must be able to reach the OTGW device's LAN address. The Localtonet client establishes an outbound connection to one of our relay servers and links the public HTTP endpoint to the OTGW service.
http://otgw.local/ when local name resolution works.
The available project evidence does not establish that our client can run directly on OTGW-firmware or on the ESP32-S3. Use a separate Localtonet-capable computer, server, or other supported host on the same network as the gateway. That host acts as the bridge between our relay and the OTGW's LAN service.
Check the hardware and firmware release line before flashing
Confirming the exact board and firmware line is the most important preparation step. The current OTGW-firmware development documentation identifies the supported ESP32-S3 arrangement as a traditional NodoShop OTGW with the PIC co-processor and a LOLIN S3 Mini installed in the module socket. A separate direct-GPIO ESP32 OpenTherm board also exists, but it is described as a prototype rather than the supported configuration covered here.
Release naming requires particular care. Version 2.0.0 targets the ESP32-S3 and builds from the PlatformIO esp32 environment, but the available project documentation labels 2.0.0 as unreleased alpha software for alpha testers. By contrast, the published v1.7.4 release belongs to the 1.x ESP8266 line. It is not an ESP32-S3 release, even if a release page happens to label it as the latest stable release.
Version v1.7.4 is explicitly a maintenance release for the 1.x ESP8266 line. For the ESP32-S3 hardware described in this guide, use only an artifact or source revision that the OTGW-firmware project explicitly identifies as an ESP32-S3 build. At the time reflected by the available project documentation, that means working with the 2.0.0 alpha line and accepting its unsupported development status.
| Firmware or hardware line | Processor target | Status and relevance |
|---|---|---|
| OTGW-firmware 1.x, including v1.7.4 | ESP8266 | A stable maintenance line for older ESP8266 modules. It is not the image to use for this ESP32-S3 tutorial. |
| OTGW-firmware 2.0.0 development line | ESP32-S3 | Targets the LOLIN S3 Mini in the traditional OTGW with PIC, but is described by the project as unreleased alpha software. |
| Traditional NodoShop OTGW with PIC | LOLIN S3 Mini for the network firmware | The supported ESP32-S3 hardware combination documented by the project. |
| Direct-GPIO ESP32 OpenTherm board | ESP32 prototype | A prototype that operates without the PIC. It is outside the supported hardware scope of this guide. |
If you are migrating older hardware, do not treat the process as an ordinary firmware update. The 1.x line ran on ESP8266 modules, including NodeMCU ESP8266 hardware on earlier NodoShop boards and Wemos D1 mini ESP8266 hardware on later boards. The 2.0.0 development documentation describes moving to the ESP32-S3 by replacing the old Wemos D1 mini with a LOLIN S3 Mini while retaining the OTGW board and PIC co-processor.
Before applying power or replacing a module, follow the electrical and assembly guidance for your exact NodoShop board revision. The evidence available for this article does not establish board-specific insertion orientation, jumper positions, USB cable requirements, power-isolation procedures, or boot-button timing. Those details should not be guessed because an incorrect physical installation can damage the controller or leave the heating system unavailable.
Prepare the hardware, software, and network prerequisites
A successful installation starts with a clear separation between what is required for flashing, what is required for first boot, and what is required only for remote access. You can flash and verify OTGW-firmware without Localtonet. Add the tunnel only after the local service behaves correctly.
Hardware prerequisites
- A traditional NodoShop OpenTherm Gateway that retains its PIC co-processor.
- A LOLIN S3 Mini installed as the ESP32-S3 module for the current 2.0.0 development target.
- A computer that can connect to the ESP32-S3 for flashing.
- A suitable data connection between that computer and the board. A charge-only USB cable will not provide a programming connection.
- A Wi-Fi network that the gateway can join during first-boot configuration.
- For remote access, a separate machine on the OTGW network that can run our Localtonet client.
Software prerequisites
The project documents two firmware installation paths. The release-oriented path uses the repository's Python flashing script:
python3 flash_esp.py
The source-build path uses PlatformIO and its environment named esp32:
pio run -e esp32 --target upload
The environment name is esp32 even though the documented target hardware is an ESP32-S3. Do not rename the environment or substitute another build target unless the project documentation for your selected revision explicitly instructs you to do so.
The extracted project documentation does not define a supported Python version beyond invoking python3, a minimum PlatformIO version, operating-system-specific driver packages, or a universal serial-port selection procedure. Install a current Python 3 environment for the script path or PlatformIO for the source-build path, then confirm that your operating system detects the attached board. If the tooling reports a missing package, serial permission error, or unavailable port, resolve that host-side issue before attempting another write.
Information to record before starting
- The exact NodoShop board revision and currently installed module.
- The firmware branch, tag, commit, or artifact selected for flashing.
- Confirmation that the selected build explicitly targets the ESP32-S3.
- The Wi-Fi network credentials that will be entered through the first-boot portal.
- The gateway's eventual LAN IP address or resolvable
otgw.localname. - The address of the separate host that will run our Localtonet client.
Firmware installation and module replacement can make the gateway temporarily unavailable. Perform the work when interruption is acceptable, preserve any existing configuration that your current installation method allows you to save, and make sure you understand how your thermostat and boiler behave if the gateway is offline. The project evidence supplied for this guide does not establish a universal fail-safe procedure for every OTGW board and heating installation.
Flash OTGW-firmware onto the ESP32-S3
The safe workflow is to identify an ESP32-S3-compatible revision, choose one of the two documented flashing paths, complete the write, and then let the device enter its first-boot network flow. Do not mix an ESP8266 binary from the 1.x line with the ESP32-S3 process.
Confirm the supported hardware combination
Verify that you have the traditional NodoShop OTGW with its PIC co-processor and a LOLIN S3 Mini. Stop if you instead have an older ESP8266 module or the experimental direct-GPIO prototype, because those configurations require different firmware decisions.
Select an explicitly compatible ESP32-S3 revision
Review the identity of the source revision or firmware artifact before writing it. The current 2.0.0 line targets ESP32-S3 but is alpha software. The v1.7.4 stable release targets ESP8266 and must not be substituted merely because it appears as the latest published stable release.
Connect the board to the flashing computer
Use a data-capable connection and confirm that the operating system detects the device. The project evidence available here does not document one universal bootloader-entry sequence or serial device name, so follow the board-specific procedure when manual bootloader mode is required.
Use the Python flashing path when working with a compatible release artifact
From the project directory containing the supplied script, run python3 flash_esp.py. Do not add undocumented flags or assume which image it will choose. Check the script output and selected artifact so that you can confirm it is writing an ESP32-S3 build rather than a 1.x ESP8266 image.
Alternatively, build and upload the ESP32 target with PlatformIO
From a compatible source checkout, run pio run -e esp32 --target upload. This compiles the project's documented esp32 environment and uploads it to the connected board. Treat compiler errors as unresolved dependency or source-revision problems rather than changing board definitions at random.
Wait for the write to finish before restarting
Do not disconnect power while the flashing tool is writing. A successful tool exit establishes that the upload process completed, but it does not by itself prove that the firmware boots, joins Wi-Fi, communicates with the PIC, or observes the OpenTherm bus.
Choose one flashing route, not both. The Python script is intended as the release-oriented installation path, while PlatformIO is appropriate when building from the source tree. Building from source gives you a direct relationship to a particular source revision, but it also introduces compiler, dependency, and environment considerations that are absent when using a prepared image.
Flashing verifies communication between the development computer and ESP32-S3. It does not verify Wi-Fi, HTTP, the REST API, PIC communication, thermostat data, boiler data, MQTT, or remote access. Test these layers separately so that a later failure can be assigned to the correct component.
Configure Wi-Fi through the first-boot access point
On first boot without usable stored network credentials, OTGW-firmware provides an access point and captive-portal flow for network setup. Connect a phone or computer to the access point presented by the device, open the captive portal when prompted, and provide the credentials for the Wi-Fi network the OTGW should use.
The available evidence does not establish a permanent access-point name, default password, captive-portal IP address, or exact field labels. Those values can change across firmware revisions, and documenting guessed credentials would be unsafe. Use the access point and portal information shown by the firmware revision you actually flashed.
Power the flashed gateway and wait for its setup network
Allow the ESP32-S3 time to boot. On a first boot without working credentials, inspect the nearby Wi-Fi networks from a phone or computer and identify the setup access point created by the gateway.
Join the gateway access point
Connect using the information presented by the device or the documentation for the exact revision. Do not assume that credentials from an older ESP8266 release apply to the ESP32-S3 alpha line.
Open the captive portal
Use the automatic captive-portal prompt if the operating system displays one. If it does not appear, consult the firmware output or revision-specific instructions rather than guessing a management address.
Enter the destination Wi-Fi credentials
Select or enter the home or management network that the OTGW should join, provide its credentials, and submit the configuration. Keep these credentials private and avoid performing setup over an untrusted shared network.
Reconnect your administration device to the LAN
After the gateway leaves setup mode and joins the selected Wi-Fi network, reconnect your phone or computer to that same LAN. Identify the address assigned to the OTGW through your router, DHCP server, or local network-management interface.
The 2.0.0 development documentation also describes Wi-Fi resilience features, including a beta access-point fallback mode and triple-reset credential recovery. Because behavior may vary across alpha revisions, use recovery only after checking the instructions for the exact revision on the device. Repeatedly resetting a live heating controller without understanding the recovery sequence can cause avoidable downtime.
Verify the browser interface and REST API locally
Do not create a public tunnel until local HTTP access is reliable. Start from a computer on the same LAN and try the hostname-based address:
http://otgw.local/If local multicast name resolution is unavailable or unreliable, use the IP address assigned to the device:
http://<device-ip>/A URL without an explicit port uses the normal HTTP port. If your firmware revision has been configured to listen elsewhere, use the actual configured port and carry that same value into the Localtonet tunnel later.
What a successful local check establishes
- The ESP32-S3 booted far enough to start its network services.
- The gateway joined the intended Wi-Fi network.
- Your local computer can route to the OTGW device.
- The HTTP server responds and the browser interface loads.
- The LAN address and port are suitable as a future Localtonet target.
Continue beyond the first page load. The firmware's web interface includes live OpenTherm logging, real-time graphs, a settings panel, and other operational views. Confirm that the information shown is plausible for your installation. A responsive web server with no thermostat, boiler, or gateway data could indicate a separate PIC, wiring, or OpenTherm communication problem.
The firmware also provides REST API v2 with JSON responses and HTTP status codes. However, the evidence supplied for this article does not establish specific endpoint paths, methods, request bodies, or authorization requirements for every API operation. Use an API route documented by the exact firmware revision and test that route locally before testing it through Localtonet. Do not invent a path based on conventions used by unrelated IoT products.
Separate network verification from heating-bus verification
| Check | What it proves | What it does not prove |
|---|---|---|
| The device appears in the router or DHCP lease list | The OTGW joined the LAN and obtained an address | That its web server or OpenTherm communication works |
http://<device-ip>/ loads |
The local HTTP service is reachable | That every REST operation or protected setting works |
http://otgw.local/ loads |
Local hostname discovery and HTTP both work | That the hostname will resolve from a different network or relay host |
| Live OT data appears | The application is receiving meaningful gateway or bus information | That every boiler-specific message is supported |
| A documented REST route returns JSON | The selected API route is working locally | That it is safe to expose without additional access controls |
For a stable tunnel target, consider giving the OTGW a predictable LAN address through your normal network administration process, such as a DHCP reservation. The exact procedure depends on your router or DHCP server and is not controlled by either OTGW-firmware or Localtonet. If the OTGW's address changes, a tunnel configured with the old address will stop reaching it.
Expose the verified OTGW HTTP service with Localtonet
Once local access works, install our client on a separate machine that can reach the OTGW. Suitable placement matters more than physical proximity. The host must have network routing to the gateway's local IP and port. A machine on an isolated guest network, a different VLAN without an allow rule, or a network with client isolation may be unable to reach the OTGW even when both devices use the same internet connection.
With Localtonet, the client creates an outbound connection to our relay. This avoids inbound router port forwarding, a public IP requirement, VPN setup, and inbound firewall changes. The public URL remains usable only while the selected Localtonet client is connected and the tunnel is running.
Install and run our client on a LAN host
Install the Localtonet application for the host's operating system and run it on a device that can reach the OTGW's verified local HTTP address. Do not attempt to install it on the ESP32-S3. Before continuing, open the OTGW address from the Localtonet host itself to prove that routing and local firewall rules permit access.
Authenticate or select the Localtonet device
Use the device-specific authentication token associated with the host that will run the tunnel. Tokens identify client devices and must not be copied into screenshots, source repositories, API examples, or public logs. Select the corresponding connected client in our dashboard.
Select an available relay server
Choose from the server or region values currently offered in our dashboard. Availability can vary, so this guide does not hardcode a server code or claim that every region is included with every plan.
Create an HTTP tunnel to the OTGW
Configure the local target as the OTGW's verified LAN IP address and HTTP port. For example, if the local browser test uses http://<device-ip>/ without a custom port, use the corresponding standard HTTP service port. Prefer the numeric LAN address if otgw.local does not resolve reliably from the Localtonet host.
Start the tunnel and test its public address
Creating a tunnel does not automatically mean it is running. Press Start, wait for the tunnel to become available, and open the assigned public URL from a network other than the OTGW LAN. HTTP tunnels can use a generated subdomain, a selected subdomain where supported, or a custom domain, and they serve through a public HTTPS address.
Stop or delete access when it is no longer required
Stop the tunnel after temporary maintenance or testing. Delete it if the configuration is no longer needed. The public endpoint is available only while the selected client remains connected and the tunnel is running.
You can review the current workflow in our Localtonet HTTP tunnel documentation. Check the current dashboard and documentation before configuring a custom domain because DNS requirements can change and are not established in the evidence for this article.
Verify the public path in layers
- Open the OTGW's LAN address from the Localtonet host.
- Confirm that our client is connected under the intended device token.
- Confirm that the tunnel is started rather than merely saved.
- Open the assigned public URL from a separate network, such as a mobile connection.
- Load a read-only status view before attempting any configuration change.
- Test one known REST route using the same method and payload that worked locally.
- Stop the tunnel and confirm that remote access is no longer available when the maintenance session ends.
In this architecture, the OTGW service runs on a different device from our client. A target such as 127.0.0.1 would refer to the Localtonet host itself, not the ESP32-S3. Enter the gateway's reachable LAN address unless you have intentionally placed a separate reverse proxy on the Localtonet host.
Secure access to a heating controller
A heating controller is not an ordinary demonstration web page. Its interface may reveal operating state, temperatures, schedules, equipment information, and configuration controls. API access may permit changes with physical consequences. A public URL therefore changes the threat model even when it is created only for convenience.
OTGW-firmware documents optional HTTP Basic Authentication for settings and maintenance endpoints. Enable the firmware's supported authentication controls where appropriate, but do not assume that this single option protects every page, API route, stream, or integration surface. Verify the behavior of the exact firmware revision and test which routes require credentials before making the service reachable from outside the LAN.
A public tunnel address is a network location, not proof that a requester is trusted. Use authentication, strong unique credentials, least-privilege API behavior, and any applicable access restrictions. Avoid exposing administrative or write-capable API operations unless remote use is necessary and you have verified their protection.
Public HTTPS protects the browser-facing connection to the tunnel edge, while the configured local target in this workflow is the OTGW's HTTP service on the LAN. Keep the Localtonet host and OTGW on a trusted or appropriately segmented network, and do not describe that local segment as protected merely because the public endpoint uses HTTPS.
Also avoid exposing unrelated firmware services through additional raw-port tunnels without a separate security review. The existence of a TCP serial bridge and Telnet debug service does not mean they are appropriate for internet access. A protocol designed for local diagnostics may lack the authentication and request controls expected at a public boundary.
Troubleshoot flashing, local access, and tunneling separately
Troubleshooting is faster when each layer is tested independently. A public URL cannot repair a failed firmware upload, missing Wi-Fi credentials, an incorrect LAN address, or broken OpenTherm communication. Begin at the hardware and move outward.
| Symptom | Likely layer | Recommended check |
|---|---|---|
| The flashing tool cannot find a device | USB, driver, permissions, or bootloader state | Use a data-capable cable, confirm OS detection, check serial permissions, and follow the board-specific bootloader-entry procedure. |
| The image writes but the board does not boot correctly | Firmware target or hardware mismatch | Confirm that the artifact explicitly targets the ESP32-S3 and is not the v1.7.4 ESP8266 image. |
| No setup access point appears | Boot, stored credentials, or firmware state | Allow time for boot, check whether the device joined a previously configured network, and consult revision-specific recovery instructions. |
otgw.local does not resolve |
Local hostname discovery | Find the gateway's LAN address in the router or DHCP server and open http://<device-ip>/ instead. |
| The IP address does not open from any LAN computer | Wi-Fi, addressing, HTTP service, or network isolation | Confirm the lease, subnet, client-isolation settings, and whether the flashed firmware has completed boot. |
| The web interface loads but no useful OpenTherm data appears | PIC, wiring, thermostat, boiler, or bus communication | Treat this as a gateway-side issue. Check the supported hardware arrangement and physical OpenTherm installation before configuring remote access. |
| The OTGW opens from one computer but not the Localtonet host | LAN routing, VLAN rules, or host firewall | Test the OTGW URL directly on the Localtonet host and permit only the required path between that host and the gateway. |
| The tunnel exists but the public URL is unavailable | Localtonet lifecycle | Confirm that the correct client is connected, the intended relay is selected, and the tunnel has been started. |
| The tunnel is running but returns an upstream error | Local target address or port | Recheck the OTGW LAN IP and HTTP port from the Localtonet host. Do not use localhost for a service running on the ESP32-S3. |
| The web page works publicly but a REST call fails | API route, method, authentication, or payload | Repeat the identical request locally. Confirm the route against the exact firmware revision and check whether the endpoint requires authentication. |
| Remote access stops after previously working | Client availability, tunnel state, or changed OTGW address | Confirm that the Localtonet host is online, our client remains connected, the tunnel is running, and the gateway still has the configured LAN address. |
When PlatformIO compilation fails
Verify that the command is being run from the compatible project source tree and that the esp32 environment exists in its platformio.ini. Do not respond to a compilation failure by changing the environment to an ESP8266 target. Capture the first meaningful compiler or dependency error because later messages are often consequences of that initial failure.
When flashing succeeds but Wi-Fi setup does not
First determine whether the gateway is creating its setup access point or has already joined a remembered network. Check the router or DHCP server for a new client before repeatedly resetting the board. The 2.0.0 documentation mentions access-point fallback and triple-reset credential recovery, but both should be used according to the exact alpha revision rather than an assumed sequence.
When local HTTP works but public HTTP does not
Test from the Localtonet host itself. If that host cannot open the OTGW URL, the tunnel cannot forward to it. If local access succeeds, verify the selected device token, client connection, tunnel target, relay selection, and running state. Remember that saving a tunnel configuration is not the same as starting it.
When a hostname works locally but not as a tunnel target
The .local hostname depends on local name-discovery support. Resolution may work on a laptop while failing on a server, container, or restricted network segment. Use the gateway's LAN IP address as the target when name resolution is inconsistent, and keep that address stable through your normal DHCP administration.
Frequently asked questions
Can I flash OTGW-firmware v1.7.4 onto the LOLIN S3 Mini?
No. Version v1.7.4 is a maintenance release for the 1.x ESP8266 line. The ESP32-S3 target is part of the 2.0.0 development line, which the project currently describes as unreleased alpha software. Use only a source revision or artifact explicitly identified for ESP32-S3.
Which ESP32-S3 hardware does the project support?
The documented supported arrangement is a traditional NodoShop OpenTherm Gateway with its PIC co-processor and a LOLIN S3 Mini installed in the module socket. A direct-GPIO ESP32 OpenTherm board exists, but the project describes it as a prototype.
Should I use the Python script or PlatformIO?
Use python3 flash_esp.py for the project's release-oriented flashing path when you have confirmed that the selected artifact supports ESP32-S3. Use pio run -e esp32 --target upload when building and uploading from a compatible source revision. You normally choose one path rather than running both.
How do I open the OTGW web interface locally?
From a device on the same LAN, try http://otgw.local/. If local hostname discovery does not work, find the gateway's assigned IP address and open http://<device-ip>/. Verify this local address from the future Localtonet host before creating a tunnel.
Can Localtonet run directly on the ESP32-S3?
This workflow does not assume that it can. The available evidence does not establish Localtonet client support inside OTGW-firmware or on the ESP32-S3. Run our client on a separate supported host that can reach the OTGW over the local network.
Do I need router port forwarding or a public IP address?
No. Our client establishes an outbound connection to a Localtonet relay, so this workflow does not require inbound router port forwarding, inbound firewall changes, VPN setup, or a public IP address. The tunnel works only while the selected client is connected and the tunnel is running.
Should I expose the Telnet or TCP serial bridge ports too?
Not as part of this web-focused workflow. OTGW-firmware documents a TCP serial bridge on port 25238 and a Telnet debug log on port 23, but those services have different security characteristics from the browser interface. Expose only the required HTTP service unless you have separately reviewed and protected another protocol.
Does a Localtonet public URL automatically secure every REST endpoint?
No. A public URL provides connectivity and is not a replacement for application authorization. OTGW-firmware documents optional HTTP Basic Authentication for settings and maintenance endpoints, but you must verify which routes are protected in the exact revision you use. Avoid exposing write-capable operations without appropriate authentication and a clear operational need.
Why does the tunnel stop working when the helper computer is turned off?
The helper computer runs our client and provides the network path to the OTGW. If it shuts down, disconnects from the network, or stops the client, the relay can no longer reach the local service. The tunnel must also remain in its started state.
Connect your verified OTGW with Localtonet
After the ESP32-S3 firmware boots, joins Wi-Fi, and serves its interface reliably on the LAN, use a separate Localtonet-capable host to create a controlled HTTP tunnel to that verified address. Start with temporary access, protect the OTGW's administrative functions, and stop the tunnel when remote maintenance is complete.
Get Started Free →
