Esp8266Interface

Esp8266Interface

A WiFi bridge between a dry-contact (or opto-isolated) signal and MQTT / HTTP, built around an ESP-01 module. It reports the state of an external input to an MQTT topic and/or a pair of webhook URLs, and drives a relay output in response to MQTT messages or a polled URL.

Typical use is retrofitting network connectivity onto existing wired equipment — a doorbell transformer, an alarm panel output, a gate contact — without modifying it.

The repository contains both halves of the project:

How it works

Input → network. An external signal pulls GPIO3 low, either through the on-board PC817 optocoupler (from the HV In header) or by a plain contact closure on the In3 header. A pin-change interrupt records the new level; the main loop notices the change and:

• publishes Trigger (pin low) or Reset (pin high) to the configured MQTT topic, and
• issues an HTTP GET to the configured trigger URL or reset URL.

Network → output. The firmware subscribes to a control topic. A payload of 1 or trigger drives GPIO1 high; anything else drives it low. GPIO1 gates a 2N7000 low-side switch on the Rly header, so this is intended to energise a relay coil. The new state is echoed back to the status topic as Output 1 / Output 0.

The same output can instead — or as well — be driven by polling. If a control URL is configured, the board fetches it every 2 s and looks at the reply: a body containing Trigger closes the relay, one containing Reset opens it. This suits a far end that has no MQTT broker and cannot reach in to the board, only be asked.

Hardware

Connectors

Silkscreen labels come from the BOM; the descriptions below are derived from the netlist.

The zener D1 has no value in the BOM, so the usable voltage range of each HV In tap depends on the part actually fitted. Work out the range for your source before relying on it, and treat anything on HV In as hazardous unless you know otherwise — nothing on the board isolates HV In from its own source, only from the ESP side.

ESP-01 pin usage

Two pins do double duty as the serial port, which shapes the firmware:

• Serial.begin() is called with SERIAL_TX_ONLY so GPIO3 stays usable as an input.

• GPIO1 cannot be the UART TX pin and the relay drive at the same time. The DEBUG_SERIAL switch at the top of the sketch picks one:

  DEBUG_SERIAL	Behaviour
  0 (default)	Boot messages print, then setup() calls Serial.end() and claims GPIO1 as an output. Logging stops; the relay works
  1	Serial logging stays on for the whole run; the relay output does nothing

  Use DBG_PRINT() / DBG_PRINTLN() for any log line added after boot — plain Serial calls past the end of setup() go to a closed port in the default build.

• GPIO1 toggles as TX during boot. C1 (33 µF) on the MOSFET gate with R4 gives roughly a 1.5 s time constant, which stops the relay chattering while the module starts up — at the cost of the output switching slowly.

Building and flashing

The sketch targets the Arduino core for ESP8266 and needs these libraries:

• WiFiManager (tzapu)
• ArduinoJson v6 — the sketch uses DynamicJsonDocument
• PubSubClient
• LittleFS, ESP8266HTTPClient, WiFiClientSecure — all part of the ESP8266 core

Build with the Arduino IDE, arduino-cli, or the supplied Visual Studio / Visual Micro solution. Choose a flash layout that includes a LittleFS partition — the configuration is stored in /config.json and there is nowhere to save settings without it.

The board has no USB interface and no auto-reset circuit. To flash, use an external 3.3 V USB-to-serial adapter on the ESP-01's TX/RX/GND, hold GPIO0 low, and pulse reset. Doing this with the module out of the socket avoids back-feeding the Rly and HV In circuitry through GPIO1 and GPIO3.

Configuration

At boot the board tries the WiFi credentials WiFiManager has stored, giving up after 20 s. Failing to connect is not fatal — it keeps running while the ESP8266 keeps retrying WiFi in the background — and it deliberately does not open the config portal on its own, so a router outage cannot leave an access point running unattended in someone's wall. If WiFi stays down for 5 minutes the board reboots (see Failure handling).

The portal is opened on demand instead. Press the button on J3 and the board comes up as an access point named ESP with the password 1234567890, which is also how you configure it on first boot, when nothing is stored yet. The portal offers the standard WiFi and info pages plus a param page with these fields:

Settings are written to /config.json in LittleFS and reloaded at boot. The portal timeout is 300 s and runs non-blocking, so the rest of the loop keeps running while it is open. Saving MQTT settings takes effect immediately: the client is re-pointed at the new broker and any live session is dropped, so the next reconnect picks up the new server, port, credentials and control topic without a restart.

Messages

Payload matching is case-insensitive. An HTTP request counts as successful if the server answers with any 2xx status; the response body is only read for the control URL.

Control URL

A control URL is polled every 2 s and the reply decides where the output sits:

The match is case-insensitive and anywhere in the body, so a page carrying other markup around the word still works. Only Output 1 / Output 0 transitions are published to the status topic — a poll that finds the same state as last time is silent, so a 2 s poll does not flood the broker.

Nothing about the poll reboots the board: a control URL that stops answering leaves the relay where it was rather than dropping it, and the next poll tries again. The request timeout is 1.5 s, under the 2 s interval, so an unreachable server cannot stall the loop for longer than one period, and the interval is measured from the end of each request rather than the start. The poll runs on the first pass through the loop, so a reboot picks the output back up immediately instead of waiting, and is held off entirely while the config portal is open, so a bad URL can still be corrected.

Note that the request is plain HTTP over WiFiClient — an https:// control URL will not work, and the reply is trusted as-is.

MQTT runs over WiFiClientSecure, but setInsecure() is called, so the server certificate is not validated. Credentials are stored in plaintext in the filesystem. Treat this as suitable for a trusted LAN, not the open internet.

Failure handling

The input is read at boot, so its state is sent even if it never changes: the matching URL on the first pass through the loop, and the MQTT status as soon as the broker connects.

• URL request fails (no WiFi, no connection, or a non-2xx reply): the next attempt is due 30 s later instead of 10 minutes, and when it comes due the board reboots instead. After the reboot it reads the input again and makes a fresh attempt.
• WiFi down for 5 minutes: the board reboots. The timer counts from power-up if WiFi never connects, so a board with no stored credentials reboots every 5 minutes until the portal is used.
• MQTT disconnected: reconnects every 5 s, but only while WiFi is up. MQTT failures never cause a reboot.

Neither reboot happens while the config portal is open, and the 5-minute WiFi timer starts again when the portal closes. A reboot turns the output off until a control message arrives; a retained control message restores it as soon as MQTT reconnects, and a control URL restores it on the first poll.

On the ESP8266 the first software restart after a serial upload can hang in the bootloader, so power-cycle the board once after flashing.

Notes

The sketch compiles clean — no warnings — against ESP8266 core 3.1.2 with --warnings all, in both DEBUG_SERIAL configurations.

A few behaviours are deliberate rather than oversights:

• The config portal opens on the button's falling edge, not while it is held, and not on top of a portal that is already running. It never opens by itself on a failed connection.
• MQTT connection attempts are spaced MQTT_RECONNECT_INTERVAL (5 s) apart and skipped while WiFi is down, so they do not stall the loop. Saving settings in the portal resets that, so a new broker is tried on the next pass.
• publishMessage() honours its retained argument; every call site passes true, so every status message is retained.
• Both output paths go through SetOutput(), so they share one idea of where the output is. An MQTT command is acknowledged on the status topic whether or not it changed anything; a control URL poll only publishes when the level actually moves.
• If both a control topic and a control URL are configured, they fight: whichever spoke last wins, and the URL speaks every 2 s. Configure one or the other.

License

GPL-3.0 — see LICENSE.