ESP Relay

Simple API for chinese ESP12F relay modules. Written in micropython, depends on tinyweb.

Supported hardware

Tested with ESP12F_Relay_X1 and ESP12F_Relay_X4 modules, but can be used with any others (just setup proper relay pins in config).

Installation

Preparations

• Download pre-build micropython firmware with tinyweb library from here.

  For ESP12F you need ESP8266 version.

• I use esptool for flashing firmware and ampy for uploading micropython files. So, install them if needed:

  pip install --user adafruit-ampy esptool

• Connect RX, TX and GND pins to your favorite USB-UART converter. You can also get 5V from usb, either use an external power supply.

Flashing firmware

• Short IO0 and GND pins on the board and reboot it.
• Erase old firmware and upload new using esptool:

  esptool.py --port /dev/ttyACM0 erase_flash
  esptool.py --port /dev/ttyACM0 --baud 460800 write_flash --flash_size=detect 0 firmware_esp8266-v1.3.5.bin

  Don't forget to change port and filename to yours.

• Remove jumper between IO0 and GND pins

Installing app files

• Upload files using ampy:

  ampy -p /dev/ttyACM0 put boot.py
  ampy -p /dev/ttyACM0 put main.py
  ampy -p /dev/ttyACM0 put config.json

  Don't forget to change port with yours.

  File config.json is optional to upload. You can change all the settings later via the API, but it is more convenient to load them in a file. You can find in repo examples for X1 and X4 relays.

• Installation is complete. Now you can reboot the board and watch the startup process on UART console via minicom or picocom.

Configuration

WiFi setup

By default, ESP will start in Access Point mode if no network is configured, or if it fails to connect to any of the configured networks.

