Update doc

docs/blog/2024-07-01_shelly_solar_diverter.md

@@ -46,6 +46,7 @@ A router can also schedule some forced heating of the water tank to ensure the w
 - **Unlimited dimmers (output)**
 - **PID Controller**
 - **Excess sharing amongst dimmers with percentages**
+- **Bypass (force heating)** and automatically turn the dimmer off
 - **Plus all the power of the Shelly ecosystem (rules, schedules, automations, etc)**
 
 This solar diverter based on Shelly devices and a Shelly script can control remotely dimmers and could even be enhanced with relays.
@@ -91,8 +92,7 @@ First the easy part: the temperature sensor and the Shelly Add-On, which has to
   For example, the Shelly EM can be inside the main electric box, and the Shelly Dimmer + Add-On can be in the water tank electric panel, while the contactor and dimmer can be placed neat the water tank.
   They communicate through the network.
 - The dimmer will control the voltage regulator through the `COM` and `0-10V` ports
-- The dimmer will also control the relay or contactor through the `A2` ports
-- The wire from `Dimmer Output` to `Dimmer S1` is to set the switch mode to invert and make the dimmer detect when the contactor is OFF or ON and respectively disable or enable the dimming.
+- The Shelly EM will control the relay or contactor through the `A2` ports.
 - The B clamp around the wire going from the voltage regulator to the water tank is to measure the current going through the water tank resistance is optional and for information purposes only.
 - The A clamp should be put around the main phase entering the house
 - The relay / contactor is optional and is used to schedule some forced heating of the water tank to ensure the water reaches a safe temperature, and consequently bypass the dimmed voltage.
@@ -122,14 +122,16 @@ Also, this central place allows to control the 1, 2 or more dimmers remotely.
 
 - Make sure the switch (input) are enabled and inverted. S1 should replicate the inverse state of the relay / contactor, so that when you activate the contactor through the Dimmer output remotely, the dimmer will deactivate itself.
 - Set static IP addresses
+- Use the min/max settings to remap the 0-100% to match the voltage regulator.
+  I noticed that the LSA allows a wider range but the one from LCTC has to be re-mapped from 10-80%
 
 ### Shelly Pro EM 50 Setup
 
 - Set static IP address
 - Make sure to place the A clamp around the main phase entering the house in the right direction
 - Add the `Shelly Solar Diverter` to the Shelly Pro EM
 - Configure the settings in the `CONFIG` object
-- Start teh script
+- Start the script
 
 ## How to use
 
