Add new actuator : PWM controller (#737)

* Initial generalization from a PWM LED controller, to a PWM controller.
Allow the config file to set the name of each channel and the number of channels.
Fade time is now per-channel, so MQTT messages can genuinely set an individual channel, and specify the fade time for that channel.
The default gamma is configurable in the config.

docs/use/actuators.md

@@ -31,7 +31,46 @@ ON command
 Theoreticaly it should be possible to use every free IO pin. But after some tests only pin D2 works at WEMOS D1. Other platforms can work.
 The default setting use NEOPIXEL (WS2812B). The simplest wiring is direct connect D2 to data pin of LED stripe and connect VCC/GND to power source. You should also add an capacitor.
 
+## PWM
+This module allows control over PWM outputs.
+It's primary use is for controlling LEDs, but it should be equally at home controlling anything that's controlled using PWM.
+E.g. LEDs, servos, PC fans.
+You would typically connect a PWM output to a transistor or MOSFET to allow control over higher power devices.
 
+* JSON message format allows you to set any or all channels in a single message.
+* Each channel can be set to smoothly transition from its current setting to the new setting over a specified number of seconds.
+* Each channel can be calibrated with min and max settings, as well as a gamma curve.
 
+### Configuration
+In order to use the PWM actuator, you need to configure which pins the PWM output channels will be connected to.
+There are a couple of `#define`s that achieve this.
+They can be defined in the `build_flags` section of the env, or by directly editing `config_PWM.h`.
 
+```c
+#define PWM_CHANNEL_NAMES {"r", "g", "b", "w0", "w1"}
+#define PWM_CHANNEL_PINS  { 25,  33,  32,   23,   22}
+```
 
+`PWM_CHANNEL_NAMES` lists the names that you would like to assign to each channel, and determines the number of channels.
+`PWM_CHANNEL_PINS` lists the corresponding output pins that the channels will be connected to.
+The number of entries in `PWM_CHANNEL_PINS` must exactly match the number of entries in `PWM_CHANNEL_NAMES`.
+
+### Usage
+
+#### Set
+`mosquitto_pub -t home/OpenMQTTGateway_MEGA/commands/MQTTtoPWM/set -m '{"r":0.5,"g":0.2,"b":1,"fade":10.0}'`
+
+This example sets new values for the channels named `r`, `g`, and `b`.
+These channels will transition from their current values to the new values over 10s.
+
+#### Calibrate
+Calibration allows that min and max levels to be configured for each channel, so that the full 0-1 range of values
+that can be specified with the `set` command actually do things.
+
+`mosquitto_pub -t home/OpenMQTTGateway_MEGA/commands/MQTTtoPWM/calibrate -m '{"min-r":0.01,"max-r":1.0,"gamma-r":2.5}'`
+
+This example calibrates the channel named `r`.
+After this calibration, if you set the `r` channel to 0.0, it will be remapped to 0.01 internally.
+Also, the gamma curve for this channel will be set to 2.5.
+This means that input values are raised to the power 2.5 internally.
+This can be used to improve the linearity of inputs.

main/User_config.h

@@ -229,6 +229,7 @@ uint8_t wifiProtocol = 0; // default mode, automatic selection
 //#define ZboardM5STICKC "M5StickC"
 //#define ZboardM5STACK  "ZboardM5STACK"
 //#define ZradioCC1101   "CC1101"   //ESP8266, ESP32
+//#define ZactuatorPWM   "PWM"      //ESP8266, ESP32
 
 /*-------------DEFINE YOUR MQTT ADVANCED PARAMETERS BELOW----------------*/
 #ifndef version_Topic

main/ZactuatorPWM.ino

@@ -0,0 +1,261 @@
+/*
+  OpenMQTTGateway - ESP32, ESP8266 or Arduino program for home automation
+
+  This actuator enables control over the PWM outputs of microcontrollers.
+
+  It uses the highest resolution duty cycles available, to try to
+  give good control over LEDs, particularly at low brightness settings.
+
+  It supports different gamma curves to try to give good perceptually
+  linear results when used to control LEDs, and it supports calibration
+  of the min and max levels for each channel.
+
+  It supports as many channels as the micro-controller can output PWM
+  signals for.  Each channel can be named in the config header.
+
+  Supported MQTT topics...
+
+  ".../commands/MQTTtoPWM/set" : Set the state of one or more channels.
+  All values are floating point.
+ {
+    "r"  : 0.0 - 1.0,
+    "g"  : 0.0 - 1.0,
+    "b"  : 0.0 - 1.0,
+    "w0" : 0.0 - 1.0,
+    "w1" : 0.0 - 1.0,
+
+    "fade" : <fade time in seconds>
+  }
+
+  ".../commands/MQTTtoPWM/calibrate" : Set calibration data
+  All values support floating point for greater precision.
+  It can be convenient to use the 'retain' feature of MQTT to
+  store calibration data.
+  Gamma is a power value that is used help make the intensity
+  curves respond in a more perceptually linear way.
+  If you would like the values to remain linear, set the gamma
+  values to 1.0
+  Min and max set the levels that 0 and 1 will correspond to.
+  Be aware the the min and max values are in the current gamma space
+  before the conversion to linear - so if you change the gamma level
+  then you will probably need to tune the min and max values again
+ {
+    "gamma-r" : 0.5 - 4.0,
+    "min-r"   : 0.0 - 1.0,
+    "max-r"   : 0.0 - 1.0,
+
+    "gamma-g" : 0.5 - 4.0,
+    etc...
+  }
+
+    Copyright: (c)
+
+    This file is part of OpenMQTTGateway.
+
+    OpenMQTTGateway is free software: you can redistribute it and/or modify
+    it under the terms of the GNU General Public License as published by
+    the Free Software Foundation, either version 3 of the License, or
+    (at your option) any later version.
+
+    OpenMQTTGateway is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU General Public License for more details.
+
+    You should have received a copy of the GNU General Public License
+    along with this program.  If not, see <http://www.gnu.org/licenses/>.
+*/
+#include "User_config.h"
+
+#ifdef ZactuatorPWM
+
+#  include "config_PWM.h"
+
+static long previousUpdateTime = 0; // milliseconds
+static long currentUpdateTime = 0; // milliseconds
+
+static const char* channelJsonKeys[] = PWM_CHANNEL_NAMES;
+static const int channelPins[] = PWM_CHANNEL_PINS;
+static const int kNumChannels = sizeof(channelPins) / sizeof(int);
+
+// These are all in a perceptually linear colour space, but scaled 0-1
+static float currentValues[kNumChannels] = {};
+static float fadeStartValues[kNumChannels] = {};
+static float targetValues[kNumChannels] = {};
+
+static long fadeStartUpdateTime[kNumChannels] = {}; // milliseconds
+static long fadeEndUpdateTime[kNumChannels] = {}; // milliseconds
+static bool fadeIsComplete = false;
+
+// Calibration data (initialised during setupPWM)
+static float calibrationMinLinear[kNumChannels];
+static float calibrationMaxLinear[kNumChannels];
+static float calibrationGamma[kNumChannels];
+
+#  if defined(ESP32)
+// We use the highest resolution duty cycle mode (16-bit) for ESP32, which
+// gives us good control LEDs at the very dim end of the range.
+static const int kNumDutyCycleBits = 16;
+#  elif defined(ESP8266)
+// ESP8266 has a 10-bit duty cycle, which is better than 8 bits, but still
+// not good enough to give really good dim control over LEDs.
+static const int kNumDutyCycleBits = 10;
+#  else
+// Assume Arduino with 8-bit duty cycle.
+// With an 8-bit duty cycle, it's difficult to get good control over
+// LEDs at the dark end of the range.
+static const int kNumDutyCycleBits = 8;
+#  endif
+
+static const float kUNormToDutyCycle = (float)((1 << kNumDutyCycleBits) - 1);
+
+void setupPWM() {
+  // Setup the PWM channels at the highest frequency we can for full 16-bit
+  // duty cycle control.  These channels will be assigned to the
+  // associated output pins.
+
+  // PWM outputs vary the light intensity linearly when used to control
+  // LEDs. But our eyes don't perceive actual linear changes as linear.
+  // This manifests as a problem when trying to have fine control
+  // over LEDs at very low levels.
+  // Using an 8-bit duty cycle for example only allows for 256 different
+  // linear levels of brightness.  Perceptually, the difference in
+  // brightness between levels 1 and 2 is very large - so to get fine
+  // control at dark levels, it's important that we use as high
+  // resolution PWM as we can.
+  for (int i = 0; i < kNumChannels; ++i) {
+#  if defined(ESP32)
+    // Configure the pin for PWM output.
+    // I think this is the fastest frequency that allows for a 16-bit
+    // duty cycle on an ESP32
+    ledcSetup(i, 625.0, kNumDutyCycleBits);
+    ledcAttachPin(channelPins[i], i);
+#  endif
+    calibrationMinLinear[i] = 0.f;
+    calibrationMaxLinear[i] = 1.f;
+    calibrationGamma[i] = PWM_DEFAULT_GAMMA;
+  }
+
+  Log.trace(F("ZactuatorPWM setup done " CR));
+}
+
+// This applies a power curve to the input to try to make the inputs
+// be 'perceptually linear', as opposed to actually linear.
+static float perceptualToLinear(float perceptual, int channelIdx) {
+  return pow(perceptual, calibrationGamma[channelIdx]);
+}
+
+// If we're currently fading between states, then update those states
+void PWMLoop() {
+  previousUpdateTime = currentUpdateTime;
+  currentUpdateTime = millis();
+
+  if (fadeIsComplete) {
+    return;
+  }
+
+  fadeIsComplete = true; //< If any channel isn't finished, we'll set this to false
+  for (int i = 0; i < kNumChannels; ++i) {
+    // Calculate our lerp value through the current fade
+    long totalFadeDuration = fadeEndUpdateTime[i] - fadeStartUpdateTime[i];
+    float fadeLerpValue = 1.f;
+    if (totalFadeDuration > 0) {
+      fadeLerpValue = (float)(currentUpdateTime - fadeStartUpdateTime[i]) / (float)totalFadeDuration;
+    }
+    if (fadeLerpValue >= 1.f) {
+      currentValues[i] = targetValues[i];
+    } else {
+      currentValues[i] = ((targetValues[i] - fadeStartValues[i]) * fadeLerpValue) + fadeStartValues[i];
+      fadeIsComplete = false;
+    }
+  }
+
+  // Now convert these perceptually linear values into actually linear values
+  // and set the appropriate duty cycle for the outputs.
+  for (int i = 0; i < kNumChannels; ++i) {
+    float linear = perceptualToLinear(currentValues[i], i);
+
+    // We always treat zero as zero so that it's truly off, regardless of the calibration data.
+    if (linear > 0.f) {
+      // Remap according to the calibration
+      linear = (linear * (calibrationMaxLinear[i] - calibrationMinLinear[i])) + calibrationMinLinear[i];
+    }
+
+    long dutyCycle = (long)(linear * kUNormToDutyCycle);
+#  if defined(ESP32)
+    ledcWrite(i, dutyCycle);
+#  else
+    analogWrite(channelPins[i], dutyCycle);
+#  endif
+    //Log.notice(F("Setting channel %d : %d" CR),i,dutyCycle);
+  }
+}
+
+boolean PWMtoMQTT() {
+  return false;
+}
+
+#  ifdef jsonReceiving
+void MQTTtoPWM(char* topicOri, JsonObject& jsonData) {
+  if (cmpToMainTopic(topicOri, subjectMQTTtoPWMset)) {
+    Log.trace(F("MQTTtoPWM JSON analysis" CR));
+    // Parse the target value for each channel
+    int modifiedChannelBits = 0;
+    for (int i = 0; i < kNumChannels; ++i) {
+      fadeStartValues[i] = currentValues[i];
+      JsonVariant value = jsonData[channelJsonKeys[i]];
+      if (value.success()) {
+        float targetValue = value.as<float>();
+        targetValue = min(targetValue, 1.f);
+        targetValue = max(targetValue, 0.f);
+        targetValues[i] = targetValue;
+
+        // Initially configure as an instantaneous change....
+        fadeStartUpdateTime[i] = currentUpdateTime;
+        fadeEndUpdateTime[i] = currentUpdateTime;
+
+        modifiedChannelBits |= (1 << i);
+      }
+    }
+    // ...unless there is a "fade" value in the JSON
+    JsonVariant fade = jsonData["fade"];
+    if (fade.success()) {
+      // "fade" json value is in seconds. Convert to milliseconds
+      long endUpdateTime = currentUpdateTime + (long)(fade.as<float>() * (1000.f));
+      // Set the fadeEndUpdateTime for the channels that were modified in the JSON
+      for (int i = 0; i < kNumChannels; ++i) {
+        if (modifiedChannelBits & (1 << i)) {
+          fadeEndUpdateTime[i] = endUpdateTime;
+        }
+      }
+    }
+    fadeIsComplete = false; // The values will start to change during PWMLoop
+  } else if (cmpToMainTopic(topicOri, subjectMQTTtoPWMcalibrate)) {
+    // Read the optional calibration data for each channel
+    for (int i = 0; i < kNumChannels; ++i) {
+      char key[64];
+      snprintf(key, sizeof(key), "gamma-%s", channelJsonKeys[i]);
+      JsonVariant value = jsonData[key];
+      if (value.success()) {
+        float gamma = value.as<float>();
+        // Sanity check
+        gamma = min(gamma, 4.f);
+        gamma = max(gamma, 0.5f);
+        calibrationGamma[i] = gamma;
+      }
+      snprintf(key, sizeof(key), "min-%s", channelJsonKeys[i]);
+      value = jsonData[key];
+      if (value.success()) {
+        calibrationMinLinear[i] = perceptualToLinear(value.as<float>(), i);
+      }
+      snprintf(key, sizeof(key), "max-%s", channelJsonKeys[i]);
+      value = jsonData[key];
+      if (value.success()) {
+        calibrationMaxLinear[i] = perceptualToLinear(value.as<float>(), i);
+      }
+    }
+  }
+}
+#  endif
+
+#endif

main/config_PWM.h

@@ -0,0 +1,52 @@
+/*
+  OpenMQTTGateway  - ESP8266 or Arduino program for home automation
+
+   This files enables you to set your parameters for the PWM actuator
+
+    Copyright: (c)
+
+    This file is part of OpenMQTTGateway.
+
+    OpenMQTTGateway is free software: you can redistribute it and/or modify
+    it under the terms of the GNU General Public License as published by
+    the Free Software Foundation, either version 3 of the License, or
+    (at your option) any later version.
+
+    OpenMQTTGateway is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU General Public License for more details.
+
+    You should have received a copy of the GNU General Public License
+    along with this program.  If not, see <http://www.gnu.org/licenses/>.
+*/
+
+/*-------------------PWM topics & parameters----------------------*/
+
+// PWM MQTT Subjects
+#define subjectMQTTtoPWM          "/commands/MQTTtoPWM"
+#define subjectMQTTtoPWMset       subjectMQTTtoPWM "/set" //set channel(s) with JSON struct {"r":0-1,"g":0-1,"b":0-1,"w0":0-1,"w0":0-1,"fade":<fade time in seconds>}
+#define subjectMQTTtoPWMcalibrate subjectMQTTtoPWM "/calibrate" //set calibration data JSON struct {"gamma-r":0.5-4.0,"min-r":0-1,"max-r":0-1 etc. }
+
+// Edit the following, or declare them in the configuration env, to declare
+// the channel names and corresponding output pins
+#ifndef PWM_CHANNEL_NAMES
+#  define PWM_CHANNEL_NAMES \
+    { "r", "g", "b", "w0", "w1" }
+#endif
+#ifndef PWM_CHANNEL_PINS
+#  define PWM_CHANNEL_PINS \
+    { 25, 33, 32, 23, 22 }
+#endif
+
+// Gamma defines a power curve that is applied to convert the input values
+// to the linear PWM outputs.
+// For LED control, the gamma can be used to make the inputs be more
+// perceptually linear.
+// For controlling other things that require strict linear control, set
+// the gamma to 1 and leave it alone.
+// This just defines the default gamma to use for all channels.
+// The gamma for each channel can be modified using the calibrate MQTT topic.
+#ifndef PWM_DEFAULT_GAMMA
+#  define PWM_DEFAULT_GAMMA 2.2f
+#endif

main/main.ino

@@ -125,6 +125,9 @@ unsigned long timer_sys_measures = 0;
 #ifdef ZactuatorFASTLED
 #  include "config_FASTLED.h"
 #endif
+#ifdef ZactuatorPWM
+#  include "config_PWM.h"
+#endif
 #if defined(ZboardM5STICKC) || defined(ZboardM5STACK)
 #  include "config_M5.h"
 #endif
@@ -630,6 +633,9 @@ void setup() {
 #ifdef ZactuatorFASTLED
   setupFASTLED();
 #endif
+#ifdef ZactuatorPWM
+  setupPWM();
+#endif
 #ifdef ZsensorDS1820
   setupZsensorDS1820();
 #endif
@@ -1201,6 +1207,9 @@ void loop() {
 #endif
 #ifdef ZactuatorFASTLED
       FASTLEDLoop();
+#endif
+#ifdef ZactuatorPWM
+      PWMLoop();
 #endif
     } else {
       connectMQTT();
@@ -1331,6 +1340,9 @@ void stateMeasures() {
 #  ifdef ZactuatorFASTLED
   modules = modules + ZactuatorFASTLED;
 #  endif
+#  ifdef ZactuatorPWM
+  modules = modules + ZactuatorPWM;
+#  endif
 #  ifdef ZboardM5STACK
   M5.Power.begin();
   SYSdata["m5-batt-level"] = (int8_t)M5.Power.getBatteryLevel();
@@ -1456,6 +1468,9 @@ void receivingMQTT(char* topicOri, char* datacallback) {
 #  ifdef ZactuatorFASTLED
     MQTTtoFASTLED(topicOri, jsondata);
 #  endif
+#  ifdef ZactuatorPWM
+    MQTTtoPWM(topicOri, jsondata);
+#  endif
 #  if defined(ZboardM5STICKC) || defined(ZboardM5STACK)
     MQTTtoM5(topicOri, jsondata);
 #  endif

platformio.ini

@@ -202,6 +202,7 @@ build_flags =
   '-DZgatewayBT="BT"'
   '-DZactuatorONOFF="ONOFF"'
   '-DZactuatorFASTLED="FASTLED"'
+  '-DZactuatorPWM="PWM"'
   '-DZsensorINA226="INA226"'
   '-DZsensorHCSR501="HCSR501"'
   '-DZsensorADC="ADC"'
@@ -418,6 +419,7 @@ build_flags =
   '-DZgatewayPilight="Pilight"'
   '-DZactuatorONOFF="ONOFF"'
   '-DZactuatorFASTLED="FASTLED"'
+  ;'-DZactuatorPWM="PWM"'
   '-DZsensorINA226="INA226"'
   '-DZsensorHCSR501="HCSR501"'
   '-DZsensorHCSR04="HCSR04"'
@@ -693,6 +695,7 @@ build_flags =
   '-DZgatewayBT="BT"'
   '-DZactuatorONOFF="ONOFF"'
   '-DZactuatorFASTLED="FASTLED"'
+  '-DZactuatorPWM="PWM"'
   '-DZsensorINA226="INA226"'
   '-DZsensorHCSR501="HCSR501"'
   '-DZsensorADC="ADC"'