Merge branch 'v0.3.4'

README.md

@@ -9,7 +9,7 @@
 *All plugins depend upon the presence of the [H4 library](https://github.com/philbowles/H4), which must be installed first.*
 
 ---
-Version **0.2.1** [Release Notes](changelog.txt)
+Version **0.3.4** [Release Notes](changelog.txt) **MUST UPGRADE TO [H4 library](https://github.com/philbowles/H4) v0.4.1 first!**
 
 ![H4PluginsFF](/assets/h4plugins.jpg)
 
@@ -49,7 +49,7 @@ As you can see, all you need to do is list the modules you want (in the right or
 
 The modular design of H4's plugin architecture minimises scarce resources in low-memory MCU targets: You only compile in what you need with a simple `#include`. Detailed diagnostics can be easily included and controlled at runtime via the serial console, HTTP REST or MQTT depending on which options you choose. It is built on top of the very stable [H4](https://github.com/philbowles/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 an issue"*.
 
-There are 31 example sketches demonstrating the features and API of all of the plugins. They should be used both as a template and a learning resource.
+There are 40 example sketches demonstrating all the features and the API of all of the plugins. They should be used both as a template for your own sketches and as a learning resource.
 
 Users are strongly recommended to work through them in the order [listed below](readme.md#current-plugins-februrary-2020)
 
@@ -89,27 +89,32 @@ When you think that H4Plugins also has "plug and play" rotary encoder handling,
 
 ---
 
-# Current Plugins (Feb 2020)
+# Current Plugins (as of v0.3.4 - Feb 2020)
 
 ## Core IOT functionality
 
-* [**H4P_SerialCmd**](docs/h4sc.md): Send commands to H4 and/or plugins to control and/or diagnose
+* [**H4P_SerialCmd**](docs/h4sc.md): Send commands from multiple sources to H4 and/or plugins to control and/or diagnose
 * [**H4P_FlasherController**](docs/h4fc.md): One-line coding of multiple simultaneous LED flashing by Square Wave, PWM, abitrary pattern and Morse code
 * [**H4P_GPIOManager**](docs/h4gm.md): One-line coding of debouncing, retriggering, rotary encoding plus numerous other GPIO strategies
 * [**H4P_WiFi**](docs/h4wifi.md): Automatic Connection / reconnection manager + AP configuration + OTA + HTTP REST
+* [**H4P_AsyncWebServer**](docs/h4asws.md): Fully Asynchronous Webserver
 * [**H4P_MQTT**](docs/h4mqtt.md): Automatic Connection/ reconnection MQTT client alows remote control of H4
-* [**H4P_BasicSwitch**](docs/h4onof.md): GPIO object that allows control by simple commands that become available to other plugins
-* [**H4P_UPNPSwitch**](docs/h4upnp.md): Extends [H4P_BasicSwitch](docs/h4onof.md) into full UPNP device with Alexa voice control
-* [**H4P_ThreeFunctionButton**](docs/h43fnb.md): Multi-function physical control on/off,reboot,factory reset depending on hold time
+* [**H4P_BinarySwitch**](docs/h4onof.md): GPIO object that allows control by commands from multiple sources
+* [**H4P_BinaryThing**](docs/xxx.md): functional object that allows control by commands from multiple sources  **NEW in v0.3.4**
+* [**H4P_UPNPSwitch**](docs/h4upnp.md): Extends [H4P_BinarySwitch](docs/h4onof.md) into full UPNP device with Alexa voice control
+* [**H4P_UPNPThing**](docs/xxx.md): Extends [H4P_BinaryThing](docs/xxx.md) into full UPNP device with Alexa voice control  **NEW in v0.3.4**
+* [**H4P_ThreeFunctionButton**](docs/h43fnb.md): Multi-function physical control on/off,reboot,factory reset depending on hold time. Binds to xSwitch or xThing
 
 ## Diagnostic / Development tools:
 
 * [**H4P_CmdErrors**](docs/h4ce.md): Provide text error messages instead of error codes to SerialCmd
 * [**H4P_QueueWarn**](docs/h4qw.md): Call user function on low Queue
 * [**H4P_TaskSniffer**](docs/h4ts.md): Low-level task / queue dumper for H4 + Plugins
-* [**H4P_SerialLogger**](docs/h4logs.md): Event logging to serial monitor **NEW in v0.2.0**
-* [**H4P_LocalLogger**](docs/h4logs.md): Event logging to SPIFFS file **NEW in v0.2.0**
-* 
+* [**H4P_SerialLogger**](docs/h4logs.md): Event logging to serial monitor
+* [**H4P_LocalLogger**](docs/h4logs.md): Event logging to SPIFFS file
+* [**H4P_MQTTLogger**](docs/h4logs.md): Event logging to MQTT Server **NEW in v0.3.4**
+* [**H4P_MQTTHeapLogger**](docs/h4logs.md): Specialised H4P_MQTTLogger which periodically logs value of FreeHEap **NEW in v0.3.4**
+  
 ## Specialist Device Drivers
 
 * [**H4P_ExternalSqWave**](docs/h4esw.md): Serial driver for cheap ebay square wave device
@@ -164,8 +169,6 @@ And:
 
 If using WiFi, you will need to install either the [ESP8266 sketch data uploader](https://github.com/esp8266/arduino-esp8266fs-plugin) or the [ESP32 sketch data uploader](https://github.com/me-no-dev/arduino-esp32fs-plugin) (or both) depending on which platform you compile for. 
 
-*(Many thanks to Kerry Clendinning for his help with this section)*
-
 ## Note for PlatformIO users
 
 Unfortunately PlatformIO has (had?) several issues that prevent *some* valid Arduino libraries from being installed correctly. I am happy to provide support for H4Plugins code if you manage to get an installation working, providing that none of the files are changed in any way. Sadly, until PlatformIO get the issues fixed, I am unable to provide any support for the installation / build process.
@@ -185,7 +188,6 @@ are recommended (if available for the chosen board):
 ## For WiFi sketches
 
 * lwIP Variant: v2 Higher Bandwidth (No Features)
-* SSL Support: Basic SSL Ciphers (Lower ROM Use)
 
 ### **IMPORTANT**
 
@@ -201,7 +203,6 @@ WiFI sketches must reserve SPIFFS space to hold the AP Mode web pages. These tak
 * Server-pull OTA
 * NODE-RED nodes for H4 devices
 * NODE-RED GUI controller for management of grid of H4 devices
-* Command logger (+SQL)
 * wifiClient http / https
 
 Plus of course any others you think may be useful. Let me know using one of the links below

changelog.txt

@@ -1,3 +1,25 @@
+2020/02/18  0.3.4
+    breaking changes:
+    1. _hasName removed from H4: MUST upgrade to 0.4.1
+    2. BasicSwitch renamed to BinarySwitch
+    new
+    1. Logging
+        filtering added to exisiting loggers
+        added loggers:
+            H4P_MQTTLogger
+            H4P_MQTTHeapLogger
+    2. Thing/Switch paradigm
+        BasicSwitch renamed to BinarySwitch
+        added   BinaryThing
+                UPNPThing
+        GPIOManager heavily modified
+            added   DebouncedThing
+                    EncoderThing
+                    LatchingThing
+                    PolledThing
+                    RawThing
+                    RetriggeringThing
+
 2020/02/12  0.2.1
     patch - put back in ip display on got ip
     move AP mode ssid lists delete to STA got IP

docs/h43fnb.md

@@ -1,6 +1,6 @@
 ![H4P Flyer](/assets/GPIOLogo.jpg) 
 
-## Three Function Button
+## Three Function Button (short name="tfnb")
 
 ### Adds 3-function* GPIO button to H4 Universal Scheduler/Timer
 
@@ -9,20 +9,22 @@
 ---
 ## What does it do?
 
-Allows the user to control a switch plugin, either a [H4P_BasicSwitch](h4onof.md) or a [H4P_UPNPSwitch](h4upnp.md) by pressing and holding a simple non-latching 'tact' button. The button causes 3 different actions to occur depending on how long it held down.
+Allows the user to control a switch plugin, a [H4P_BinarySwitch](things.md) [H4P_BinaryThing](things.md), [H4P_UPNPSwitch](things.md)  or a [H4P_UPNPThing](things.md) by pressing and holding a simple non-latching 'tact' button. The button causes 3 different actions to occur depending on how long it held down.
 
-In essence it links an output GPIO (defined by the swicth plugin) to an input GPIO and uses an LED to signal its changing state.
+In essence it links an output GPIO (defined by the xSwitch or xThing plugin) to an input GPIO connector and uses an LED to signal its changing state the longer the button is held.
 
-A "short" press (less than 2 seconds) simply switches the device to the opposite state as a "normal" press of any button might do. The resulting action depends on the definition of the linked switch plugin.
+A "short" press (less than 2 seconds**) simply switches the device to the opposite state as a "normal" press of any button might do. The resulting action depends on the definition of the linked switch plugin.
 
-A "medium" press over 2 seconds (but less than 5 seconds) starts the associated LED flashing rapidly and when the button is released, the device will reboot.
+A "medium" press over 2 seconds (but less than 5 seconds**) starts the associated LED flashing rapidly and when the button is released, the device will reboot.
 
-A "long" press - anything over 5 seconds - starts the LED flashing extremely rapidly and when the button is released, the device will clear any stored configuration information and then reboot, a process known as a "factory reset".
+A "long" press - anything over 5 seconds** - starts the LED flashing extremely rapidly and when the button is released, the device will clear any stored configuration information and then reboot, a process known as a "factory reset".
 
 **N.B** If the [H4P_WiFi](h4wifi.md) plugin is in use, the factory reset will clear any stored WiFi credentials therefore ensuring the when the device reboots, it will start in AP configuration mode.
 
 (* ***Four** functions if you count the LED flashing* :) )
 
+(** These default values can be changes by the user - see "Tweakables" below)
+
 ---
 
 # Usage
@@ -32,11 +34,12 @@ A "long" press - anything over 5 seconds - starts the LED flashing extremely rap
 H4_USE_PLUGINS
 
 H4P_GPIOManager h4gm;
-// either
-H4P_UPNPSwitch h4upnp(...
-//or
-H4P_BasicSwitch h4upnp(...
-H4P_ThreeFunctionButton h43fb(...
+// one of
+//H4P_UPNPSwitch h4bt(...
+//H4P_UPNPThing h4bt(...
+//H4P_BinarySwitch h4bt(...
+//H4P_BinaryThing h4bt(...
+H4P_ThreeFunctionButton h4bt(...
 ```
 
 # Dependencies
@@ -47,28 +50,18 @@ Requires a GPIO pin to be connected to an LED (default is LED_BUILTIN) and a "ta
 
 none
 
-# Callbacks
-
-```cpp
-void onChange(uint32_t sweptValue); // called when swept value changes
-```
-
-# Trusted Name
-
-*TFNB*
-
 # Unloadable
 
 NO
 
 ---
 
-## API
+# API
 
 ```cpp
 /* constructor: */
 H4P_ThreeFunctionButton(
-    H4P_BasicSwitch* bsp,  //a reference to a previoulsy defined H4P_BasicSwitch or H4P_UPNPSwitch
+    H4P_BinarySwitch* bsp,  //a reference to a previoulsy defined H4P_BinarySwitch or H4P_UPNPSwitch
     uint32_t dbTimeMs, // the switch debounce value in milliseconds: depends on the individual switch
     //          the input button
     uint8_t pin,
@@ -80,7 +73,28 @@ H4P_ThreeFunctionButton(
     );
 ```
 
-[Example code](../examples/H43FNB/H4P_SONOFF_Basic/H4P_SONOFF_Basic.ino)
+[Example code](../examples/H4P_SONOFF_Basic/H4P_SONOFF_Basic.ino)
+
+---
+
+# Tweakables
+
+The following values are defined in `H4PConfig.h` . They are chosen initally to set a good balance between stability, performance and memory / stack usage. *It is not advisable to change them unless you know exactly what you are doing and why*. 
+
+**N.B.** **Support will not be provided if any of these values are changed.**
+
+* H43F_MEDIUM            175
+Millisecond flash rate of a medium press
+
+* H43F_FAST               50
+Millisecond flash rate of a long press
+
+* H43F_TIMEBASE          175
+Timebase of the Morse S-O-S flash when signalling onWiFIDisconnect (if [H4P_WiFi](h4wifi.md) is used)
+* H43F_REBOOT           2000
+Millisecond time defining transition from short->medium
+* H43F_FACTORY          5000
+* Millisecond time defining transition from medium->long
 
 ---
 

docs/h4asws.md

@@ -1,6 +1,6 @@
 ![H4P Flyer](/assets/HTTPLogo.jpg) 
 
-# Asynchronous Web Server
+# Asynchronous Web Server (short name="asws")
 ## Adds Asynchronous Webserver, AP mode configuration to H4 Universal Scheduler/Timer. Runs on ESP8266/32 only
 
 *All plugins depend upon the presence of the [H4 library](https://github.com/philbowles/H4), which must be installed first.*
@@ -50,10 +50,6 @@ void onDisconnect(void); // webserver is down
 void h4AddAwsHandlers(void) // called after adding its own handlers, adds your in here
 ```
 
-## Trusted Name
-
-*ASWS*
-
 ## Unloadable
 
 No, but can be stopped with `h4/asws/stop` command.
@@ -95,7 +91,7 @@ The REST interface allows the user to enter commands in a similar fashion to the
 
 ![JSONREST](../assets/rest.jpg)
 
-When "prettified" it loks like this:
+When "prettified" it looks like this:
 
 ```json
 

docs/h4ce.md

@@ -1,5 +1,6 @@
 ![H4P Flyer](/assets/DiagLogo.jpg) 
-# Command Errors
+
+# Command Errors (short name="cerr")
 
 # Adds error-code to meaningful message translation to SerialCmd plugin for H4 Universal Scheduler/Timer.
 
@@ -46,10 +47,6 @@ None, but must be included *before* [**H4P_SerialCmd**](h4sc.md)
 
 none
 
-### Trusted Name
-
-*CERR*
-
 ### Unloadable
 
 NO

docs/h4esw.md

@@ -1,6 +1,6 @@
 ![H4P Logo](/assets/DriversLogo.jpg)
 
-# External Square Wave Generator
+# External Square Wave Generator (short name "esqw")
 
 ## Adds driver/controller for Square Wave Generator module to H4 Universal Scheduler/Timer
 *All plugins depend upon the presence of the [H4 library](https://github.com/philbowles/H4), which must be installed first.*
@@ -61,10 +61,6 @@ y2 is the "to" y
 void onChange(uint32_t sweptValue); // called when swept value changes
 ```
 
-## Trusted Name
-
-*ESQW*
-
 ## Unloadable
 
 NO

docs/h4fc.md

@@ -1,6 +1,6 @@
 ![H4P Logo](/assets/GPIOLogo.jpg)
 
-# Flasher Controller
+# Flasher Controller (short name="wink")
 
 ## Adds multiple LED blinking methods to H4 Universal Scheduler/Timer.
 
@@ -32,16 +32,12 @@ H4P_FlasherController h4fc;
 
 ## Dependencies
 
-none, but must be created *after* [**H4P_SerialCmd**](h4sc.md) if using that plugin. Also if [**H4P_GPIOManager**](h4gm.md) is in use, the relevant pin will be automatically set as output - otherwise it is up to the user to call `pinMode` before any API function below and to manage its logical / physical and active high /active low states. The simplest solution is to always also include [**H4P_GPIOManager**](h4gm.md). 
+none, but must be created *after* [**H4P_SerialCmd**](h4sc.md) if using that plugin. Also if [**H4P_GPIOManager**](h4gm.md) is in use, the relevant pin will be automatically set as output - otherwise it is up to the user to call `pinMode` before any API function below and to manage its logical / physical and active high /active low states. The simplest solution is to always also include [**H4P_GPIOManager**](h4gm.md) before H4P_FlasherController.
 
 ## Commands Added
 
 none *TODO* add dynamic command-line control
 
-## Trusted Name
-
-*WINK*
-
 ## Unloadable
 
 NO:

docs/h4gm.md

@@ -1,6 +1,6 @@
 ![H4P Flyer](/assets/GPIOLogo.jpg) 
 
-# GPIO Manager
+# GPIO Manager (short name="gpio")
 
 ## Adds sophisticated GPIO management to H4 Universal Scheduler/Timer.
 
@@ -38,10 +38,6 @@ none
 
 h4/show/pins
 
-## Trusted Name
-
-*GPIO*
-
 ## Unloadable
 
 YES: No GPIO activity is futher handled. This cannot be undone.
@@ -69,6 +65,14 @@ GPIOManager currently provides behaviours for:
 * Sequenced - Increments counter for each ON/OFF press
 * Timed - Reports how long button held ON
 
+You should also read [Things vs Switches](things.md) which explains how some of the above strategies can be autmatically tied/bound/linked to predefined output actions. In it you will find how to use these variants of the above, each of which send an ON or OFF command to a linked output handler
+
+* DebouncedThing - binds a Debounced input to a BinarySwitch or UPNPSwitch output
+* EncoderThing - binds a Encoder input to a BinarySwitch or UPNPSwitch output
+* LatchingThing - binds a Latching input to a BinarySwitch or UPNPSwitch output
+* PolledThing - binds a Polled input to a BinarySwitch or UPNPSwitch output 
+* RawThing - binds a Raw input to a BinarySwitch or UPNPSwitch output
+* RetriggeringThing - binds a Retriggering input to a BinarySwitch or UPNPSwitch output
 
 Before we dive into the strategies, let's deal with the sometimes confusing concept of "Active High" and "Active Low" (experts can skip the next section)
 
@@ -407,22 +411,28 @@ void            toggle(uint8_t p); // reverse current logical state
 //
 //      Strategies
 //
-CircularPin*        Circular(uint8_t p,uint8_t mode,H4GM_SENSE sense,uint32_t dbTimeMs,uint32_t nStages,H4GM_FN_EVENT callback);
-DebouncedPin*       Debounced(uint8_t p,uint8_t mode,H4GM_SENSE sense,uint32_t dbTimeMs,H4GM_FN_EVENT callback);
+CircularPin*        Circular(uint8_t p,uint8_t mode,H4GM_SENSE sense,uint32_t dbTimeMs,uint32_t nStages,H4GM_FN_EVENT callback);//
+DebouncedPin*       Debounced(uint8_t p,uint8_t mode,H4GM_SENSE sense,uint32_t dbTimeMs,H4GM_FN_EVENT callback);//
+DebouncedPin*       DebouncedThing(uint8_t p,uint8_t mode,H4GM_SENSE sense,uint32_t dbTimeMs,H4P_BinaryThing* btp);//
 EncoderPin*         Encoder(uint8_t pA,uint8_t pB,uint8_t mode,H4GM_SENSE sense,H4GM_FN_EVENT);
 EncoderPin*         Encoder(uint8_t pA,uint8_t pB,uint8_t mode,H4GM_SENSE sense,int&);
+EncoderPin*         EncoderThing(uint8_t pA,uint8_t pB,uint8_t mode,H4GM_SENSE sense,H4P_BinaryThing* btp);
 EncoderAutoPin*     EncoderAuto(uint8_t pA,uint8_t pB,uint8_t mode,H4GM_SENSE sense,int vMin,int vMax,int vSet,uint32_t vIncr,H4GM_FN_EVENT);
 EncoderAutoPin*     EncoderAuto(uint8_t pA,uint8_t pB,uint8_t mode,H4GM_SENSE sense,int vMin,int vMax,int vSet,uint32_t vIncr,int&);
-FilteredPin*        Filtered(uint8_t p,uint8_t mode,H4GM_SENSE sense,uint8_t filter,H4GM_FN_EVENT callback);
-LatchingPin*        Latching(uint8_t p,uint8_t mode,H4GM_SENSE sense,uint32_t dbTimeMs,H4GM_FN_EVENT callback);
-MultistagePin*      Multistage(uint8_t p,uint8_t mode,H4GM_SENSE sense,uint32_t dbTimeMs,H4GM_STAGE_MAP stageMap,H4GM_FN_EVENT callback);
-OutputPin*          Output(uint8_t p,H4GM_SENSE sense,uint8_t initial,H4GM_FN_EVENT callback=[](H4GPIOPin*){});
-PolledPin*          Polled(uint8_t p,uint8_t mode,H4GM_SENSE sense,uint32_t frequency,uint32_t isAnalog,H4GM_FN_EVENT callback);
-RawPin*             Raw(uint8_t p,uint8_t mode,H4GM_SENSE sense,H4GM_FN_EVENT callback);
-RepeatingPin*       Repeating(uint8_t p,uint8_t mode,H4GM_SENSE sense,uint32_t dbTimeMs,uint32_t frequency,H4GM_FN_EVENT callback);
+FilteredPin*        Filtered(uint8_t p,uint8_t mode,H4GM_SENSE sense,uint8_t filter,H4GM_FN_EVENT callback);//
+LatchingPin*        Latching(uint8_t p,uint8_t mode,H4GM_SENSE sense,uint32_t dbTimeMs,H4GM_FN_EVENT callback);//
+LatchingPin*        LatchingThing(uint8_t p,uint8_t mode,H4GM_SENSE sense,uint32_t dbTimeMs,H4P_BinaryThing* btp);//
+MultistagePin*      Multistage(uint8_t p,uint8_t mode,H4GM_SENSE sense,uint32_t dbTimeMs,H4GM_STAGE_MAP stageMap,H4GM_FN_EVENT callback);//
+OutputPin*          Output(uint8_t p,H4GM_SENSE sense,uint8_t initial,H4GM_FN_EVENT callback=nullptr);// FIX ptr type
+PolledPin*          Polled(uint8_t p,uint8_t mode,H4GM_SENSE sense,uint32_t frequency,uint32_t isAnalog,H4GM_FN_EVENT callback);//
+PolledPin*          PolledThing(uint8_t p,uint8_t mode,H4GM_SENSE sense,uint32_t frequency,uint32_t isAnalog,H4P_BinaryThing* btp);//
+RawPin*             Raw(uint8_t p,uint8_t mode,H4GM_SENSE sense,H4GM_FN_EVENT callback);//
+RawPin*             RawThing(uint8_t p,uint8_t mode,H4GM_SENSE sense,H4P_BinaryThing*);//
+RepeatingPin*       Repeating(uint8_t p,uint8_t mode,H4GM_SENSE sense,uint32_t dbTimeMs,uint32_t frequency,H4GM_FN_EVENT callback);//
 RetriggeringPin*    Retriggering(uint8_t _p, uint8_t _mode,H4GM_SENSE sense,uint32_t timeout, H4GM_FN_EVENT _callback);
-SequencedPin*       Sequenced(uint8_t p,uint8_t mode,H4GM_SENSE sense,uint32_t dbTimeMs,H4GM_FN_EVENT callback);
-TimedPin*           Timed(uint8_t p,uint8_t mode,H4GM_SENSE sense,uint32_t dbTimeMs,H4GM_FN_EVENT callback);
+RetriggeringPin*    RetriggeringThing(uint8_t _p, uint8_t _mode,H4GM_SENSE sense,uint32_t timeout,H4P_BinaryThing* btp);
+SequencedPin*       Sequenced(uint8_t p,uint8_t mode,H4GM_SENSE sense,uint32_t dbTimeMs,H4GM_FN_EVENT callback); //
+TimedPin*           Timed(uint8_t p,uint8_t mode,H4GM_SENSE sense,uint32_t dbTimeMs,H4GM_FN_EVENT callback); //
 //
 ```