Enables rapid development of IOT apps using WiFi, MQTT, NTP, OTA, Alexa voice control etc with an emphasis on performing multiple simultaneous functions
Most of the above is achieved with only a few lines of code, with many features requiring on the inclusion of only a single line
In Memoriam: Phil Bowles, the original creator of H4Plugins, passed away. The community is deeply grateful for his innovative contributions to the ESP8266 and ESP32 ecosystem. Maintenance has been taken over by Hamza Hajeir.
Keep Philbowles remembered by viewing and sharing his Youtube channel (instructional videos)
Key
-
✔️ = As good as it's likely to get for this release
-
🏗️ = Missing / Work in Progress
-
💎 = Absolutely essential: without reading this you will find it hard going.
-
🌸 = Interesting but not 100% essential: a "sidebar article"
-
🚪 = "external" - takes the reader away from the current page, perhaps even offsite
If in doubt, or you can't find something, refer first to the 🚪 Documentation Master Index. If the file does not have a check mark [:heavy_check_mark:], it has not yet been reviewed. It may function as a pointer to get you started, but do not trust it completely.
For reference, here is the size of the task
- Introduction
- Diving In
- Compatible Hardware
- 💎 Installation
- 🚪 Overview of the 32 current plugins
- 🚪 Documentation Master Index
- 🚪 Youtube Channel
- What Next?
- Installation
- Issues
Successful IoT applications that perform multiple simultaneous functions require specialized programming techniques. These techniques are complex and time-consuming to learn, even for experienced programmers. H4Plugins provides a way to develop sophisticated IoT applications on ESP8266, ESP32, and RP2040 without the steep learning curve. The framework handles the complexity, allowing developers to focus on implementing the specific behaviors they want when events occur.
More information on why this is the case and why event-driven programming is the solution can be found in the pre-requisite H4 library.
H4 and its plugins provide a modular framework to rapidly develop IoT applications. With basic C/C++ experience, developers can use H4 and H4Plugins effectively. Most plugins can be included with a single line of code.
The framework includes modules for WiFi, OTA updates, web server, MQTT, GPIO handling (such as debouncing and rotary encoders), Amazon Alexa voice control, NTP synchronization, device presence detection, remote logging, and diagnostics. By combining the necessary modules, developers can quickly build custom IoT firmware. The resulting applications are stable and responsive, with built-in control interfaces. The plugins enable multiple simultaneous processes without watchdog timer resets. As experience grows, applications can be extended using the well-documented API and runtime command system.
H4 and its plugin system represent a very different way of getting started on ESPs and RPI Picos from the "standard" examples found all over the web.
There are many good reasons for that but it means that there are a few things you need to know about H4 and how it works before "diving in" to the H4Plugins system. Spending a few minutes reading the basics of H4 will save you days and even weeks of effort, so please digest it all before trying some of the 80+ examples in this repo - it will be time well spent!
Once you "get" how H4 and the plugin system work, you will be able to churn out fully working, multi-functional stable IOT apps on Wi-Fi Enabled MCUs in only a few lines of code, compared with literally hundreds of lines in the "standard" way of doing things. That's if you can even find anything close to what you need...
To get a "feel" for just how different H4 and H4Plugins are from all the other examples you will find on the web, let's see an example of H4Plugins being used to build replacement firmware for a SONOFF Basic switch.
What follows is the entire H4Plugins code - despite the fact it might look like there is something missing, there is not. The code as shown compiles to produce firmware that can be uploaded directly to your SONOFF device and provides:
- Seamless autoconnect/reconnect of failed WiFI and/or MQTT with no reboot
- OTA
- Full control via Serial console
- Full control via MQTT plus automatic publishing of state change
- Full control via built-in Web console
- Single-button control for on/off, reboot, factory reset depending on the time pressed down
- LED pattern signalling, e.g. ... --- ... ("SOS") = No WiFi, two short blips = no MQTT etc
- HTTP REST-like control from any other device with JSON response
- Dynamic reconfiguration of SSID, MQTT server, Alexa UPNP device name
- UPNP device control from e.g. Windows Network Explorer
- Amazon ECHO "Alexa" voice control
- Auto-off timeout if required, which persists across reboots
#include<H4Plugins.h>
H4_USE_PLUGINS(115200,H4_Q_CAPACITY,false) // Serial baud rate, Q size, SerialCmd autostop
H4P_WiFi wiffy("XXXXXXXX","XXXXXXXX","basic");
H4P_AsyncMQTT cutie("http://192.168.1.4:1883");
H4P_BinarySwitch relay(D6,ACTIVE_HIGH);
H4P_UPNPServer lexy("Sonoff Basic Switch");
h4pMultifunctionButton mfb(0,INPUT,ACTIVE_LOW,15); // 15ms of debounceAnd here's what you see when you point your browser to the webserver running inside the device:
The "big red switch" switches the device on / off. GPIO12 (D6) is lit up in red showing the device's relay is currently OFF - it will go green when the device is ON, similar to the green LED showing that MQTT is currently connected successfully. The builtin LED on GPIO2 is blue on the test board, but you can make it whatever colour matches your actual board.
You can also switch the device using MQTT, HTTP, serial monitor, Alexa voice command an even the physical button if you simply have to. The button is debounced, and if you hold it down for longer than 2 seconds, the built-in LED will start to flash to warn you that when you release it, the device will reboot.
If you hold down the uswr button for longer than 5 seconds, the device will "factory reset" and clear any saved values, such as the Auto-off timer if you have ever changed it from zero.
You also get a "web console" that allows you to control the device in the same way as if you were connected via a Serial link. On Windows, it is also visible to your PC's Network Explorer and you can control the device with the right-click menu:
As you can see, pretty much all you need to do is list the modules/functionality you require and provide a few necessary starting values such as ssid / passwords etc. The plugins link up with each other, exchange messages between themselves and "stitch" everything together into a seamless piece of stable firmware.
Not bad for 7 lines of code, I think you'll agree 😄 - If you know of anything easier, please let us know too!
The modular design of H4's plugin architecture minimises scarce resources in low-memory MCU targets: You only compile in what you need by choosing the relevant bulding blocks. Detailed logging and/or diagnostics can be easily included (or completely compiled-out) and controlled at runtime via the serial console, web console, HTTP REST or MQTT depending on which options you choose. It is built on top of the very stable H4 timer/scheduler which traces its ancestry back to "Esparto" - of which one user had said: "and now have Esparto modules with months of uptime without any issues".
There are over 80 example sketches demonstrating all the features and the APIs of all of the plugins. They should be used both as a template for your own sketches and as a learning resource.
Each plugin is also thoroughly documented in the links below.
- ESP8266 - any board e.g. nodeMCU, Wemos D1 Mini etc
- ESP8285 - any board e.g. Wemos D1 mini Lite
- ESP32 - any board e.g. DevKit, Lolin D32
- RP2040 - Any board e.g Raspberry Pi Pico W
- SONOFF Basic, S20, SV and RF. Others may work too if ESP8266 based
H4Plugins sits at the top of a structure of underlying libraries with strange names, which we like to call "the menagerie". Each of them can be used in its own right without needing H4Plugins, but they all work best when H4Plugins pulls them all together and manages them.
SEE Installation
| Name | Provides | Notes | |
|---|---|---|---|
| H4AsyncTCP | "Glue" to LwIP | Reliable Async TCP Library | |
| H4AsyncWebServer | Basis of webUI in H4Plugins | Reliable Webserver with Websockets support | |
 |
