Table of Contents

ChangeLog

28th of April 2025

  • added GPIO pin interrupt reporting by allowing the user to specify the interrupt pin and then sending MQTT payloads depending on the interrupt type
  • the template now responds on the subscribe topic plus /message

29th of September 2024

  • initial release

Boilerplate WiFi Connect, OTA and GPIO handling for ESP8266 and ESP32

The sketch is supposed to provide an universal and all-encompassing tool for purpose of interfacing with the GPIO pins on an ESP8266 or ESP32 device. The design idea is that the sketch will just provide a thin glue between the GPIO pins and an MQTT bus such that all processing that does not involve interfacing with the GPIO pins will take place off the ESP device with some other script or program that will be interfacing with the ESP via the MQTT bus. In practice, the sketch has been used with dataflow programming such as Node-Red but it is possible to interface with the sketch from any environment that supports publishing and subscribing to and from an MQTT broker.

In short, in case your application requires toggling pins, reading analog/digital pins or receiving interrupt updates from a remote WiFi-connected ESP device then this template covers all the aforementioned operations. The sketch was created because it covers a large range of typical applications for multiple ESP devices, especially tiny ESP-01S, where a sketch might have had to be written each and every time, even though, all that the sketch would have done would have been to set or read GPIO pins.

The template is based on the wifipreboot template and implements a captive portal-like environment to configure the initial WiFi network, OTA and then obsoletes the older esp-pin-toggle and esp-pin-toggle-analog templates by making the features of both those templates available in one single all-encompassing template.

Usage

The template must be configured in order to set the MQTT broker hostname at the top and the password in order to be able to configure the template within the preboot environment. The template can then be uploaded onto the device and after a restart, the device should blink the WiFi AP number tag. The AP can be then connected to using a different device in order to set up WiFi and make other preliminary settings. In case no MQTT topic is configured by editing the template header, then the template will subscribe to the MQTT broker on the same topic name as the name that will be configured for the device via the WiFi preboot environment.

Once everything is set up, the device should connect to the MQTT broker and subscribe to the configured topic (the device name, by default). Any response will be published on the MQTT topic concatenated with /messages (configurable by editing MQTT_TOPIC_OUTBOX in the code). Once subscribed, the template will publish a "hello" message on the MQTT topic plus /messages indicating that the bootup worked fine and will report the client ID.

From then on, commands can be issued on the configured MQTT topic (or the name of the device) and the device will publish results on the MQTT topic plus /messages.

Application Programmer Interface

Here is a table of actions available, the possible options and an example for each:

Action Parameter Possible Value Description Example JSON
get pin any digital pin number get the digital level of a GPIO pin indicated by pin
{
    "action": "get",
    "pin": 4
}
set pin any digital pin number set the digital level of a pin depending on the state parameter to either HIGH (on) or LOW (off)
{
    "action": "set",
    "pin": 4,
    "state": "on"
}
state on, off
debounce pin any digital pin number the debounce action can be used to simulate a digital button press for devices and gadgets that require simulating pushing and releasing a button with a certain time interval between the two (ie: long-press); the action allows to specify sleep, the amount of time between the figurative press and release, as well as mode set to either HTL or LTH meaning setting the digital pin level from HIGHT to LOW, respectively LOW to HIGH with HTL being the default
{
  "pin": "2",
  "sleep": "2500",
  "action": "debounce"
}
sleep an amount of time to sleep between toggling the pin between HIGH or LOW
mode HTL from HIGH to LOW, or LTH from LOW to HIGH
measure pin any analog pin number get the analog value of the GPIO pin indicated by pin
{
    "action": "measure",
    "pin": 0
}
interrupt pin any digital pin number that can be used as an interrupt pin set up an interrupt for pin number pin
{
    "action": "interrupt",
    "pin": 12,
    "state": "start",
    "mode": "falling"
 
}
state either start or stop
mode can be low, change, rising or falling

Upon publishing the payload, the template will respond on the same topic plus /messages using a matching JSON payload containing the results and the execute key set to the original JSON payload that was sent by the user for the purpose of linearizing requests and responses. Commands that are deemed to return results, for example, get or measure, will return the results formatted on the MQTT topic plus /messages.

Code

Unable to display file "https://svn.grimore.org/arduino-sketches/arduinoGPIOTool/arduinoGPIOTool.ino": It may not exist, or permission may be denied.