The default SSID is ESP Relay xxx, where xxx is the default password (as well as the ESP's MAC address). The default IP address is 10.0.0.10/24.

After connecting to the ESP's AP, you can add new networks via API:

curl -s -X POST 10.0.0.10/api/config/nets -d "ssid=my_network" -d "password=my_secret"

You can also add networks at the stage of uploading config.json file:

    "saved_nets": {
        "my_network": "my_secret",
        "my_another_network": "secret_password"
    },

As the networks are configured, you can reboot the board using RST button, or just via API:

curl -s -X POST 10.0.0.10/api/system/reboot

During startup, ESP will scan for networks and connect to the first available network from the list. ESP will get an IP address via DHCP, you can find it in UART console.

For easy management it would be nice to set static lease for ESP in your DHCP server config.

Relay pins

On the board, the relay control pins are located near the ESP pins, which allows you to connect them with jumpers.

On the ESP12F_Relay_X4 model, RY1 is near IO16, but during ESP initialization, this pin is always HIGH. Therefore, the relay will be switched on briefly each time at boot. To prevent it, I use IO4 pin for RY1 in my configuration, just connected them with a short wire.

On the ESP12F_Relay_X1 model, the relay pin is connected to IO5 by default, so you do not need to set any jumpers.

You can add relay pins via API:

curl -s -X POST 10.0.0.10/api/config/relays -d "name=1" -d "pin=5"

or via config.json:

    "relay_pins": {
        "1": {
            "pin": 5,
            "state": 0
        }
    },

Board led

In addition to relay status leds, there are another two. One is located directly on ESP, the other on the board. They are used to indicate startup status during the boot:

• Immediately after switching on, the ESP led lights up.
• After loading the config, the board led lights up.
• After connecting to a WiFi network, the ESP led goes out.
• After starting the API server, the board led goes out.

On the ESP12F_Relay_X1 model, board led is connected to IO16 pin.

On the ESP12F_Relay_X4 model, board led is connected to IO5 pin.

You can configure the board led pin via API:

curl -s -X POST 10.0.0.10/api/config/led -d "pin=16"

or in config.json:

    "custom_led_pin": 16,

API endpoints

Endpoint	Methods
/api/relay	GET
/api/relay/:name	GET, PUT
/api/config/nets	GET, POST, PUT, DELETE
/api/config/relays	POST, PUT, DELETE
/api/config/led	POST
/api/system/reboot	POST

GET /api/relay

Get list of configured relays with names and statuses

Example request:

curl -s -X GET 10.0.0.10/api/relay

Example response:

{
  "1": {
    "pin": 4,
    "state": 1
  },
  "4": {
    "pin": 13,
    "state": 0
  },
  "3": {
    "pin": 12,
    "state": 0
  },
  "2": {
    "pin": 14,
    "state": 0
  }
}

↑

GET /api/relay/:name

Get status of the relay with name :name.

Example request:

curl -s -X GET 10.0.0.10/api/relay/1

Example response:

{
  "pin": 4,
  "state": 1
}

↑

PUT /api/relay/:name

Change status of the relay with name :name.

Request data required:

Attribute	Type	Description
state	int	0 or 1

Example request:

curl -s -X PUT -d "state=0" 10.0.0.10/api/relay/1

Example response:

{
  "message": "Relay [1] state changed to [0]"
}

↑

GET /api/config/nets

Get list of saved networks

Example request:

curl -s -X GET 10.0.0.10/api/config/nets

Example response:

{
  "saved_nets": [
    "Example SSID 1",
    "Example SSID 2"
  ]
}

↑

POST /api/config/nets

Add new wireless network

Request data required:

Attribute	Type	Description
ssid	str	SSID
password	str	Password

Example request:

curl -s -X POST 10.0.0.10/api/config/nets -d "ssid=Test Net" -d "password=supersecret"

Example response:

{
  "message": "SSID [Test Net] added."
}

↑

PUT /api/config/nets

Change password of existing network

Request data required:

Attribute	Type	Description
ssid	str	SSID
password	str	New password

Example request:

curl -s -X POST 10.0.0.10/api/config/nets -d "ssid=Test Net" -d "password=newsupersecret"

Example response:

{
  "message": "Password for [Test Net] changed."
}

↑

DELETE /api/config/nets

Remove existing network

Request data required:

Attribute	Type	Description
ssid	str	SSID

Example request:

curl -s -X DELETE 10.0.0.10/api/config/nets -d "ssid=Test Net"

Example response:

{
  "message": "SSID [Test Net] removed."
}

↑

POST /api/config/relays

Add new relay pin

Request data required:

Attribute	Type	Description
name	str	Relay name
pin	int	ESP pin

Example request:

curl -s -X POST 10.0.0.10/api/config/relays -d "name=5" -d "pin=15"

Example response:

{
  "message": "Added relay [5] pin [15]"
}

↑

PUT /api/config/relays

Change existing relay pin

Request data required:

Attribute	Type	Description
name	str	Relay name
pin	int	New ESP pin

Example request:

curl -s -X PUT 10.0.0.10/api/config/relays -d "name=5" -d "pin=16"

Example response:

{
  "message": "Relay [5] pin changed to [16]"
}

↑

DELETE /api/config/relays

Remove existing relay

Request data required:

Attribute	Type	Description
name	str	Relay name

Example request:

curl -s -X DELETE 10.0.0.10/api/config/relays -d "name=5"

Example response:

{
  "message": "Relay [5] removed."
}

↑

POST /api/config/led

Setup board led pin

Request data required:

Attribute	Type	Description
pin	int	ESP pin

Example request:

curl -s -X POST 10.0.0.10/api/config/led -d "pin=5"

Example response:

{
  "message": "Custom led pin changed to [5]"
}

↑

POST /api/system/reboot

Reboot the board

Example request:

curl -s -X POST 10.0.0.10/api/system/reboot

Example response:

{
  "message": "Reboot initiated"
}

↑

Debug mode

After connecting to a WiFi network, you have 3 seconds to press Ctrl+C in the UART console to cancel the API server starting and get into the REPL for debugging. If you press Ctrl+C after API server start, this will trigger watchdog to reboot the board.