pid cal

docs/index.md

@@ -46,7 +46,7 @@ _YaSolR_ is built with this vision in mind:
   - JSY reading speed is increased to its maximum to give a fast reading
   - RMT peripheral is used for DS18 readings
   - PID Controller for dimmers with customizable Kp, KI, kd factors
-  - Optimized dimmer library with ZCD pulse width (🚧)
+  - Optimized dimmer library (🚧)
   - Motor Control Pulse Width Modulator (MCPWM) for phase control (🚧)
 
 ## YaS☀️lR Features
@@ -83,8 +83,8 @@ Controls the power sent to the load. Example of supported dimmers:
 | :---------------------------------------------------------------------------------------- | :-------------: | :-----------------------: |
 | **Robodyn 24A** ![Robodyn 24A](./assets/img/hardware/Robodyn_24A.jpeg)                    |       ✅        |            ✅             |
 | **Robodyn 40A** ![Robodyn 40A](./assets/img/hardware/Robodyn_40A.jpeg)                    |       ✅        |            ✅             |
-| **Random SSR** (🚧) ![Random SSR](./assets/img/hardware/Random_SSR.jpeg)                  |       ✅        |            ✅             |
-| **Zero-Cross SSR** ![Zero-Cross SSR](./assets/img/hardware/SSR_40A_DA.jpeg)               |       ❌        |            ✅             |
+| **Random SSR** ![Random SSR](./assets/img/hardware/Random_SSR.jpeg)                       |       ✅        |            ✅             |
+| **Zero-Cross SSR** (🚧) ![Zero-Cross SSR](./assets/img/hardware/SSR_40A_DA.jpeg)          |       ❌        |            ✅             |
 | **Voltage Regulator** (🚧) ![Loncont LSA-H3P50YB](./assets/img/hardware/LSA-H3P50YB.jpeg) |       ✅        |            ✅             |
 
 #### Bypass Relay (optional)
@@ -117,7 +117,7 @@ To monitor the temperature of the water tanker and trigger automatic heating bas
 Each output supports the following features:
 
 - `Automatic Bypass` / `Manual Bypass Control`: Automatically force a heating as needed based on days, hours, temperature range, or control it manually
-- `Automatic Dimmer` (🚧) / `Manual Dimmer Control`: Automatically send the grid excess to the resistive load through the dimmer (or manually control the dimmer yourself if disabled), or control it manually
+- `Automatic Dimmer` / `Manual Dimmer Control`: Automatically send the grid excess to the resistive load through the dimmer (or manually control the dimmer yourself if disabled), or control it manually
 - `Dimmer Duty Limiter`: Set a limit to the dimmer power to avoid routing too much power
 - `Dimmer Temperature Limiter`: Set a limit to the dimmer to stop it when a temperature is reached. This temperature can be different than the temperature used in auto bypass mode.
 - `Statistics`: Harmonic information, power factor, energy, routed power, etc
@@ -196,7 +196,7 @@ Modules can communicate through `UDP` very fast, or through `ESP-Now` when WiFi
 
 - **Setup 1**: measurement module on the main electric panel with a JSY, YaSolR router close to the loads:
 
-  - `Remote JSY-MK-194T with UDP on same WiFi`
+  - `Remote JSY-MK-194T with UDP on same WiFi` (✅)
   - `Remote JSY-MK-194T with ESP-Now` (🚧)
   - `Remote JSY-MK-333 with UDP on same WiFi` (🚧)
   - `Remote JSY-MK-333 with ESP-Now` (🚧)

docs/manual.md

