ESP WiFi relay project – preview

The impetus behind the project is a remotely WiFi controllable relay for reset function in a remote controlled ham station.

The information presented here applies to development v0.1.


  • support typical multi channel relay boards;
  • ESP8266 and ESP32 firmware versions;
  • WiFi credentials programmable via a captive web interface;
  • DHCP or static IP;
  • nMDNS responder;
  • flexible configuration stored as json file in on-board LittleFS file system;
  • optional authentication to secure remote access.

A variety of integrated relay boards

Above, a Yunshan relay, not recommended as RESET pin is tied high. This one was binned, quite a waste of money. It exemplifies a common problem in that the RESET line is often not available on a header pin, this one is worse in having tied RESET high and no header pin for EN.

Above, a basic relay using custom firmware in a ESP01S (note the firmware described in this project will not fit in a ESP01). Board is programmed in a separate USB adapter which can be had with automatic handling of reset and boot signals. (ESP8266, ESP32 reset – the (ugly) detail)

I might note that the 5V relay is run from the regulated 3.3V supply, and the relay specifications state the maximum pull in voltage is 3.75V. Chinese quality!

Above,  a relay module with 30A relay on board. XL7005A SM regulator on board.

Above is a 4 channel Lilygo module (note that the USB connector is NOT USB, but requires a special programming adapter – T-U2T). An MP1593 converter is used on this board.
Above, a 4 channel board with onboard 230VAC switched mode power supply. The SM regulator is a LM2596 on this board.

Above, and ESP32s 4 channel board with external antenna. Power supply is 6V in and a AMS1117-5.0 linear regulator, another AMS-1117-3.3 for the MCU module supply.

Web interface

Above is a preview of the web browser interface, it is a bit trivial for a single channel board, but it is extensible to more channels based on a config file (config.cfg) stored in the littleFS file system on the microcontroller.

  "hostname": "EspFactory01",
  "username": "user",
  "password": "somesecret",
  "relays": [
    ["Flood lights",0,0],
    ["Interior lights",3,0],
    ["Security lights",5,1],

Above is the example configuration, it specifies four relay channels on GPIO0, GPIO3, GPIO5, GPIO4, the third with initial state ON.

Differently to most such controllers around, this does a synchronised update to all relay channels on a multi channel controller (well, within microseconds, so the individual relay operate time is the main variable).

Above is the captive portal for configuration of WiFi credentials.

The code uses a RESTful interface, and so it the relays can be controlled from command line tools (eg curl)  that could send http://EspFactory01.lan/?n00=on&update= for example.

Static IP

There are some instances where the application might require static IP address (eg to eliminate the possibility of change in the IP addresses if it is mentioned in a port redirection, see below), and the above example shows how it is done. For ‘normal’ DHCP operation, leave out the entire “staticip” key.

Don’t use static IP unless you have a need.


A username and  password can be specified in the config file and if the username is not empty, it will be used for HTTP digest authentication.

The following example shows use of command line utility curl to send an update request to the relay controller.

D:\src\EspRelay>curl --digest --user user:somesecret "http://espfactory01.lan/?n02=on&n01=on&update="
<html><body><h1>ESP Relay controller (v0.1)</h1><h2>EspFactory01</h2>
<form method="get" action="/">
<input type='button' value='Check all' onClick="javascript:f=this.form;for(x=0;x<f.elements.length;x++){if (f.elements[x].type=='checkbox'){f.elements[x].checked=true;}}">
<input type='button' value='Uncheck all' onClick="javascript:f=this.form;for(x=0;x<f.elements.length;x++){if (f.elements[x].type=='checkbox'){f.elements[x].checked=false;}}">
<input type="checkbox" id="r00" name="n00"><label for="r00">Flood lights</label><br>
<input type="checkbox" id="r01" name="n01" checked><label for="r01">Interior lights</label><br>
<input type="checkbox" id="r02" name="n02" checked><label for="r02">Security lights</label><br>
<input type="checkbox" id="r03" name="n03"><label for="r03">Ventilation</label><br>
<input type="hidden" id="update" name="update" value="">
<input type="button" value="Read" onclick="location.href='/';">
<input type="submit" value="Write">

The response to the curl command is the HTML that is sent to display the page after update, it could be redirected to NUL.

Virtual server configuration with gateway

The relay controller can be accessed through a gateway using the ‘virtual server’ capability to perform port redirection.

Above is an example of port redirection.

Above, the controller is accessed from externally, in this case using an IPName linked to a DDNS service.

Programming the controller

Two files must be copied to the controller’s flash memory:

  • distributed application flash image; and
  • LittleFS file system image.

The LittleFS image is made using the mklittlefs utility, parameters for this application create a 64kB image:

mklittlefs -d 2 -c data -b 4096 -p 256 -s 0x10000 littlefs.bin

One way to program the memory is to use Espressif’s Flash Download Tool.

Above is the dialogue from upload of both files. To update only one part of the image, eg the FS after revision of a config file, just select only that component’s tick box. You may erase the whole memory, but be aware you will erase the stored WiFi credentials.

The project is a work in progress, documentation as it evolves at WiFi relay controller (ESP8266, ESP32).