Skip to content

Commit

Permalink
Enhancing dimmer output function block (#75)
Browse files Browse the repository at this point in the history 
FB_OUTPUT_DIMMER_MQTT drastically enhanced
  • Loading branch information
@MichielVanwelsenaere
MichielVanwelsenaere authored Nov 12, 2020
1 parent 68c6166 commit ce7724a
Show file tree
Hide file tree
Showing 8 changed files with 537 additions and 291 deletions.
2 changes: 1 addition & 1 deletion docs/FunctionBlocks/FB_INPUT_PUSHBUTTON_DIMMER_MQTT.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,7 @@ METHOD(S)
- `Qos_Dimm`: datatype *SD_MQTT.QoS*, MQTT QoS of the DIM MQTT events.
- `Delta_Dimm`: datatype *INT*, resolution of the MQTT DIM events. For example: specifying value *5* will configure the FB to only emit an MQTT event when the DIM output differs *5* or more than its previous value. Note that the last value of output DIM (when input `PB` becomes low again) is always published. Even if the resolution delta hasn't been reached yet. This way the last DIM value published through MQTT is always synchronized with the DIM output of the FB.

- ConfigureDimmer: configures the dimmer with your prefered configurations, an overview of the parameters and their default values:
- ConfigureFunctionBlock: configures the dimmer with your prefered configurations, an overview of the parameters and their default values:
- `T_Debounce`: debounce time for input PB, defaults to 10ms.
- `T_Reconfig`: reconfiguration time, defaults to 10S.
- `T_On_Max`: start limitation, defaults to 0ms.
Expand Down
71 changes: 49 additions & 22 deletions docs/FunctionBlocks/FB_OUTPUT_DIMMER_MQTT.md
View file
Original file line number Diff line number Diff line change
@@ -1,15 +1,14 @@
## FB_OUTPUT_DIMMER_MQTT

### __General__
Can be controlled using pulses from [FB_INPUT_PUSHBUTTON_MQTT](./FB_INPUT_PUSHBUTTON_MQTT.md), maintains output state through powercycles.
Can be controlled using pulses from [FB_INPUT_PUSHBUTTON_MQTT](./FB_INPUT_PUSHBUTTON_MQTT.md), maintains output state through powercycles. Takes a 0-255 byte value as input -as FB input or MQTT value-. Byte input value is linearly scaled to a word datatype value with a range from 0-32767. Output linear scaled range can be configured to be different from 0-32767 if desired.

### __Block diagram__

<img src="../_img/FB_OUTPUT_DIMMER_MQTT.svg" width="350">

INPUT(S)
- SINGLE: input to connect to one or multiple `SINGLE` from one or multiple [FB_INPUT_PUSHBUTTON_MQTT](./FB_INPUT_PUSHBUTTON_MQTT.md).
- DOUBLE: input to connect to one or multiple `DOUBLE` from one or multiple [FB_INPUT_PUSHBUTTON_MQTT](./FB_INPUT_PUSHBUTTON_MQTT.md).
- LONG: input to connect to one or multiple `LONG` from one or multiple [FB_INPUT_PUSHBUTTON_MQTT](./FB_INPUT_PUSHBUTTON_MQTT.md).
- P_LONG: input to connect to one or multiple `P_LONG` from one or multiple [FB_INPUT_PUSHBUTTON_MQTT](./FB_INPUT_PUSHBUTTON_MQTT.md).
- PRIO_HIGH: when high the output `Q` is set to high with a maximum brightness, has priority over the other inputs.
Expand All @@ -18,12 +17,10 @@ INPUT(S)
- SET: input for switching output DIM to input VAL value.
- RST: input to switch of the output.

INPUT/OUTPUT(S)
- OUT: dimmer value, byte datatype.

OUTPUT(S)
- Q: output.
- DBL: double-click output.
- Q: output, bool datatype.
- OUT: dimmer value, word datatype.
- Q_OUT: follows 'OUT' when Q is high. Equal to 0 when Q is low.

METHOD(S)
- InitMQTT: enables MQTT events on the FB, an overview of the parameters:
Expand All @@ -34,29 +31,29 @@ METHOD(S)
- `Qos_Dimm`: datatype *SD_MQTT.QoS*, MQTT QoS of the DIM MQTT events.
- `Delta_Dimm`: datatype *INT*, resolution of the MQTT OUT events. For example: specifying value *5* will configure the FB to only emit an MQTT event when the OUT output differs *5* or more than its previous value. Note that the last value of output OUT (when input `P_LONG` becomes low again) is always published. Even if the resolution delta hasn't been reached yet. This way the last OUT value published through MQTT is always synchronized with the OUT output of the FB.

- ConfigureDimmer: configures the dimmer with your prefered configurations, an overview of the parameters and their default values:
- ConfigureFunctionBlock: configures the dimmer with your prefered configurations, an overview of the parameters and their default values:
- `T_Debounce`: debounce time for input PB, defaults to 10ms.
- `T_Reconfig`: reconfiguration time, defaults to 10S.
- `T_On_Max`: start limitation, defaults to 0ms.
- `T_Dimm_Start`: reaction time to dim, defaults to 400ms.
- `T_Dimm`: time for a dimming ramps, defaults to 3s.
- `Min_On`: minimum value of output OUT at startup, defaults to 50.
- `Max_On`: maximum value of output OUT at startup, defaults to 255.
- `Soft_Dimm`: if TRUE dimming begins after ON and at 0.
- `Dbl_Toggle`: if TRUE the output DBL is inverted at each double-click, defaults to FALSE.
- `Soft_Dimm`: if TRUE dimming begins after ON and at 0, defaults to TRUE.
- `Rst_Out`: if input Rst is TRUE, ouput OUT is set to 0, defaults to FALSE.
- `OUT_LinearScaleMin`: Lower bound value used for linear scaleout output OUT from datatype byte to word. Defaults to 0.
- `OUT_LinearScaleMax`: Upper bound value used for linear scaleout output OUT from datatype byte to word. Defaults to 32767.

- PublishReceived: callback method called by the callbackcollector when a message is received on the subscribed topic by the callbackcollector.
### __Function Block Behaviour__
The following table shows the operating status of the dimmer:

| SINGLE/DOUBLE/LONG/P_LONG | SET | RST | Q | DIR (*) | DBL | OUT |
|:-------------|:------------------|:------------------|:------------------|:------------------|:------------------|:------------------|
| SINGLE | 0 | 0 | NOT Q | OUT < 127 | - | LIMIT(MIN_ON,OUT,MAX_ON)
| DOUBLE | 0 | 0 | - | - | TOG PULSE |
| LONG/P_LONG | 0 | 0 | ON | NOT DIR | - | Ramp up or down depending on DIR, start at 0 when soft_dimm = TRUE and Q = 0, reverse direction if 0 or 255 is reached
| 0 | 1 | 0 | ON | OUT < 127 | - | VAL
| 0 | 0 | 1 | OFF | UP | OFF | 0 when RST_OUT = TRUE
| SINGLE/LONG/P_LONG | SET | RST | Q | DIR (*) | OUT | Q_OUT |
|:-------------|:------------------|:------------------|:------------------|:------------------|:---------------------------------------|:------------------|
| SINGLE | 0 | 0 | NOT Q | OUT < 127 | LIMIT(MIN_ON,OUT,MAX_ON) | Q * OUT
| LONG/P_LONG | 0 | 0 | ON | NOT DIR | Ramp up or down depending on DIR, start at 0 when soft_dimm = TRUE and Q = 0, reverse direction if 0 or 255 is reached | OUT
| 0 | 1 | 0 | ON | OUT < 127 | VAL | OUT
| 0 | 0 | 1 | OFF | UP | 0 when RST_OUT = TRUE | 0

(*): DIR refers to the direction of the dimmer output `OUT`, indicating whether the dimmer output value changes up-or downwards.

Expand All @@ -68,7 +65,6 @@ Requires method call `InitMQTT` to enable MQTT capabilities.
| Event | Description | MQTT payload | QoS | Retain flag | Published on startup |
|:-------------|:------------------|:------------------|:------------------|:--------------------------|:--------------------------|
| **Output changes: Q** | A change is detected on output `Q`. (*) | `TRUE/FALSE` | 2 | `TRUE` | no
| **Output changes: DBL** | A change is detected on output `DBL`. (*) | `TRUE/FALSE` | 2 | `TRUE` | no
| **Output changes: OUT** | A change is detected on output `OUT`. (*) | `0-255` | configured in method call `InitMQTT` | `TRUE` | no

(*): MQTT publish topic is a concatenation of the publish prefix variable, the function block name and the name of the output.
Expand Down Expand Up @@ -108,17 +104,48 @@ FB_AO_DIMMER_001.InitMQTT(MQTTPublishPrefix:= ADR(MqttPubDimmerPrefix), (* p
```
The MQTT publish topic in this code example will be `WAGO-PFC200/Out/Dimmers/FB_AO_DIMMER_001` (MQTTPubSwitchPrefix variable + function block name). The subscription topic will be `WAGO-PFC200/In/Dimmers/FB_AO_DIMMER_001` (MQTTSubSwitchPrefix variable + function block name).

- checking for events to switch the digital output (cyclic):
- ConfigureFunctionBlock (called once during startup):
```
FB_AO_DIMMER_001.ConfigureFunctionBlock(
T_Debounce:=T#10MS,
T_Reconfig:=T#10S,
T_On_Max:=T#0S,
T_Dimm_Start:=T#400MS,
T_Dimm:=T#3S,
Min_On:=50,
Max_On:=255,
Soft_Dimm:=TRUE,
Rst_Out:=FALSE,
OUT_LinearScaleMin:=11000,
OUT_LinearScaleMax:=32767
);
```
The dimmer behavior in the example above is adjusted to start dimming from '11000' instead of the default '0' value. This can be important as different dimming devices will have different lower bound 'on' voltages. In addition, depending on your PLC device, the maximum out value will differ. Note that this method only requires a call when it's desired to change the default behavior characteristics.

- checking for events to switch the digital output (cyclic), example 1:
```
FB_AO_DIMMER_001(SINGLE:= FB_DI_PB_041.SINGLE, (* for toggling the output Q *)
DOUBLE:= FB_DI_PB_041.DOUBLE, (* for controlling the output DBL *)
LONG:= FB_DI_PB_041.LONG, (* for controlling the dimmer output OUT *)
P_LONG:= FB_DI_PB_041.P_LONG, (* for controlling the dimmer output OUT *)
Q=> DO_001, (* couple the function block to the physical digital output *)
OUT:= AO_001 (* couple the function block to the physical anolog output *)
OUT:= AO_001, (* couple the function block to the physical anolog output *)
VAL:= 255, (* value to set on output OUT when input SET is high *)
SET:= FB_DI_PB_041.DOUBLE (* when high, VAL is set on output OUT *)
);
```
The above illustrates an integration with [FB_INPUT_PUSHBUTTON_MQTT](./FB_INPUT_PUSHBUTTON_MQTT.md). The dimmer module in this example has a 'on/off' digital input that is wired to the 'Q' output of the dimmer & a 0/1-10V analog input that is wired to the 'OUT' output of the dimmer.

- checking for events to switch the digital output (cyclic), example 2:
```
FB_AO_DIMMER_001(SINGLE:= FB_DI_PB_041.SINGLE, (* for toggling the output Q *)
LONG:= FB_DI_PB_041.LONG, (* for controlling the dimmer output OUT *)
P_LONG:= FB_DI_PB_041.P_LONG, (* for controlling the dimmer output OUT *)
Q_OUT:= AO_001, (* couple the function block to the physical anolog output *)
VAL:= 255, (* value to set on output OUT when input SET is high *)
SET:= FB_DI_PB_041.DOUBLE (* when high, VAL is set on output OUT *)
);
```
The above illustrates an integration with [FB_INPUT_PUSHBUTTON_MQTT](./FB_INPUT_PUSHBUTTON_MQTT.md) as well.
The above illustrates an integration with [FB_INPUT_PUSHBUTTON_MQTT](./FB_INPUT_PUSHBUTTON_MQTT.md). The dimmer module in this example has a 0/1-10V analog input that is wired to the 'Q_OUT' output of the dimmer.

### __Home Assistant YAML__
To integrate with Home Assistant use the YAML code below in your [MQTT lights](https://www.home-assistant.io/components/light.mqtt/) config:
Expand Down
4 changes: 2 additions & 2 deletions docs/FunctionBlocks/FB_RS485_BUSCONTROLLER.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,8 +14,8 @@ METHOD(S)
- Init: configures the buscontroller, an overview of the parameters:
- `StartupDelay`: datatype *TIME*, amount of time that should be waited on PLC startup before using the RS485 bus, can prevent errors due to RS485 devices not booted up yet.
- `SilenceTime`: datatype *TIME*, the silence time between two requests. Typically 10-20ms.
- SetBusOccupied: can be called by any RS485 to indicate that it is using the RS485 bus.
- ReleaseBus: can be called by any RS485 to indicate that it is done using the RS485 bus.
- SetBusOccupied: can be called by any RS485 function block to indicate that it is using the RS485 bus.
- ReleaseBus: can be called by any RS485 function block to indicate that it is done using the RS485 bus.

### __Code example__

Expand Down
2 changes: 1 addition & 1 deletion docs/_drawio/FB_OUTPUT_DIMMER_MQTT.drawio
View file
Original file line number Diff line number Diff line change
@@ -1 +1 @@
<mxfile modified="2020-01-03T10:39:00.192Z" host="Electron" agent="Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) draw.io/12.1.0 Chrome/76.0.3809.139 Electron/6.0.7 Safari/537.36" etag="0oefp2UVIC12bqcXB4wp" version="12.1.0" type="device" pages="1"><diagram id="FV2jeNOKKN2BWKF91_h7" name="Page-1">7Vpbd6I6FP41PnqWEOLl0Vtt17TTdtqemc6LiyVROSLYgLf59ScJCQQSV9UR2jXMk/DtsBO//e2wk1AD/eVuhO3V/C5wkFczG86uBgY10zQapkV+KLKPEdgxY2CGXYc3SoEn9xcST3J07ToozDSMgsCL3FUWnAS+jyZRBrMxDrbZZtPAy/a6smdIAZ4mtqei310nmsdoGzZS/Bq5s7no2Whwy9IWjTkQzm0n2EoQGNZAHwdBFF8td33kUfIEL/FzVwesycAw8qNjHlj+bIy+3Cybwx/3Y/jfAo4XJqxzLxvbW/M/zAcb7QUD27kboaeVPaH3WxLlGujNo6VH7gxyaYermPepu0Okq546LtEJwhHaSRAf5wgFSxThPWkirIIzLhpTkLpNQ2AJbC7Rn4A2D/ss8Z0yQy44OScQZSpEXfXG9y/PDy/P48HN3d3w2/ju8flZYY/84yhHmOfOfHI9IfwgTIBp4Edc+Aa4DIGm0foHvkuh2YAqhaAoBsH7UkO+06U5S+78wEdZ3o6mCTmZlFZJkiiAGhEJDCPPjtxNdiLQ0cJ7eAhcMpLDIrZyzIbBGk8Qf0pO3Jyj9jt+IhvPUKT4IUzae6nZijYITx9vGvPYY6qAhNLzRWEponi6+Tq6HR6RR2GEgwXqB16AU71MXc/LQSLfPDSlHmgSuWR+73J46ToO7aSnm+dwsPYdOqsNGsUkqkI6UNO0rdGoWVSWwoplKVQC0BEz56l5CpvvurpQqh4edKHJ2qy6NtpnzuCKMvKOitJFu4QpvK2o4rGA2RvH0f1k07dlfbLpu6NJ0aZHiXPcTSYmzbc1XXn0aGjqnOUuzRk2ysRMrmb8l7kJV7YvsEHvVsBksLJFglm/Aq2qLFofLAuxmi5HF2RZ9FcXx+gCGOXpIgp/XLVnjzv8/Au0kNH1Hus/K1/tgTyz577RFUcnv9EzcTzttawNrTbl/+TYKkup1tmVfH7FrXoqas3dunQhr9eGuuyuljaAcSltaDwVpI20p2K1UbV3gsIzvJg2VE9FaQOWow11B+Df7q0ij4rs1VklVvX6cLSUcDwNjzmC+CPDAT+6mDbUnRC2EqpoOGB54bDc3aZzh9fd0Stc4E3wdr1YVP68STkLPfMtpvgp6B0m+rnUG0wriqoXvtaFDiEVP0WJ4sKHkFpRVL3itc4918iLoqBjjUPjLVQUaqk7uH/p0ZNpecNTs3FK1VCf2kvX28c7p8RkL1dMFwBYVDrI2yD66lYsrHVf94yNXds73D60/bAeIuxOKcQMbBwhkyUdRWO1S0ysQKiHcYVAjX7AygTN7i7Mf9sFCYcUZR8uJXeCU8hYJciAXtPRQUojJLF6r62RtBWpc5YbM3UTxy6xiC8LhDkOXWJmdRm5izObwga7laszirL8p4a0QsvAcZVGIVanUShbqVETr9WoUarWqCUOBEwrNgo24g7FPMMGBxgm/du4VDuGz8SUUJnOQZCmXdpS4r6xl1gGEh7PWomtLZn47JU+J9lI+if4TOo/H2h2m0RbBrMa5O0UsR44iahmWV7mUZR2XlXXrLf3X0dVDUeZJ0DacKhr1odxpQPy0ctW3Ql+PhSkFvBnBzmTQnQJgmD2Q1IImwpBhoYgoyiCjjnYKpUhq5VlCIgt9BIYam3BZDTtvUad9WtrY03fOr32MR91n7GeyS1eNKR9lvVMcjj7m+sZxU9B6xnRz6XWM1pRmFUXxblH/XlR/PZJ/2njLVQU6h7pw7ebe1IAfFen1E/7/ldm6qNUeGhvocQv+LQhUXcoWUiub0bXVY0J6BQWkxpfREpZlS4fwfB/</diagram></mxfile>
<mxfile modified="2020-11-06T11:57:45.251Z" host="Electron" agent="Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) draw.io/12.1.0 Chrome/76.0.3809.139 Electron/6.0.7 Safari/537.36" etag="Tx6FzDs-Jx_t0Z0yljWM" version="12.1.0" type="device" pages="1"><diagram id="FV2jeNOKKN2BWKF91_h7" name="Page-1">7Vpbd6I6FP41PvYsIKD4qK1V19S2Vntm2hcXSyIyIrExXjq/foImckm6vAyhc8p5Ej7CTvz2t3d2Eirger5tY2cx7SEXBhVDc7cVcFMxDN2wNfoTIe8M0UF9j3jYdxkWAwP/F2Qge9Fb+S5cphoShALiL9LgGIUhHJMU5mCMNulmExSke104HhSAwdgJRPS775LpHrUtLcY70PemvGddY0/mDm/MgOXUcdEmAYFWBVxjhMj+ar69hkHEHudl/97tB08PA8MwJKe8MH/V2t+682rrx8PI+jmzRjPDumJW1k6wYn+YDZa8cwY2U5/AwcIZR/cb6uYKaE7JPKB3Or10los97xN/C2lXTXFcvBOICdwmIDbONkRzSPA7bXLQDeOMqcbgpG5iF4Aqw6YJ+g+gw9zuHWzHzNALRs4ZRBkCUbfN0cPz8PF5OLrp9nqtp1GvPxwK7NF/TDKEBb4X0usx5QdiCkxQSJjwdZAPgYZe+8c6SqGhWRIKVTEIjksNhm4jill6F6IQpnk7mSbopkJaJClBgSUREccwDBzir9OJQEYL6+ER+XQkH4vYzDC7RCs8huytZOBmDNlH7BAHe5AIdiiTznui2SJqsDx/vLHP9xZjBRwovVwUpiCKQfe+fdc6IY6WBKMZvEYBwrFeJn4QZCAebwGcRBaiIPJpfm8weO67btRJU5bnMFqFbpTVbjQ1gSqQDsQwtSUaNVRFqVWyKDWz0cXrk3Oj1BI8mTGUU5h+NGClYWoLqugriFC89+5fFqKm9peFKC+NUzFaDSLmXH+dckr1bRWVl83IN1eM5kYUNLthHh7TK4/97swsF07IsX5U5fAHdLzJZwl41zNHy6qMWnHKIMsft7bX3+LhL1CDeiPoX73+n7xrdV72/nH6Fk2dncBTvjwvC0vdq4vV0tf2r1Ad2TmV0Fk7qkpoO98SWq6KskV9lmWgX1iy2UfsKFIF70etKqqCKv5t3CmYmv8TyyqzwJpN7o6a4I5B65Tdoq/pjs8ulHRxQbOrcsvpDksvzh2mv13Xe3jVaL9YM7xGb53ZrPRbg8C6uG7NzmGiJVWz2KGnvOYxqTTKXvIe1ph/KAzBjiJZ8H6UiqLsFa8J8soXEkuqhAEKyRdinXX3cN8u68xe5I6U1B1infU4KrNDwGeXWvXjqZNg3wm9DzlLuCgPgqz0ObXFF64JgnQJQboqgqS765/JkAnSDAG+4VMAQ7UNGLcnzRdSX73U1ubkrd60T/lm5GvPvpfvMmdn3xw2mc8dc16zr1QaRsmlYWXz9oXCEOwokgXvR6koxNX941P3gZYB38XEWpIqoF5cFSB1ibiq3rmk0213SusTqzifaKBrfnvu3P20PLN1/zq7n5In6bSq7FT/K5/pCxqQKOXkM/0iC3apLNRMqZn58ySGPudMH1w6pWZP9AVDCs/z6W38Yfe+efx9PGj9Bg==</diagram></mxfile>
Loading

0 comments on commit ce7724a

Please sign in to comment.