@@ -26,6 +26,7 @@ description: Manual
 - [Dashboard / Hardware](#dashboard--hardware)
 - [Dashboard / Hardware Config](#dashboard--hardware-config)
   - [Resistance Calibration](#resistance-calibration)
+- [Dashboard / PID Controller](#dashboard--pid-controller)
 - [Dashboard / Statistics](#dashboard--statistics)
 - [Important Hardware Information](#important-hardware-information)
   - [Bypass Relay](#bypass-relay)
@@ -433,6 +434,76 @@ Then you just have to report it in the `Hardware Config` page.
 3. **JSY-MK-194T:** If you have a JSY-MK-194T, you can activate the dimmer one by one to 100% and wait for the values to stabilize.
    The router will then display the resistance value in the `Overview` page, thanks to the JSY.
 
+## Dashboard / PID Controller
+
+[![](assets/img/screenshots/pid_tuning.jpeg)](assets/img/screenshots/pid_tuning.jpeg)
+
+**For advanced users only.**
+
+This page allows to tune the PID algorithm used to control the automatic routing.
+Use only if you know what you are doing and know how to tweak a PID controller.
+
+You can change the PID settings at runtime and the effect will appear immediately.
+
+`Real-time PID Data` can be activated to see the PID action in real time in teh graphs.
+
+**If you find better settings, please do not hesitate to share them with the community.**
+
+You are supposed to know how to tune a PID controller.
+If not, please research on Google.
+Here are some basic links to start with, which talks about the code used under the hood:
+
+- [Improving the Beginner’s PID – Introduction](http://brettbeauregard.com/blog/2011/04/improving-the-beginners-pid-introduction/)
+- [Improving the Beginner’s PID – Derivative Kick](http://brettbeauregard.com/blog/2011/04/improving-the-beginners-pid-derivative-kick/)
+- [Introducing Proportional On Measurement](http://brettbeauregard.com/blog/2017/06/introducing-proportional-on-measurement/)
+- [Proportional on Measurement – The Code](http://brettbeauregard.com/blog/2017/06/proportional-on-measurement-the-code/)
+
+**Default Settings**
+
+- Proportional Mode: `On Input`
+- Derivative Mode: `On Error`
+- Integral Correction: `Anti-windup`
+- Setpoint: `0`
+- Kp: `0.3`
+- Ki: `0.3`
+- Kd: `0.1`
+- Output Min: `-10000`
+- Output Max: `10000`
+
+**PID Tuning through WebSocket**
+
+When `Real-time PID Data` is activated, a WebSocket endpoint is available at `/ws/debug/pid` and will stream all the PID data in real time in a `CSV` format when automatic dimmer control is activated.
+You can quickly show then and process then in `bash` with `websocat` by typing for example:
+
+```bash
+❯  websocat ws://192.168.125.123/ws/debug/pid
+pMode,dMode,icMode,rev,setpoint,kp,ki,kd,outMin,outMax,input,output,error,sum,pTerm,iTerm,dTerm
+2,1,2,0,800,0.300,0.400,0.200,-10000,10000,780.645,1109.700,19.355,1104.889,7.217,7.742,4.811
+2,1,2,0,800,0.300,0.400,0.200,-10000,10000,778.620,1114.453,21.380,1114.048,0.607,8.552,0.405
+2,1,2,0,800,0.300,0.400,0.200,-10000,10000,774.128,1126.643,25.872,1125.745,1.347,10.349,0.898
+2,1,2,0,800,0.300,0.400,0.200,-10000,10000,786.127,1125.294,13.873,1127.694,-3.600,5.549,-2.400
+2,1,2,0,800,0.300,0.400,0.200,-10000,10000,804.696,1116.531,-4.696,1120.245,-5.571,-1.878,-3.714
+2,1,2,0,800,0.300,0.400,0.200,-10000,10000,820.285,1104.337,-20.285,1107.455,-4.677,-8.114,-3.118
+2,1,2,0,800,0.300,0.400,0.200,-10000,10000,822.300,1097.527,-22.300,1097.930,-0.605,-8.920,-0.403
+2,1,2,0,800,0.300,0.400,0.200,-10000,10000,808.928,1101.045,-8.928,1098.370,4.012,-3.571,2.674
+2,1,2,0,800,0.300,0.400,0.200,-10000,10000,798.264,1104.396,1.736,1102.264,3.199,0.694,2.133
+2,1,2,0,800,0.300,0.400,0.200,-10000,10000,793.393,1107.342,6.607,1106.368,1.461,2.643,0.974
+2,1,2,0,800,0.300,0.400,0.200,-10000,10000,785.225,1116.361,14.775,1114.728,2.450,5.910,1.634
+2,1,2,0,800,0.300,0.400,0.200,-10000,10000,821.839,1087.686,-21.839,1095.008,-10.984,-8.736,-7.323
+```
+
+You can also stream this data directly to a command-line tool that will plot in real time the graphs.
+Example of such tools:
+
+- https://github.com/keithknott26/datadash
+- https://github.com/cactusdynamics/wesplot
+
+**Demo**
+
+Here is a demo of the real-time PID tuning in action:
+
+[![PID Tuning in YaSolR (Yet Another Solar Router)](http://img.youtube.com/vi/ygSpUxKYlUE/0.jpg)](http://www.youtube.com/watch?v=ygSpUxKYlUE "PID Tuning in YaSolR (Yet Another Solar Router)")
+
 ## Dashboard / Statistics
 
 [![](assets/img/screenshots/statistics.jpeg)](assets/img/screenshots/statistics.jpeg)
@@ -588,3 +659,7 @@ So the router will take whatever is not used by the EV box.
 - **GitHub Discussions**: [https://github.com/mathieucarbou/YaSolR-OSS/discussions](https://github.com/mathieucarbou/YaSolR-OSS/discussions)
 
 - **GitHub Issues**: [https://github.com/mathieucarbou/YaSolR-OSS/issues](https://github.com/mathieucarbou/YaSolR-OSS/issues)
+
+```
+
+```