H4PluginsFF

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

28/06/2021 Release Notes v3.2.0

If you are able, please Support me on Patreon and/or subscribe to my Youtube channel (instructional videos)

Watch the videos

youtube

Documentation caveat

This a major release with many changes "under the hood". There are 85 example sketches which demonstrate the all the features of library. They have all been tested, so until this message is removed, they are the one definitive source for the API, as there is SO much documentation to check and fix... [ TL;DR 6000+ lines of documenation in 40 files] with quite a bit more to come.

I would rather get the library "out there" with bad / missing / incorrect documentation than continue to delay the release. I am working hard to bring the documentation up to date, so until It's finished, please be patient. This document itself is accurate and up-to-date as at 16/05/2021

Key

:heavy_check_mark: = As good as it's likely to get for this release
:building_construction: = Missing / Work in Progress
:gem: = Absolutely essential: without reading this you will find it hard going.
:cherry_blossom: = Interesting but not 100% essential: a "sidebar article"
:door: = "external" - takes the reader away from the current page, perhaps even offsite

If in doubt, or you can't find something, refer first to :door: Documentation Master Index. If the file doesn't have a :heavy_check_mark:, it hasnt yet been reviewed. It may function as a pointer to get you started, but don't trust it 100%

For a bit of fun, :cherry_blossom: :door: here is the size of the task

Introduction
Diving In
Compatible Hardware
:gem: Installation
:door: Overview of the 32 current plugins
:door: Documentation Master Index
:door: Youtube Channel
What Next?
Installation
Issues

Introduction

It is a simple (and unavoidable) fact of life that successful IOT Apps that are more than just a "blinky" require special programming techniques to do many things at once. It is also true that those techniques are complex and take a long time to learn, even for experienced programmers. H4Plugins is a method of getting you started in sophisticated IOT apps on ESP8266 / ESP32 without that steep learning curve. All the hard work has been done for you and you are left with a very simple event-driven framework into which you just drop the simple few lines of code that you want your app to do when "x" happens.

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.

Think of H4 and its plugins as "IOT Lego" or an "IOT Swiss Army Knife" (or both) to get your IOT app up and running in minutes rather than weeks. If you have some basic C / C++ experience then H4 and its H4Plugins are for you! Most get included with only a single line of code.

You will modules (and over 80 example sketches) for WiFi + OTA, Webserver, MQTT, numerous common types of GPIO handling (e.g. debouncing, rotary encoders), Amazon Alexa voice control, NTP synchronisation, device presence detection, logging to remote MySQL server and extensive diagnostics. By "plugging " together only the required modules, you can rapidly build your own custom firmware or IOT app. Everything you build will be stable and responsive, with a built-in control panel: the plugins work together to allow multiple simultaneous processes to run, so no more WDT resets! As your experience grows you can extend your app / firmware with H4Plugins' well-documented* API and runtime command system.

(* It will be when it's finished :) )

Diving in

Watch the video

1. "Blinky on Steroids"

H4 and its plugin system represent a very different way of getting started on ESP8266 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 ESP8266 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.

sonoff

SONOFF Basic Example

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 debounce

And here's what you see when you point your browser to the webserver running inside the device:

sonoffbasic

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 yout 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:

sonoffbasic

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 :smile: - If you know of anything easier, please let us know too!

Designed for programmers

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 recently 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 throroughly documented in the li

H4plugins

Install / Use

README