@@ -144,33 +146,53 @@ const CONFIG = {
   // Grid Power Read Interval (s)
   READ_INTERVAL_S: 1,
   PID: {
+    // Reverse
+    REVERSE: false,
+    // Proportional Mode:
+    // - "error" (proportional on error),
+    // - "input" (proportional on measurement),
+    // - "both" (proportional on 50% error and 50% measurement)
+    P_MODE: "input",
+    // Derivative Mode:
+    // - "error" (derivative on error),
+    // - "input" (derivative on measurement)
+    D_MODE: "error",
+    // Integral Correction
+    // - "off" (integral sum not clamped),
+    // - "clamp" (integral sum not clamped to OUT_MIN and OUT_MAX),
+    // - "advanced" (advanced anti-windup algorithm)
+    IC_MODE: "advanced",
     // Target Grid Power (W)
-    SET_POINT: 0,
-    // Number of Watts allowed to be above or below the set point (W)
-    SET_POINT_DELTA: 2,
+    SETPOINT: 0,
     // PID Proportional Gain
-    KP: 0.8,
+    KP: 0.3,
     // PID Integral Gain
-    KI: 0,
+    KI: 0.3,
     // PID Derivative Gain
-    KD: 0.8,
-    // PID Output Minimum Clamp (W)
-    OUTPUT_MIN: 0,
+    KD: 0.1,
+    // Output Minimum (W)
+    OUT_MIN: -10000,
+    // Output Maximum (W)
+    OUT_MAX: 10000,
   },
   DIMMERS: {
-    "192.168.125.93": {
+    "192.168.125.98": {
       // Resistance (in Ohm) of the load connecter to the dimmer + voltage regulator
       // 0 will disable the dimmer
       RESISTANCE: 24,
       // Percentage of the remaining excess power that will be assigned to this dimmer
       // The remaining percentage will be given to the next dimmers
       RESERVED_EXCESS_PERCENT: 100,
+      // Set whether the Shelly EM with this script will be used to control the bypass relay to force a heating
+      // When set to true, if you activate remotely the bypass to force a heating, then the script will tur the dimmer off
+      BYPASS_CONTROLLED_BY_EM: true
     },
     "192.168.125.97": {
       RESISTANCE: 0,
       RESERVED_EXCESS_PERCENT: 100,
-    },
-  },
+      BYPASS_CONTROLLED_BY_EM: false
+    }
+  }
 };
 ```
 
@@ -240,51 +262,71 @@ http://192.168.125.92/script/1/status
 
 ```json
 {
+  "config": {
+    "DEBUG": 2,
+    "READ_INTERVAL_S": 1,
+    "PID": {
+      "REVERSE": false,
+      "P_MODE": "input",
+      "D_MODE": "error",
+      "IC_MODE": "advanced",
+      "SETPOINT": 0,
+      "KP": 0.3,
+      "KI": 0.3,
+      "KD": 0.1,
+      "OUT_MIN": -10000,
+      "OUT_MAX": 10000
+    },
+    "DIMMERS": {
+      "192.168.125.98": {
+        "RESISTANCE": 24,
+        "RESERVED_EXCESS_PERCENT": 100
+      },
+      "192.168.125.97": {
+        "RESISTANCE": 0,
+        "RESERVED_EXCESS_PERCENT": 100
+      }
+    }
+  },
   "pid": {
     "input": 0,
     "output": 0,
     "error": 0,
     "pTerm": 0,
     "iTerm": 0,
-    "dTerm": 0
+    "dTerm": 0,
+    "sum": 0
   },
   "divert": {
-    "voltage": 237.9,
-    "gridPower": 0,
-    "divertPower": 173.76,
+    "lastTime": 1720281498691.629,
     "dimmers": {
-      "192.168.125.93": {
-        "divertPower": 86.88,
-        "nominalPower": 2358.18375,
-        "dutyCycle": 0.03684191276,
-        "powerFactor": 0.19194247253,
-        "dimmedVoltage": 45.66311421705,
-        "current": 1.90262975904,
-        "apparentPower": 452.63561967657,
-        "thdi": 5.11302248812,
-        "rpc": "pending"
-      },
-      "192.168.125.97": {
-        "divertPower": 86.88,
-        "nominalPower": 2358.18375,
-        "dutyCycle": 0.03684191276,
-        "powerFactor": 0.19194247253,
-        "dimmedVoltage": 45.66311421705,
-        "current": 1.90262975904,
-        "apparentPower": 452.63561967657,
-        "thdi": 5.11302248812,
-        "rpc": "pending"
+      "192.168.125.98": {
+        "divertPower": 0,
+        "maximumPower": 2263.98374999999,
+        "dutyCycle": 0,
+        "powerFactor": 0,
+        "dimmedVoltage": 0,
+        "current": 0,
+        "apparentPower": 0,
+        "thdi": 0,
+        "rpc": "success"
       }
     }
   }
 }
 ```
 
+### PID Control and Tuning
+
+The script uses a complex PID controller that can be tuned to really obtain a very good routing precision.
+The algorithm used and default parameters are the same as in the YaSolr project.
+You will find a lot of information in the [YaSolR manual](/manual#dashboard--pid-controller).
+
 ## Demo
 
 Here is the view of the Shelly device websites while the grid power is changing.
 
-[![Shelly Solar Diverter Demo](http://img.youtube.com/vi/he5qPJx8_R4/0.jpg)](http://www.youtube.com/watch?v=he5qPJx8_R4 "Shelly Solar Diverter Demo")
+[![Shelly Solar Diverter Demo](http://img.youtube.com/vi/qDV0VZnWXWU/0.jpg)](http://www.youtube.com/watch?v=qDV0VZnWXWU "Shelly Solar Diverter Demo")
 
 Here is a PoC box I am using for my testing with all the components wired. I am still waiting for the dimmer gen 3 which works in **current sourcing** mode, but everything else is working.