H4Tools | '32/'8266/RP2040 HAL and utility functions | |
 |
H4AsyncMQTT | Async MQTT Client | QoS 0/1/2 Fully 3.1.1/5.0 compliant. Large payloads |
 |
ArmadilloHTTP | Async HTTP/S Client | Simple send/callback of large payloads |
 |
H4 | Scheduler/Async Timers | |
 |
H4/Plugins | Full Async IOT Firmware | Webserver, MQTT, OTA, NTP, HTTP etc etc |
H4Plugins is tested using
To reduce the footprint of the binary code and provide best WiFi / MQTT performance, the following IDE options are recommended (if available for the chosen board):
You'll need to upload the required FileSystem data to the MCU memory, the data is needed for any WiFi sketches for at least to run the Webserver UI. Upload the FileSystem using the appropriate tool for, keep in mind LittleFS is the used one.
If in doubt, use PlatformIO and hit Upload FileSystem Image, or execute pio run -t uploadfs with specification of the target environment and upload porting whenever needed.
There is a lot in this library, its pre-requisite: the H4 library and the rest of "the mangerie". For a start, there are over 30 individual plugins, as well as several new concepts to learn, although you will probably only use 6 or 7 of the more common / important ones for most of your apps.
Then there are over 80 example sketches in the two libraries. Every plugin and every possible API call is demonstrated at least once somewhere in that collection. It's designed to help you get up to speed quickly - use it! 90% of the time you will find the start (if not all) of the app you want to write.
After you have finished reading this file, the recommended path you should follow for mastery of these libraries is:
-
Download, install and play with H4. Pick one or two of the examples and run it.
-
Read the H4 documentation carefully. Everything H4P does is based on using the features of the scheduing library. As the examples here use the library's API extensively.
-
By this point you will have got "the feel" of event-driven programming and how everything is done in H4Plugins.
-
Watch the first video in the training series
-
Read
- Everything is an event: Listeners, Emitters and Handlers
- Global Variables and persistent storage
- Common Command and Control: H4P_SerialCmd
These three concepts are the entire basis of H4 and the plugins system, They form the core of any / all apps you will create. Once you have these three "under your belt" all the rest of the plugins and examples just fall into place.
Don't skip this step, as without these three, everything is going to look like gibberish.
-
Read Switches and Things as the vast majority of simple apps will have one of these as is main function...
-
...such as the basic sonoff app (it works on pretty much any hardware) Compile it and play with controlling it via Serial, builtin Webserver, MQTT, REST etc
-
Read Event Listeners and Event Emitters because in this class are some incredibly useful tools for helping you debug your code and log any problems or errors as you get more adventurous.
-
Now work your way through several of the GPIO examples. Start with "raw" and then "debounced" - once you understand those two all the rest will start to make a lot more sense. If you DO have a rotary encoder, hook it up and delight in the ease with which you will be able to use it!
-
Try a few of the other examples to give yourself an idea of the range and flexibility of the whole system
- At each stage above, check out the dedicated H4Plugins Youtube channel to see if the relevant video has been produced yet - working as fast as possible to get a whole video library out there for you.
One can get a homogeneous H4 Stack versions from the PlatformIO H4Plugins Environment. One can reuse the environment directly, or copy the parts of interest in the configuration file platformio.ini in a new project.
Simply download the zip of this repository and install as an Arduino library: Sketch/Include Library/Add .ZIP Library...
-
As with all H4 and H4Plugins libraries, please make sure you have read the relevant documentation relating to the issue and watched any videos on the Youtube channel (instructional videos).
-
If there is a genuine issue then you will be referred to Raising issues after which you are advised to create a full github issue report.
For more information, read out the License change statement, which covers our awared and responsible decision.