3 | 
4 | 
5 |
6 | This CoDeSys 3.5 project is built for home automation purposes. The goal of the approach is to perform any critical operations like reading inputs, switching light, controlling sunscreens, etc. Inside the PLC itself and make use of MQTT events to send events to an MQTT broker. Using MQTT subscriptions it's possible to send commands to the PLC to control -for example- outputs.
7 |
8 | The purpose? Redundancy on a software level but also on a hardware level!
9 | - PLCs are very (very) robust controllers: no PC, SoC, etc. is more robust and failure resistant.
10 | - Hardware continuity: Home automation providers often renew their modules every X years, modules aren't sold anymore or a full upgrade is required when something breaks. PLCs models and their modules are sold decades after their initial release date. For an example, check out the Wago 750 series controllers and modules.
11 | - Avoid performing critical operations that should work 24/7 inside a less redundant controller (it will fail sooner or later).
12 | - Keep your wife/girlfriend happy when you're not at home and your Rpi, Odroid, Banana Pi, Pc crashes (running your MQTT broker, OpenHab, Home Assistant, etc.).
13 |
14 | # Supported Runtimes
15 | The project is developed using the IEC 61131-3 standard, there are multiple development environments with their own runtime that support the standard:
16 |
17 | - [CODESYS V3 by 3S-Smart Software Solutions](https://www.codesys.com/)
18 | - [é!COCKPIT by WAGO](https://www.wago.com/global/automation-technology/discover-software/ecockpit-engineering-software) (WAGO PLCs only)
19 | - ...
20 |
21 | # Architecture
22 | Core processing logic is executed in the (robust) PLC. Meaning that events like reading pushbuttons/switches, updating outputs are executed in the PLC software. To enable integration with external software the PLC sends out events to an MQTT broker when events occur (like pushbutton events, outputs that change state). MQTT subscriptions are enabled as well to allow control from the external software to control -for example- outputs.
23 |
24 | 
25 |
26 | # Software Architecture
27 |
28 | More information on the software architecture [here](./docs/SoftwareArchitecture.md).
29 |
30 | # Function blocks
31 |
32 | ## Basic function blocks
33 | Basic function blocks for basic IO events and operations.
34 |
35 | - [FB_INPUT_PUSHBUTTON_MQTT](./docs/FunctionBlocks/FB_INPUT_PUSHBUTTON_MQTT.md)
36 | - [FB_INPUT_PUSHBUTTON_DIMMER_MQTT](./docs/FunctionBlocks/FB_INPUT_PUSHBUTTON_DIMMER_MQTT.md)
37 | - [FB_INPUT_BINARYSENSOR_MQTT](./docs/FunctionBlocks/FB_INPUT_BINARYSENSOR_MQTT.md)
38 | - [FB_OUTPUT_BINARY_MQTT](./docs/FunctionBlocks/FB_OUTPUT_BINARY_MQTT.md)
39 | - [FB_OUTPUT_DIMMER_MQTT](./docs/FunctionBlocks/FB_OUTPUT_DIMMER_MQTT.md)
40 | - [FB_OUTPUT_COVER_MQTT](./docs/FunctionBlocks/FB_OUTPUT_COVER_MQTT.md)
41 | - [FB_OUTPUT_BISTABLE_MQTT](./docs/FunctionBlocks/FB_OUTPUT_BISTABLE_MQTT.md)
42 |
43 | ## Virtual function blocks
44 | Function blocks developed to easily set and get values from the processing logic through MQTT.
45 |
46 | - [FB_VIRTUAL_BOOL_MQTT](./docs/FunctionBlocks/FB_VIRTUAL_BOOL_MQTT.md)
47 | - [FB_VIRTUAL_INT_MQTT](./docs/FunctionBlocks/FB_VIRTUAL_INT_MQTT.md)
48 | - [FB_VIRTUAL_STRING_MQTT](./docs/FunctionBlocks/FB_VIRTUAL_STRING_MQTT.md)
49 | - [FB_VIRTUAL_REAL_MQTT](./docs/FunctionBlocks/FB_VIRTUAL_REAL_MQTT.md)
50 |
51 | ## Modbus RTU over RS485
52 | With many PLCs having a onboard RS485 serial port it is a popular protocol to create a robust Modbus RTU sensor network.
53 |
54 | ### Using Modbus RTU
55 | How to use Modbus RTU differs depending on the PLC/development environment used. The topics belows address the usage of Modbus RTU in several development environments:
56 |
57 | - [Using Modbus RTU with the CODESYS 3S runtime](./docs/RS485/UsingModbusRTU_CODESYS3S.md)
58 | - [Using Modbus RTU with the é!COCKPIT runtime](./docs/RS485/UsingModbusRTU_éCOCKPIT.md)
59 |
60 | ### RS485 function blocks
61 | To translate the byte array received by the modbus device to their actual value and send their values through MQTT the function blocks below have been developed. Note that a specific function block is required for each type of Modbus RTU device.
62 |
63 | - [FB_RS485_EASTRON_SDM220_MQTT](./docs/FunctionBlocks/FB_RS485_EASTRON_SDM220_MQTT.md)
64 | - [FB_RS485_EASTRON_SDM_POWER_MQTT](./docs/FunctionBlocks/FB_RS485_EASTRON_SDM_POWER_MQTT.md)
65 | - [FB_RS485_DUCO_DUCOBOX_MQTT](./docs/FunctionBlocks/FB_RS485_DUCO_DUCOBOX_MQTT.md)
66 | - [FB_RS485_ESERA_1WIRE_GATEWAY_MQTT](./docs/FunctionBlocks/FB_RS485_ESERA_1WIRE_GATEWAY_MQTT.md) & [FB_RS485_ESERA_OWD_MQTT](./docs/FunctionBlocks/FB_RS485_ESERA_OWD_MQTT.md)
67 |
68 | In addition to the above a buscontroller function block ([FB_RS485_BUSCONTROLLER](./docs/FunctionBlocks/FB_RS485_BUSCONTROLLER.md))
69 | is used to control access to the RS485 bus between multiple RS485 device function blocks.
70 |
71 | ## DALI
72 | Control DALI drivers using the WAGO DALI modules (753-647).
73 |
74 | - [FB_OUTPUT_DIMMER_DALI_MQTT](./docs/FunctionBlocks/FB_OUTPUT_DIMMER_DALI_MQTT.md)
75 |
76 | ## DMX
77 | Control DMX drivers.
78 |
79 | - [FB_OUTPUT_DIMMER_DMX_MQTT](./docs/FunctionBlocks/FB_OUTPUT_DIMMER_DMX_MQTT.md)
80 |
81 |
82 | # Additional functionality
83 |
84 | - [MQTT related settings](./docs/AdditionalFunctionality/MQTT_General.md)
85 | - [MQTT Discovery](./docs/AdditionalFunctionality/MQTT_Discovery.md)
86 | - [Controlling Wago PFC user leds](./docs/AdditionalFunctionality/User_leds_éCOCKPIT_runtime.md) (é!COCKPIT runtime)
87 | - [Controlling Wago PFC user leds](./docs/AdditionalFunctionality/User_leds_Codesys3S_runtime.md) (Codesys 3S runtime)
88 |
89 | # FAQ
90 |
91 | - [Contributing guidelines](./docs/CONTRIBUTING.md)
92 | - [Getting started guide](./docs/FAQ/Getting_started_guide_CODESYS_3S.md) (CODESYS 3S runtime)
93 | - [Getting started guide](./docs/FAQ/Getting_started_guide_éCOCKPIT.md) (é!COCKPIT runtime)
94 | - [How-to: adding a new MQTT subscription](./docs/FAQ/Howto_adding_a_new_MQTT_subscription.md)
95 | - [How-to: verifying resource usage on a Wago PFC PLC](./docs/FAQ/Howto_verifying_resource_usage_WagoPFC.md)
96 | - [How-to: updating function blocks to the latest version](./docs/FAQ/Howto_updating_function_blocks.md)
97 | - [RS485: tips and tricks](./docs/FAQ/RS485_tips_and_tricks.md)
98 | - [I'm missing some functionality](./docs/FAQ/Missing_functionality.md)
99 |
100 | # Libraries
101 |
102 | The following libraries are used in this PLC project and can be found under `src\Libraries`:
103 | - MQTT ([stefandreyer/CODESYS-MQTT](https://github.com/stefandreyer/CODESYS-MQTT))
104 | - CommonTypesAndFunctions ([stefandreyer/CODESYS-Common](https://github.com/stefandreyer/CODESYS-Common))
105 | - PRO_JSON ([stefandreyer/JSON-Library](https://github.com/stefandreyer/JSON-Library))
106 | - OSCAT_NETWORK_TYPES ([stefandreyer/OSCAT-NETWORK](https://github.com/stefandreyer/OSCAT-NETWORK))
107 | - BASIC_Extension ([stefandreyer/OSCAT-BASIC](https://github.com/stefandreyer/OSCAT-BASIC))
108 | - OSCAT NETWORK ([link](https://store.codesys.com/oscat-building.html))
109 | - OSCAT BASIC ([link](https://store.codesys.com/oscat-basic.html))
110 | - OSCAT BUILDING ([link](https://store.codesys.com/oscat-network.html))
111 |
112 | Special thanks to Stefan Dreyer for his assistance in some of the MQTT aspects of this project and his great work on his open-source CoDeSys MQTT library.
113 |
114 |
--------------------------------------------------------------------------------
/docs/AdditionalFunctionality/DMX_artnet.md:
--------------------------------------------------------------------------------
1 | ## DMX via Art-Net
2 |
3 | ### **General**
4 |
5 | DMX is a light protocol (alternative to DALI). It is used in stage lighting. It can have multiple universes. A house needs typically one universe, since it contains 512 channels. Each channel has 256 steps. Channels can combined to get more fine grained control.
6 |
7 | ### **Setup**
8 |
9 | Global parameters
10 | In `DMXVariables` you can set an IP. This depends on your topology. Multicast works, if the PLC and art-net node share the sub mask.
11 |
12 | // unicast: 10.1.1.4
13 | // multicast: 10.1.1.255
14 | // broadcast: 255.255.255.255
15 |
16 | In `DMX_SEND` you can set the universe. `0` is not recommended for art-net. the default is therefore `1`
17 |
18 | ### **Debug**
19 |
20 | With wireshark you can track your network. ArtNet/DMX has a dedicated parser.
21 |
22 | 
23 |
24 | If you work remove you can SSH into a PLC, to check the multicast (in this case `10.1.1.255`). Either use this cmdline or add ssh directly into wireshark
25 |
26 | ```
27 | ssh root@10.1.1.3 sudo tcpdump --dont-verify-checksums -i ethX2 -U -s0 -w - 'dst host 10.1.1.255' | "C:\Apps\Wireshark\Wireshark.exe" -k -i -
28 | ```
29 |
--------------------------------------------------------------------------------
/docs/AdditionalFunctionality/MQTT_Discovery.md:
--------------------------------------------------------------------------------
1 | ## **MQTT discovery**
2 | Several home automation systems -like Home Assistant- support [MQTT discovery](https://www.home-assistant.io/integrations/mqtt/#mqtt-discovery). Leveraging this functionality in the PLC programming will automatically provision devices in the supported home automation system.
3 |
4 | ----------------------------
5 |
6 | :information_source: Function blocks supporting MQTT discovery are marked with a  badge on their documentation page.
7 |
8 | ----------------------------
9 |
10 | Supported function blocks have a `InitMqttDiscovery` method. The method needs a [FB_PLC_MQTT_DISCOVERY_DEVICE](../FunctionBlocks/FB_PLC_MQTT_DISCOVERY_DEVICE.md) instance to work.
11 |
12 | 
13 |
14 |
15 | ### JSON library configuration
16 | In order to support MQTT discovery the 'PRO_JSON' library is used to generate the required json objects.
17 | This library is configuration sensitive. Amongst others it required the projectName in its variables to function correctly:
18 |
19 | 
--------------------------------------------------------------------------------
/docs/AdditionalFunctionality/MQTT_General.md:
--------------------------------------------------------------------------------
1 | ## **All MQTT settings**
2 |
3 | The topics are predefined once in the `MqttVariables`.
4 |
5 | Mqtt works with subscriptions and publications. An example for a dimmer publication is
6 | `Devices/PLC/House/Out/Dimmers/FB_AO_DIMMER_001/OUT`
7 |
8 | If you change any of these topic. Keep an eye on the **length of the topic and or STRING() size**
9 |
10 | ```ST
11 | (* Broker setup *)
12 | clientID :STRING:='PLC-House';
13 | broker :STRING:='192.168.1.52:1883';
14 | (* use the below for username password authentication to broker *)
15 | (* broker :STRING:='user:password@192.168.1.36:1883'; *)
16 |
17 | (* Topics *)
18 | MqttMain :STRING(16) := 'Devices/';
19 | MqttType :STRING(16) := 'PLC/';
20 | MqttDevice :STRING(16) := 'House/';
21 | // e.g. Devices/PLC/House/
22 | MqttBaseTopic :STRING(100) := CONCAT(CONCAT(MqttMain,MqttType),MqttDevice);
23 | MqttAvailabilityTopic :STRING(100) := CONCAT(MqttBaseTopic,'availability');
24 | MqttAvailabilityOnlinePayload :STRING(20) := 'online';
25 | MqttAvailabilityOfflinePayload :STRING(20) := 'offline';
26 | MQTTAvailabilityHartbeatTime :TIME:=T#5S;
27 | MqttPubLogPrefix :STRING(100) := CONCAT(MqttBaseTopic,'logger/');
28 | MqttHADiscoveryPrefix :STRING(16) := 'homeassistant/';
29 |
30 | (* FB Topics *)
31 | MqttPushbuttonPrefix :STRING(100) := CONCAT(MqttBaseTopic,'Out/DigitalInputs/Pushbuttons/');
32 | MqttPubSwitchPrefix :STRING(100) := CONCAT(MqttBaseTopic,'Out/DigitalOutputs/');
33 | MqttSubSwitchPrefix :STRING(100) := CONCAT(MqttBaseTopic,'In/DigitalOutputs/');
34 | MqttPubCoverPrefix :STRING(100) := CONCAT(MqttBaseTopic,'Out/Covers/');
35 | MqttSubCoverPrefix :STRING(100) := CONCAT(MqttBaseTopic,'In/Covers/');
36 | MqttPubDimmerPrefix :STRING(100) := CONCAT(MqttBaseTopic,'Out/Dimmers/');
37 | MqttSubDimmerPrefix :STRING(100) := CONCAT(MqttBaseTopic,'In/Dimmers/');
38 | MqttPubVirtualPrefix :STRING(100) := CONCAT(MqttBaseTopic,'Out/Virtuals/');
39 | MqttSubVirtualPrefix :STRING(100) := CONCAT(MqttBaseTopic,'In/Virtuals/');
40 | MqttPubRS485Prefix :STRING(100) := CONCAT(MqttBaseTopic,'Out/RS485/');
41 | MqttSubRS485Prefix :STRING(100) := CONCAT(MqttBaseTopic,'In/RS485/');
42 |
43 | (* Wildcard subscriptions *)
44 | MqttSubSwitchTopic :STRING(100) := CONCAT(MqttSubSwitchPrefix,'+');
45 | MqttSubCoverTopic :STRING(100) := CONCAT(MqttSubCoverPrefix,'+');
46 | MqttSubVirtualTopic :STRING(100) := CONCAT(MqttSubVirtualPrefix,'+');
47 | MqttSubDimmerTopic :STRING(100) := CONCAT(MqttSubDimmerPrefix,'#');
48 | MqttSubRS485Topic :STRING(100) := CONCAT(MqttSubRS485Prefix,'#');
49 |
50 | ```
51 |
52 | ## MQTT Birth and Last will message
53 |
54 | ### **General**
55 |
56 | The software supports so-called Birth and Last Will and Testament (LWT) messages. The former is used to send a message after the service has started, and the latter is used to notify other clients about an ungracefully disconnected client. In addtion to a Birth message on startup the Birth message is also published cyclic as a harbeat.
57 |
58 | ### **Examples**
59 |
60 | Birth message:
61 | Topic: `Devices/PLC/House/availability`
62 | Payload: `online`
63 |
64 |
65 | LWT message:
66 | Topic: `Devices/PLC/House/availability`
67 | Payload: `offline`
68 |
69 | Note that the Topics and payloads can be changed in de code. The Birth message is by default published during startup and after that every 5 seconds (hartbeat). This can be changed as well in the code.
70 |
--------------------------------------------------------------------------------
/docs/AdditionalFunctionality/User_leds_Codesys3S_runtime.md:
--------------------------------------------------------------------------------
1 | ## User leds (Codesys 3S runtime)
2 |
3 | ### **General**
4 |
5 | It's possible to control the *U* leds on a WAGO PFC controller. The example below illustrates how.
6 |
7 | ### **Prerequisites**
8 | the following libaries should be present:
9 |
10 | - CmpPfcx00
11 |
12 | ### **Implementation**
13 | The project has a working implementation that controls the *U1* led, displaying it green when there is a working connection with the MQTT broker, flashing red if not.
14 |
15 | - controlling the led depending on connection with the MQTT broker
16 | ```
17 | IF MQTTClient.connected THEN
18 | PFC.SetLed(which:=PFC.LED.U1, how:=PFC.LedState.STATIC_GRN);
19 | ELSE
20 | PFC.SetLed(which:=PFC.LED.U1, how:=PFC.LedState.BLINK_RED);
21 | END_IF
22 | ```
23 | The code has been commented out to prevent interference with users that work with the é!COCKPIT runtime.
24 |
--------------------------------------------------------------------------------
/docs/AdditionalFunctionality/User_leds_éCOCKPIT_runtime.md:
--------------------------------------------------------------------------------
1 | ## User leds (é!COCKPIT runtime)
2 |
3 | ### **General**
4 |
5 | It's possible to control the *U* leds on a WAGO PFC controller. The example below illustrates how.
6 |
7 | ### **Prerequisites**
8 | the following libaries should be present:
9 |
10 | - WagoAppAppLED
11 | - WagoTypesAppLED
12 |
13 | ### **Implementation**
14 | The project has a working implementation that controls the *U1* led, displaying it green when there is a working connection with the MQTT broker, flashing red if not.
15 |
16 | - variables initiation (inside *PLC_PRG_MQTT*):
17 | ```
18 | LED_1_BrokerStatus :FbAppLED;
19 | ```
20 |
21 | - controlling the led depending on connection with the MQTT broker
22 | ```
23 | LED_1_BrokerStatus(eID:=eLedID.AppLED_1, xOpen:=TRUE );
24 | IF(MQTTClient.connected) THEN
25 | LED_1_BrokerStatus.SetStatic(eLedColor.Green);
26 | ELSE
27 | LED_1_BrokerStatus.SetFlash(T#1S,eLedColor.Red, eLedColor.Off);
28 | END_IF
29 | ```
30 | The code has been commented out to prevent interference with users that work with the CODESYS 3S runtime.
31 |
--------------------------------------------------------------------------------
/docs/CONTRIBUTING.md:
--------------------------------------------------------------------------------
1 | ## How to contribute
2 |
3 | #### **Did you find a bug?**
4 |
5 | * **Ensure the bug was not already reported** by searching on GitHub under [Issues](https://github.com/MichielVanwelsenaere/HomeAutomation.CoDeSys3/issues).
6 |
7 | * If you're unable to find an open issue addressing the problem, [open a new one](https://github.com/MichielVanwelsenaere/HomeAutomation.CoDeSys3/issues/new). Be sure to include a **title and clear description**, as much relevant information as possible, and a **code sample** or a **clear explanation** demonstrating the expected behavior that is not occurring.
8 |
9 |
10 | #### **Did you write a patch that fixes a bug?**
11 |
12 | * Make sure there is a Github issue for the patch you are writing.
13 |
14 | * Open a new GitHub pull request with the patch.
15 |
16 | * Ensure the PR description clearly describes the problem and solution. Include the relevant issue number.
17 |
18 | In case your specific project differs to much from the reference project in this repository, use the PLCopen XML to export the specific artifacts including the fix and paste them in the relevant Github issue.
19 |
20 | #### **Do you intend to add a new feature or change an existing one?**
21 |
22 | * Suggest your change/feature in the [Gitter chat](https://gitter.im/MichielVanwelsenaere/HomeAutomation.CoDeSys3) and start writing code.
23 |
24 | * Do not open an issue on GitHub until you have collected positive feedback about the change. GitHub issues are primarily intended for bug reports, fixes and milestone tracking.
25 |
26 | #### **Do you have questions about the source code?**
27 |
28 | * Ask any question about how to use the source code in the [Gitter chat](https://gitter.im/MichielVanwelsenaere/HomeAutomation.CoDeSys3).
29 |
30 | # Merge request (pull request)
31 |
32 | ## **GIT side**
33 |
34 | 1. Create own fork (if you not already did)
35 | 2. Don't change the default `.ecp` for your own config
36 | 3. Optional: Create branch
37 | 4. Code
38 | 5. Prepare for export, see below.
39 | 6. Add documentation in the markdown files.
40 | 6. Create merge/pull request from your repo to this.
41 |
42 | ## **Prepare for export**
43 |
44 | An export contains `.export` and `.xml` for people to update. The `.ecp` is upgraded to the new changes, so its a basic version for newcomers.
45 |
46 | 1. Save file the `.ecp`
47 |
48 | - Make sure the original ecp is **unmodified**
49 | - Save with another name.
50 |
51 | 2. Run export (from your modified ecp)
52 |
53 | - Export all files except configs
54 |
55 | 
56 |
57 | So no `*variables`, `PRG's` and `PersistenceVars`
58 | - You can export Variables/Library if you see fit
59 | - Codesys v3 >>> [Exports\PLCopen.xml](../src/Exports/PLCopen.xml)
60 | - PLCopen XML >>> [Exports\CodesysV3.export](../src/Exports/CodesysV3.export)
61 |
62 | 3. Open the original `.ecp`. Keep your config out.
63 | - Follow [this guide](FAQ/Howto_updating_function_blocks.md) to update your blocks
64 |
65 | - Add 1 example of the new function block/methods to the POU
66 | - Document the new function block/methods in the POU!
--------------------------------------------------------------------------------
/docs/FAQ/Getting_started_guide_éCOCKPIT.md:
--------------------------------------------------------------------------------
1 | ## Getting started guide (é!COCKPIT runtime)
2 |
3 | ### **Getting to know CoDeSys3**
4 | If you have experience with programming in CodeSys3 you can skip this part. Otherwise, it's advised to gain some experience by checking the sources below:
5 |
6 | - Setup environment and creation first project: [YouTube video](https://www.youtube.com/watch?v=hI8t9UHPV8s)
7 | - CoDeSys start guide (uses CoDeSys 2.3 but principles still applicable): [YouTube playlist](https://www.youtube.com/watch?v=WP9pUfBi6Pw&list=PL08CDB741463CA7B4&index=1)
8 | - CoDeSys Sequential Function Charts Explained: [YouTube video](https://www.youtube.com/watch?v=eP42t9O5drk)
9 | - Getting to know the IEC 61131-3 standard: [iec 61131-3 reference](https://bitbucket.org/ntphx/iec-61131)
10 |
11 | ### **Setup CoDeSys 3S**
12 |
13 | 1. Download é!COCKPIT from the [WAGO website](https://www.wago.com/global/automation-technology/discover-software/ecockpit-engineering-software).
14 |
15 |
16 | ### **Open the project**
17 |
18 | 1. open the file with *.ecp* extension in é!COCKPIT.
19 |
20 | ### **Libraries**
21 |
22 | 1. Go to the *Library Manager* → *Libary repository* menu:
23 |
24 | 
25 |
26 | 2. install all libraries from the [src/Libraries](https://github.com/MichielVanwelsenaere/HomeAutomation.CoDeSys3/tree/master/src/Libraries) folder.
27 |
28 | 
29 |
30 |
31 | ### **Build**
32 |
33 | 1. Build the project
34 |
35 | 
36 |
37 | ### **Uploading and running the project**
38 |
39 | [This video](https://www.youtube.com/watch?v=K-zUGiEQRAw) provides all instructions.
--------------------------------------------------------------------------------
/docs/FAQ/Howto_adding_a_new_MQTT_subscription.md:
--------------------------------------------------------------------------------
1 | ## How-to: Adding a new MQTT subscription
2 | This page describes the steps required to add a new MQTT subscription in the reference project.
3 |
4 | 1. Add a new subscriber function block in the *PLC_PRG_MQTT* program variable declaration. Example below:
5 | ```
6 | (* variables for MQTT subscribing *)
7 | subscriber_FB_OUTPUT_SWITCH_MQTT:SD_MQTT.MQTTSubscribe;
8 | subscriber_FB_OUTPUT_COVER_MQTT:SD_MQTT.MQTTSubscribe;
9 | subscriber_FB_VIRTUAL_MQTT:SD_MQTT.MQTTSubscribe;
10 | ```
11 |
12 | 2. Add a new callback function block in the *MqttVariables* global variables. Example below:
13 | ```
14 | (* Shared Variables for MQTT subscribe communication *)
15 | collector_FB_OUTPUT_SWITCH_MQTT :SD_MQTT.CallbackCollector;
16 | collector_FB_OUTPUT_COVER_MQTT :SD_MQTT.CallbackCollector;
17 | collector_FB_VIRTUAL_MQTT :SD_MQTT.CallbackCollector;
18 | ```
19 | These function blocks are created in a global variable list so they are accessible from all PRGs. This is necessary because function blocks require access to the callbackcollector for being able to register itself to a MQTT subscription.
20 |
21 | 3. Initialize the subscriber function block in the *MQTT_INIT* action in the *PLC_PRG_MQTT* program. Example below:
22 | ```
23 | (* INIT MQTT SUBSCRIBE STUFF *)
24 | subscriber_FB_OUTPUT_SWITCH_MQTT.SetMqttInOut(MQTT_IN_OUT:= ADR(MQTT_IN_OUT));
25 | subscriber_FB_OUTPUT_COVER_MQTT.SetMqttInOut(MQTT_IN_OUT:= ADR(MQTT_IN_OUT));
26 | subscriber_FB_VIRTUAL_MQTT.SetMqttInOut(MQTT_IN_OUT:= ADR(MQTT_IN_OUT));
27 | ```
28 | The *MQTT_IN_OUT* is the object that links the subscribers to the MQTT Client.
29 |
30 | 4. Call the subscriber function block in the *MQTT_SUBSCRIBE* action in the *PLC_PRG_MQTT* program. Example below:
31 | ```
32 | subscriber_FB_OUTPUT_SWITCH_MQTT(
33 | Subscribe:= TRUE,
34 | Topic:= ADR('Devices/PLC/House/In/DigitalOutputs/+'),
35 | QoSSubscribe:= SD_MQTT.QoS.ExactlyOnce,
36 | ExpectingString:= TRUE,
37 | Callback:= MqttVariables.collector_FB_OUTPUT_SWITCH_MQTT,
38 | );
39 |
40 | subscriber_FB_OUTPUT_COVER_MQTT(
41 | Subscribe:= TRUE,
42 | Topic:= ADR('Devices/PLC/House/In/Covers/+'),
43 | QoSSubscribe:= SD_MQTT.QoS.ExactlyOnce,
44 | ExpectingString:= TRUE,
45 | Callback:= MqttVariables.collector_FB_OUTPUT_COVER_MQTT,
46 | );
47 | ```
48 |
49 | 5. Register the required function blocks against the callback function block to trigger the callback method when a new message arrives on the subscribed topic. Example below:
50 | ```
51 | pMqttCallbackCollector^.put(instance:= THIS^);
52 | ```
53 | A more in depth implementation can be found in the *InitMqtt* method of every MQTT function block in the reference project.
54 |
55 | 6. Implement the callback method triggered by the callback function block. More details below:
56 | - Add the *IMPLEMENTS* statement:
57 | ```
58 | FUNCTION_BLOCK FB_VIRTUAL_STRING_MQTT IMPLEMENTS SD_MQTT.MQTT_SUBSCRIBE_CALLBACK
59 | ```
60 | - Add the *PublishReceived* callback method:
61 | ```
62 | METHOD PublishReceived : bool
63 | VAR_INPUT
64 | (*Collection of received Data*)
65 | Data : SD_MQTT.CALLBACK_DATA;
66 | END_VAR
67 | ```
68 | - Add logic to process the received MQTT message: in this reference project a check is executed if the subscription that triggered the callback method matches the subscription configured in the *MqttInit* method. In that method the subscription topic is automatically concatenated with the function block name. For more in depth details study the *PublishReceived* and *MqttInit* methods of every MQTT function block in the reference project.
69 |
70 |
71 |
--------------------------------------------------------------------------------
/docs/FAQ/Howto_updating_function_blocks.md:
--------------------------------------------------------------------------------
1 | ## How-to: updating function blocks to the latest version
2 | This page describes the advised process to upgrade the function blocks in the project the latest version.
3 |
4 | 1. Navigate to the [src/PLCOpen](https://github.com/MichielVanwelsenaere/HomeAutomation.CoDeSys3/blob/master/src/Exports/PLCopen.xml) directory on GitHub.
5 | 2. Download the xml file. This file contains an export of the entire project.
6 | 3. Open your personal project, and navigate to the 'import PLCOpen' option.
7 | 4. Select everything to import except 'HomeAutomation':
8 |
9 | 
10 |
11 | 5. Resolve all conflicts by replacing:
12 |
13 | 
14 |
15 |
16 |
17 |
18 |
19 |
--------------------------------------------------------------------------------
/docs/FAQ/Howto_verifying_resource_usage_WagoPFC.md:
--------------------------------------------------------------------------------
1 | ## How-to: Verifying resource usage on a Wago PFC PLC
2 | This page describes the steps required to verify the resource usage (CPU/memory) on a Wago PFC.
3 | Steps might be similair for other PLCs.
4 |
5 | 1. Using an SSH client -for example PuTTY- SSH into the IP address of your PLC.
6 | 2. Run the `htop` command to verify the resource usage on your PLC:
7 |
8 | 
9 |
10 |
11 |
--------------------------------------------------------------------------------
/docs/FAQ/Missing_functionality.md:
--------------------------------------------------------------------------------
1 | ## Missing functionality
2 | Found this repository, read trough the documentation and missing some functionality for your needs? Open [a issue](https://github.com/MichielVanwelsenaere/HomeAutomation.CoDeSys3/issues/new), describe your needs, and we'll have a look!
3 |
--------------------------------------------------------------------------------
/docs/FAQ/RS485_tips_and_tricks.md:
--------------------------------------------------------------------------------
1 | ## RS485: Tips and Tricks
2 | This page describes some tips and tricks to verify and resolve RS485 issues.
3 |
4 | ### **Testing the RS485 device**
5 | In many cases it can be usefull to test the RS485 device from a PC before attempting to connect and read it out by your PLC device. In first instance it allows detection of faulty devices but in parallel also provides more insights in the structure of the device modbus registers .
6 |
7 | To be able to communicate with modbus RTU devices from a PC you'll need a USB to RS485 convertor ([example here](https://www.aliexpress.com/item/32638090708.html)).
8 | Consider acquiring two convertors to simultaneously send modbus commands and sniff the traffic.
9 |
10 | Using [QModMaster](https://sourceforge.net/projects/qmodmaster/) specific modbus RTU commands can be executed. For example:
11 |
12 | 
13 |
14 | Note: use 'Device Manager' to establish on what COM port the USB to RS485 convertor is located.
15 |
16 | In addition to targeted modbus commands the QModMaster software also allows scanning of the RS485 bus to find any devices. This can be usefull if you don't now the address of your device.
17 |
18 | ### **Verifying traffic on the bus**
19 | When not able to perform and modbus read/write commands it's often hard to establish the exact cause. Is the device faulty, is there a problem on the bus or is the master device not able to send a command on the RS485 bus?
20 | An easy trick to narrow it down is using a regular led diode and placing it on the RS485 bus datawires.
21 | The led will light up everytime data passes over the bus providing more information to where the problem might occur.
22 |
23 | ### **RS485 cabling best practices**
24 |
25 | Consider [this article on electrical-engineering](https://electrical-engineering-portal.com/correct-cabling-modbus-rs485) a must read.
26 |
27 |
28 | ### **Using a dedicated Wago RS485 module**
29 | Depending on requirements a dedicated RS485 module might be required instead of using the onboard serial port of the device (if available).
30 |
31 | Based on user experience in this field, pay attention to:
32 | - reset the module to factory settings before using.
33 | - last confirmed working version of required libraries:
34 | - WagoSysModule_75x_65x: Version 1.9.5.2
35 | - WagoTypesCom: Version 1.6.1.3
36 | - change the 'comport' in the RS485 master function block you intend to use.
37 | - make sure the wiring of the module is correct:
38 |
39 | 
--------------------------------------------------------------------------------
/docs/FunctionBlocks/FB_INPUT_BINARYSENSOR_MQTT.md:
--------------------------------------------------------------------------------
1 | ## FB_INPUT_BINARYSENSOR_MQTT
2 | 
3 |
4 | ### **General**
5 | Binary sensors gather information about the state of devices which have a "digital" return value (either 1 or 0). These can be switches, contacts, pins, etc. These sensors only have two states: *0/off/low/closed/false* and *1/on/high/open/true*
6 |
7 | ### **Block diagram**
8 |
9 | 
10 |
11 | INPUT(S)
12 | - BS: digital input linked to the signal wire of the binary sensor.
13 |
14 | OUTPUT(S)
15 | - Q: follows the input `BS` but debounced.
16 | - EVENT: output high for one clock cycle when any event occurs on debounced input `BS`.
17 | - EVENT_R: output high for one clock cycle when a rising edge is detected on debounced input `BS`.
18 | - EVENT_F: output high for one clock cycle when a falling edge is detected on debounced input `BS`.
19 |
20 | METHOD(S)
21 | - InitMQTT: enables MQTT events on the FB, an overview of the parameters:
22 | - `MQTTPublishPrefix`: datatype *POINTER TO STRING*, pointer to the MQTT publish prefix that should be used for publishing any messages/events for this FB. Suffix is automatically set to FB name.
23 | - `pMqttPublishQueue`: datatype *POINTER TO FB_MqttPublishQueue*, pointer to the MQTT queue to publish messages.
24 | - `pMqttCallbackCollector`: datatype _POINTER TO MQTT.CallbackCollector, pointer to the MQTT callback collector to receive subscribe messages.
25 |
26 | - ConfigureFunctionBlock: configures the behaviour of output `Q` using the parameters below:
27 | - `T_TurnOffDelay`: duration of the turn off delay added on output `Q` to prevent rapid ON/OFF behaviour on the output caused by a fast switching sensor on the digital input. Defaults to 0 seconds, can be extremely usefull when connecting a motion sensor the the PLC.
28 |
29 | ### **MQTT publish behavior**
30 | Requires method call `InitMQTT` to enable MQTT capabilities.
31 |
32 | | Event | Description | MQTT payload | QoS | Retain flag | Published on startup |
33 | |:-------------|:------------------|:------------------|:------------------|:--------------------------|:--------------------------|
34 | | **input changes: BS** | A change is detected on input `BS`. (*) | `ON/OFF` | 2 | `TRUE` | yes
35 |
36 | MQTT publish topic is a concatenation of the publish prefix variable and the function block name.
37 |
38 | ### **Code example**
39 |
40 | - variables initiation:
41 | ```
42 | MQTTBinarySensorPrefix :STRING(100) := 'Devices/PLC/House/Out/DigitalInputs/BinarySensors/';
43 | FB_DI_BS_001 :FB_INPUT_BINARYSENSOR_MQTT;
44 | ```
45 |
46 | - Init MQTT method call (called once during startup):
47 | ```
48 | FB_INPUT_BINARYSENSOR_MQTT.InitMQTT(MQTTPublishPrefix:= ADR(MQTTBinarySensorPrefix), (* pointer to string prefix for the MQTT publish topic *)
49 | pMQTTPublishQueue := ADR(MQTTVariables.fbMQTTPublishQueue) (* pointer to MQTTPublishQueue to send a new MQTT event *)
50 | );
51 | ```
52 | The MQTT publish topic in this code example will be `Devices/PLC/House/Out/DigitalInputs/BinarySensors/FB_DI_BS_001` (MQTTBinarySensorPrefix variable + function block name).
53 |
54 | - Configuration of the function block with a 5 second turn off delay on the output (called once during startup):
55 | ```
56 | FB_INPUT_BINARYSENSOR_MQTT.ConfigureFunctionBlock(T_TurnOffDelay:= T#5S); (* time to delay the negative edge on output Q *)
57 | ```
58 |
59 | - reading digital input for events (cyclic):
60 | ```
61 | FB_DI_BS_001(BS:= DI_001);
62 | ```
63 |
64 | - integration with `FB_OUTPUT_BINARY_MQTT`:
65 | ```
66 | FB_DO_SW_001(OUT=> DO_001, (* couple the function block to the physical output *)
67 | PRIO_HIGH:= FALSE, (* brings the output high regardless of other input values *)
68 | PRIO_LOW:= FALSE, (* brings the output low regardless of other input values. NOTE: Priohigh overrules Priolow input *)
69 | TOGGLE:= FB_DI_BS_001.EVENT (* for toggling the output *)
70 | );
71 | ```
72 |
73 | - MQTT discovery:
74 | ```
75 | FB_DI_BS_001.InitMqttDiscovery(
76 | Name := 'Binary sensor 001', (* The name show in Home Assistant frond-end*)
77 | Device := ADR(PLC_DEVICE), (* The device show in Home Assistant *)
78 | );
79 | ```
80 |
81 | ### **Home Assistant YAML**
82 | If [MQTT discovery](../AdditionalFunctionality/MQTT_Discovery.md) is not working for you, you can use the YAML code below in your [MQTT binary sensor](https://www.home-assistant.io/components/binary_sensor.mqtt/) config:
83 |
84 | ```YAML
85 | mqtt:
86 | binary_sensor:
87 | - name: "FB_DI_BS_001"
88 | state_topic: "Devices/PLC/House/Out/DigitalInputs/BinarySensors/FB_DI_BS_001"
89 | qos: 2
90 | payload_on: "ON"
91 | payload_off: "OFF"
92 | availability_topic: "Devices/PLC/House/availability"
93 | payload_available: "online"
94 | payload_not_available: "offline"
95 | ```
96 |
--------------------------------------------------------------------------------
/docs/FunctionBlocks/FB_INPUT_PUSHBUTTON_MQTT.md:
--------------------------------------------------------------------------------
1 | ## FB_INPUT_PUSHBUTTON_MQTT
2 | 
3 |
4 | ### **General**
5 | Reads out a digital input and sets a single, double or long output high for one cycle when one of those events has been detected on the configured input.
6 |
7 | ### **Block diagram**
8 |
9 | 
10 |
11 | INPUT(S)
12 | - PB: digital input linked to the signal wire of a pushbutton.
13 |
14 | OUTPUT(S)
15 | - SINGLE: output high for one clock cycle when a single push is detected on input `PB`.
16 | - DOUBLE: output high for one clock cycle when a double push is detected on input `PB`.
17 | - LONG: output high for one clock cycle when a long push is detected on input `PB`.
18 | - P_LONG: output becomes high when a long push is detected on input `PB`, remains high as long as `PB` remains high.
19 |
20 | METHOD(S)
21 | - InitMQTT: enables MQTT events on the FB, an overview of the parameters:
22 | - `MQTTPublishPrefix`: datatype *POINTER TO STRING*, pointer to the MQTT publish prefix that should be used for publishing any messages/events for this FB. Suffix is automatically set to FB name.
23 | - `pMqttPublishQueue`: datatype *POINTER TO FB_MqttPublishQueue*, pointer to the MQTT queue to publish messages.
24 | - `pMqttCallbackCollector`: datatype _POINTER TO MQTT.CallbackCollector, pointer to the MQTT callback collector to receive subscribe messages.
25 |
26 | - ConfigureFunctionBlock: configures the time parameter specifing the decoding time for long key press. Defaults to 400ms.
27 |
28 | ### **MQTT publish behavior**
29 | Requires method call `InitMQTT` to enable MQTT capabilities.
30 |
31 | | Event | Description | MQTT payload | QoS | Retain flag | Published on startup |
32 | |:-------------|:------------------|:------------------|:------------------|:--------------------------|:--------------------------|
33 | | **Pushbutton single press** | A single pushbutton press is detected on input `PB`. | `{"event_type": "SINGLE"}` | 2 | `FALSE` | no
34 | | **Pushbutton double press** | A double pushbutton press is detected on input `PB`. | `{"event_type": "DOUBLE"}` | 2 | `FALSE` | no
35 | | **Pushbutton long press** | A long pushbutton press is detected on input `PB`. | `{"event_type": "LONG"}` | 2 | `FALSE` | no
36 |
37 | MQTT publish topic is a concatenation of the publish prefix variable and the function block name.
38 |
39 | (*): MQTT publish topic is a concatenation of the publish prefix variable, the function block name and the name of the output.
40 |
41 | ### **Code example**
42 |
43 | - variables initiation:
44 | ```
45 | MQTTPushbuttonPrefix :STRING(100) := 'Devices/PLC/House/Out/DigitalInputs/Pushbuttons/';
46 | FB_DI_PB_001 :FB_INPUT_PUSHBUTTON_MQTT;
47 | ```
48 |
49 | - Init MQTT method call (called once during startup):
50 | ```
51 | FB_DI_PB_001.InitMQTT(MQTTPublishPrefix:= ADR(MQTTPushbuttonPrefix), (* pointer to string prefix for the MQTT publish topic *)
52 | pMQTTPublishQueue := ADR(MQTTVariables.fbMQTTPublishQueue) (* pointer to MQTTPublishQueue to send a new MQTT event *)
53 | );
54 | ```
55 | The MQTT publish topic in this code example will be `Devices/PLC/House/Out/DigitalInputs/Pushbuttons/FB_DI_PB_001` (MQTTPushbuttonPrefix variable + function block name).
56 |
57 | - reading digital input for events (cyclic):
58 | ```
59 | FB_DI_PB_001(PB:= DI_001);
60 | ```
61 |
62 | - integration with `FB_OUTPUT_SWITCH_MQTT`:
63 | ```
64 | FB_DO_SW_001(OUT=> DO_001, (* couple the function block to the physical output *)
65 | PRIOHIGH:= FALSE, (* brings the output high regardless of other input values *)
66 | PRIOLOW:= FALSE, (* brings the output low regardless of other input values. NOTE: Priohigh overrules Priolow input *)
67 | TOGGLE:= FB_DI_PB_001.SINGLE (* for toggling the output *)
68 | );
69 | ```
70 |
71 | - MQTT discovery:
72 | ```
73 | FB_DI_PB_001.InitMqttDiscovery(
74 | Name := 'pushbutton 001', (* The name show in Home Assistant frond-end*)
75 | Device := ADR(PLC_DEVICE), (* The device show in Home Assistant *)
76 | );
77 | ```
78 |
79 | ### **Home Assistant YAML**
80 | If [MQTT discovery](../AdditionalFunctionality/MQTT_Discovery.md) is not working for you, you can use the YAML code below in your [MQTT events](https://www.home-assistant.io/integrations/event.mqtt/) config:
81 |
82 | ```YAML
83 | mqtt:
84 | event:
85 | # To receive single/double/long events
86 | - name: "FB_DI_PB_001"
87 | state_topic: "Devices/PLC/House/Out/DigitalInputs/Pushbuttons/FB_DI_PB_001"
88 | event_types:
89 | - "SINGLE"
90 | - "DOUBLE"
91 | - "LONG"
92 | qos: 2
93 | device_class: "button"
94 | availability_topic: "Devices/PLC/House/availability"
95 | payload_available: "online"
96 | payload_not_available: "offline"
97 | ```
--------------------------------------------------------------------------------
/docs/FunctionBlocks/FB_MQTT_LOG.md:
--------------------------------------------------------------------------------
1 | ## FB_MQTT_LOG
2 | 
3 |
4 | 
5 |
6 | INPUT(S)
7 |
8 | OUTPUT(S)
9 |
10 | METHOD(S)
11 |
12 | - InitMQTT: enables MQTT events on the FB, an overview of the parameters:
13 | - `MQTTPublishPrefix`: datatype _POINTER TO STRING_, pointer to the MQTT publish prefix that should be used for publishing any messages/events for this FB. Suffix is automatically set to FB name.
14 | - `pMqttPublishQueue`: datatype _POINTER TO FB_MqttPublishQueue_, pointer to the MQTT queue to publish messages.
15 | - `MqttQos`: datatype _SD_MQTT.QoS_, configures the MQTT Qos for the function block published messages.
16 | - `MqttRetain`: datatype _BOOL_, configures the MQTT retain flag for the function block published messages.
17 | - `pMqttCallbackCollector`: datatype _POINTER TO MQTT.CallbackCollector, pointer to the MQTT callback collector to receive subscribe messages.
18 | - send: allows logging to MQTT. The output string is formatted as follows: `instance | payload`
19 | - `instance` String for your own choice.
20 | - `payload`: datatype _STRING_, the payload to be sent to MQTT. String(128)
21 | - InitMqttDiscovery:
22 | - See [MQTT Discovery](./../AdditionalFunctionality/MQTT_Discovery.md) for more info.
23 |
24 | ### **Code example**
25 |
26 | - variables initiation: (inside MqttVariables)
27 | ```
28 | MQTT_logger :FB_MQTT_LOG;
29 | ```
30 |
31 | - Init MQTT method call (called once during startup):
32 | ```
33 | MqttVariables.MQTT_logger.InitMqtt(
34 | MQTTPublishPrefix:= ADR(MqttPubLogPrefix),
35 | pMqttPublishQueue := ADR(MqttVariables.fbMqttPublishQueue),
36 | MqttQos:=MQTT.QoS.ExactlyOnce,
37 | MqttRetain:=FALSE
38 | );
39 | ```
40 |
41 | - To send a message to MQTT:
42 | ```
43 | MqttVariables.MQTT_logger.send('Init finished');
44 | ```
45 |
46 | - MQTT discovery:
47 | ```
48 | MqttVariables.MQTT_logger.InitMqttDiscovery(
49 | Device := ADR(PLC_DEVICE), (* The device show in Home Assistant *)
50 | );
51 | ```
52 | ### **Home Assistant YAML**
53 | If [MQTT discovery](../AdditionalFunctionality/MQTT_Discovery.md) is not working for you, you can use the following to your `configuration.yaml`:
54 |
55 | ```yaml
56 | - name: "plc_log"
57 | object_id: "plc_log"
58 | unique_id: "plc_log"
59 | state_topic: "Devices/PLC/House/debug"
60 | qos: 2
61 | availability_topic: "Devices/PLC/House/availability"
62 | payload_available: "online"
63 | payload_not_available: "offline"
64 |
65 | ```
66 |
67 | ### **Home Assistant dashboard**
68 |
69 | You can use the following card:
70 |
71 | ```yaml
72 | type: logbook
73 | entities:
74 | - sensor.plc_log
75 | ```
76 |
--------------------------------------------------------------------------------
/docs/FunctionBlocks/FB_OUTPUT_BINARY_MQTT.md:
--------------------------------------------------------------------------------
1 | ## FB_OUTPUT_BINARY_MQTT
2 | 
3 |
4 | ### **General**
5 | Can be switched using pulses that are high for one clock cycle (for example from `FB_INPUT_PUSHBUTTON_MQTT`), maintains output state through powercycles.
6 |
7 | ### **Block diagram**
8 |
9 | 
10 |
11 | INPUT(S)
12 | - TOGGLE: when high the output `OUT` gets toggled. input should one be high for one clockcycle.
13 | - PRIO_HIGH: when high the output `OUT` is set to high, has priority over the `TOGGLE` and `PRIO_LOW` input.
14 | - PRIO_LOW: when high the output `OUT` is set to low, has priority over the `TOGGLE` input.
15 |
16 | OUTPUT(S)
17 | - OUT: output to switch digital output on and off. Can be connected to a relay for example.
18 |
19 | METHOD(S)
20 | - InitMQTT: enables MQTT events on the FB, an overview of the parameters:
21 | - `MQTTPublishPrefix`: datatype *POINTER TO STRING*, pointer to the MQTT publish prefix that should be used for publishing any messages/events for this FB. Suffix is automatically set to FB name.
22 | - `MQTTSubscribePrefix`: datatype *POINTER TO STRING*, pointer to the MQTT subscribe prefix that should be used for publishing any messages/events to this FB. Suffix is automatically set to FB name.
23 | - `pMqttPublishQueue`: datatype *POINTER TO FB_MqttPublishQueue*, pointer to the MQTT queue to publish messages.
24 | - `pMqttCallbackCollector`: datatype *SD_MQTT.CallbackCollector*, pointer to the MQTT callback collector, required to register FB for subscriptions on a certain topic.
25 |
26 | - PublishReceived: callback method called by the callbackcollector when a message is received on the subscribed topic by the callbackcollector.
27 |
28 | ### **MQTT publish behavior**
29 | Requires method call `InitMQTT` to enable MQTT capabilities.
30 |
31 | | Event | Description | MQTT payload | QoS | Retain flag | Published on startup |
32 | |:-------------|:------------------|:------------------|:------------------|:--------------------------|:--------------------------|
33 | | **Output changes: OUT** | A change is detected on output `OUT`. | `TRUE/FALSE` | 2 | `TRUE` | yes
34 |
35 | MQTT publish topic is a concatenation of the publish prefix and the function block name.
36 |
37 | ### **MQTT subscribe behavior**
38 | Requires method call `InitMQTT` to enable MQTT capabilities.
39 | Commands are executed by the FB if the topic `MQTTSubscribeTopic` matches the MQTT topic and the payload exists in the table below.
40 |
41 | | Command | Description | expected payload | Additional notes |
42 | |:-------------|:------------------|:------------------|:------------------|
43 | | **Change output to high** | Request to change output to high. | `TRUE` | Command executed when `PRIO_HIGH` and `PRIO_LOW` inputs are low.
44 | | **Change output to low** | Request to change output to low. | `FALSE` | Command executed when `PRIO_HIGH` and `PRIO_LOW` inputs are low.
45 |
46 | MQTT subscription topic is a concatenation of the subscribe prefix variable and the function block name.
47 |
48 | ### **Code example**
49 |
50 | - variables initiation:
51 | ```
52 | MQTTPubSwitchPrefix :STRING(100) := 'Devices/PLC/House/Out/DigitalOutputs/';
53 | MQTTSubSwitchPrefix :STRING(100) := 'Devices/PLC/House/In/DigitalOutputs/';
54 | FB_DO_SW_001 :FB_OUTPUT_BINARY_MQTT;
55 | ```
56 |
57 | - Init MQTT method call (called once during startup):
58 | ```
59 | FB_DO_SW_001.InitMQTT(MQTTPublishPrefix:= ADR(MQTTPubSwitchPrefix), (* pointer to string prefix for the MQTT publish topic *)
60 | MQTTSubscribePrefix:= ADR(MQTTSubSwitchPrefix), (* pointer to string prefix for the MQTT subscribe topic *)
61 | pMQTTPublishQueue := ADR(MQTTVariables.fbMQTTPublishQueue), (* pointer to MQTTPublishQueue to send a new MQTT event *)
62 | pMQTTCallbackCollector := ADR(MQTTVariables.collector_FB_OUTPUT_BINARY_MQTT) (* pointer to CallbackCollector to receive MQTT subscription events *)
63 | );
64 | ```
65 | The MQTT publish topic in this code example will be `Devices/PLC/House/Out/DigitalOutputs/FB_DO_SW_001` (MQTTPubSwitchPrefix variable + function block name). The subscription topic will be `Devices/PLC/House/In/DigitalOutputs/FB_DO_SW_001` (MQTTSubSwitchPrefix variable + function block name).
66 |
67 |
68 | - checking for events to switch the digital output (cyclic):
69 | ```
70 | FB_DO_SW_001(OUT=> DO_001, (* couple the function block to the physical output *)
71 | PRIO_HIGH:= FALSE, (* brings the output high regardless of other input values *)
72 | PRIO_LOW:= FALSE (* brings the output low regardless of other input values. NOTE: Priohigh overrules Priolow input *)
73 | TOGGLE:= FB_DI_PB_009.SINGLE (* for toggling the output *)
74 | );
75 | ```
76 |
77 | - integration with `FB_INPUT_PUSHBUTTON_MQTT`:
78 | ```
79 | FB_DO_SW_001(OUT=> DO_001, (* couple the function block to the physical output *)
80 | PRIO_HIGH:= FALSE, (* brings the output high regardless of other input values *)
81 | PRIO_LOW:= FALSE, (* brings the output low regardless of other input values. NOTE: Priohigh overrules Priolow input *)
82 | TOGGLE:= FB_DI_PB_001.SINGLE (* for toggling the output *)
83 | );
84 | ```
85 |
86 | - MQTT discovery (choose one):
87 | ```
88 | (* switch entity *)
89 | FB_DO_SW_001.InitMqttDiscoveryAsSwitch(
90 | Name := 'switch 001', (* The name show in Home Assistant frond-end*)
91 | Device := ADR(PLC_DEVICE), (* The device show in Home Assistant *)
92 | );
93 |
94 | (* light entity *)
95 | FB_DO_SW_001.InitMqttDiscoveryAsLight(
96 | Name := 'light 001', (* The name show in Home Assistant frond-end*)
97 | Device := ADR(PLC_DEVICE), (* The device show in Home Assistant *)
98 | );
99 |
100 | (* siren entity *)
101 | FB_DO_SW_001.InitMqttDiscoveryAsSiren(
102 | Name := 'siren 001', (* The name show in Home Assistant frond-end*)
103 | Device := ADR(PLC_DEVICE), (* The device show in Home Assistant *)
104 | );
105 |
106 | (* lock entity *)
107 | FB_DO_SW_001.InitMqttDiscoveryAsLock(
108 | Name := 'lock 001', (* The name show in Home Assistant frond-end*)
109 | Device := ADR(PLC_DEVICE), (* The device show in Home Assistant *)
110 | );
111 |
112 | (* valve entity *)
113 | FB_DO_SW_001.InitMqttDiscoveryAsValve(
114 | Name := 'valve 001', (* The name show in Home Assistant frond-end*)
115 | Device := ADR(PLC_DEVICE), (* The device show in Home Assistant *)
116 | );
117 | ```
118 |
119 | By default a 'NO' (Normally Open) contact is assumed for MQTT discovery yet this can be inverted to a 'NC' (Normally Closed) contact by leveraging the 'Invert' parameter:
120 |
121 | ```
122 | FB_DO_SW_001.InitMqttDiscoveryAsLock(
123 | Name := 'lock 001', (* The name show in Home Assistant frond-end*)
124 | Device := ADR(PLC_DEVICE), (* The device show in Home Assistant *)
125 | Invert := TRUE (* FALSE by default = NO, TRUE = NC *)
126 | );
127 | ```
128 |
129 | ### **Home Assistant YAML**
130 | If [MQTT discovery](../AdditionalFunctionality/MQTT_Discovery.md) is not working for you, you can use the YAML code below in your [MQTT lights](https://www.home-assistant.io/components/light.mqtt/) config:
131 |
132 | ```YAML
133 | mqtt:
134 | light:
135 | - name: "FB_DO_SW_001"
136 | state_topic: "Devices/PLC/House/Out/DigitalOutputs/FB_DO_SW_001"
137 | command_topic: "Devices/PLC/House/In/DigitalOutputs/FB_DO_SW_001"
138 | payload_on: "TRUE"
139 | payload_off: "FALSE"
140 | qos: 2
141 | optimistic: false
142 | availability_topic: "Devices/PLC/House/availability"
143 | payload_available: "online"
144 | payload_not_available: "offline"
145 | ```
--------------------------------------------------------------------------------
/docs/FunctionBlocks/FB_OUTPUT_BISTABLE_MQTT.md:
--------------------------------------------------------------------------------
1 | ## FB_OUTPUT_BISTABLE_MQTT
2 | 
3 |
4 | ### **General**
5 | Designed to control bistable relays, can be switched using pulses that are high for one clock cycle (for example from `FB_INPUT_PUSHBUTTON_MQTT`), requires a feedback loop from the bistable relay.
6 |
7 | ----------------------------
8 |
9 | :warning: Usage of this function block with a bistable relay requires a wired feedback loop from the relay to the PLC. Without it, it is not possible for the PLC to know the state of the relay and thus control it with `TRUE/FALSE` MQTT messages!
10 |
11 | ----------------------------
12 |
13 | ### **Block diagram**
14 |
15 | 
16 |
17 | INPUT(S)
18 | - FEEDBACK: feedback from the bistable input, should be high when the relay is turned on and low when turned off.
19 | - TOGGLE: when high the output `OUT` gets a pulse. input should one be high for one clockcycle.
20 | - PRIO_HIGH: when high and input `FEEDBACK` low, the output `OUT` gets a pulse. Has priority over the `TOGGLE` and `PRIO_LOW` input.
21 | - PRIO_LOW: when high and input `FEEDBACK` low, the output `OUT` gets a pulse. Has priority over the `TOGGLE` input.
22 |
23 | OUTPUT(S)
24 | - OUT: pulse output to control a bistable relay.
25 |
26 | METHOD(S)
27 | - InitMQTT: enables MQTT events on the FB, an overview of the parameters:
28 | - `MQTTPublishPrefix`: datatype *POINTER TO STRING*, pointer to the MQTT publish prefix that should be used for publishing any messages/events for this FB. Suffix is automatically set to FB name.
29 | - `MQTTSubscribePrefix`: datatype *POINTER TO STRING*, pointer to the MQTT subscribe prefix that should be used for publishing any messages/events to this FB. Suffix is automatically set to FB name.
30 | - `pMqttPublishQueue`: datatype *POINTER TO FB_MqttPublishQueue*, pointer to the MQTT queue to publish messages.
31 | - `pMqttCallbackCollector`: datatype *SD_MQTT.CallbackCollector*, pointer to the MQTT callback collector, required to register FB for subscriptions on a certain topic.
32 |
33 | - PublishReceived: callback method called by the callbackcollector when a message is received on the subscribed topic by the callbackcollector.
34 |
35 | - ConfigureFunctionBlock: configures the behaviour of output `OUT` using the parameters below:
36 | - `T_Hold`: duration of the pulse generated on output `OUT` to switch the bistable relais.
37 |
38 | ### **MQTT publish behavior**
39 | Requires method call `InitMQTT` to enable MQTT capabilities.
40 |
41 | | Event | Description | MQTT payload | QoS | Retain flag | Published on startup |
42 | |:-------------|:------------------|:------------------|:------------------|:--------------------------|:--------------------------|
43 | | **Input changes: FEEDBACK** | A change is detected on input `FEEDBACK`. | `TRUE/FALSE` | 2 | `TRUE` | yes
44 |
45 | MQTT publish topic is a concatination of the publish prefix and the function block name.
46 |
47 | ### **MQTT subscribe behavior**
48 | Requires method call `InitMQTT` to enable MQTT capabilities.
49 | Commands are executed by the FB if the topic `MQTTSubscribeTopic` matches the MQTT topic and the payload exists in the table below.
50 |
51 | | Command | Description | expected payload | Additional notes |
52 | |:-------------|:------------------|:------------------|:------------------|
53 | | **Change output to high** | Request to generate a pulse on output `OUT` if input `FEEDBACK` is low. | `TRUE` | Command executed when `PRIO_HIGH` and `PRIO_LOW` inputs are low.
54 | | **Change output to low** | Request to generate a pulse on output `OUT` if input `FEEDBACK` is high. | `FALSE` | Command executed when `PRIO_HIGH` and `PRIO_LOW` inputs are low.
55 |
56 | MQTT subscription topic is a concatenation of the subscribe prefix variable and the function block name.
57 |
58 | ### **Code example**
59 |
60 | - variables initiation:
61 | ```
62 | MQTTPubSwitchPrefix :STRING(100) := 'Devices/PLC/House/Out/DigitalOutputs/';
63 | MQTTSubSwitchPrefix :STRING(100) := 'Devices/PLC/House/In/DigitalOutputs/';
64 | FB_DO_BISTABLE_001 :FB_OUTPUT_BISTABLE_MQTT;
65 | ```
66 |
67 | - Init MQTT method call (called once during startup):
68 | ```
69 | FB_DO_BISTABLE_001.InitMQTT(MQTTPublishPrefix:= ADR(MQTTPubSwitchPrefix), (* pointer to string prefix for the MQTT publish topic *)
70 | MQTTSubscribePrefix:= ADR(MQTTSubSwitchPrefix), (* pointer to string prefix for the MQTT subscribe topic *)
71 | pMQTTPublishQueue := ADR(MQTTVariables.fbMQTTPublishQueue), (* pointer to MQTTPublishQueue to send a new MQTT event *)
72 | pMQTTCallbackCollector := ADR(MQTTVariables.collector_FB_OUTPUT_SWITCH_MQTT) (* pointer to CallbackCollector to receive MQTT subscription events *)
73 | );
74 | ```
75 | The MQTT publish topic in this code example will be `Devices/PLC/House/Out/DigitalOutputs/FB_DO_BISTABLE_001` (MQTTPubSwitchPrefix variable + function block name). The subscription topic will be `Devices/PLC/House/In/DigitalOutputs/FB_DO_BISTABLE_001` (MQTTSubSwitchPrefix variable + function block name).
76 |
77 |
78 | - checking for events to switch the digital output (cyclic):
79 | ```
80 | FB_DO_BISTABLE_001(OUT=> DO_001, (* couple the function block to the physical output *)
81 | PRIO_HIGH:= FALSE, (* brings the output high regardless of other input values *)
82 | PRIO_LOW:= FALSE (* brings the output low regardless of other input values. NOTE: Priohigh overrules Priolow input *)
83 | TOGGLE:= FB_DI_PB_009.SINGLE, (* for toggling the output *)
84 | FEEDBACK:= DI_001 (* feedback input, required to know state *)
85 | );
86 | ```
87 |
88 | - integration with `FB_INPUT_PUSHBUTTON_MQTT`:
89 | ```
90 | FB_DO_BISTABLE_001(OUT=> DO_001, (* couple the function block to the physical output *)
91 | PRIO_HIGH:= FALSE, (* brings the output high regardless of other input values *)
92 | PRIO_LOW:= FALSE, (* brings the output low regardless of other input values. NOTE: Priohigh overrules Priolow input *)
93 | TOGGLE:= FB_DI_PB_001.SINGLE, (* for toggling the output *)
94 | FEEDBACK:= DI_001 (* feedback input, required to know state *)
95 | );
96 | ```
97 | - MQTT discovery (choose one):
98 | ```
99 | (* switch entity *)
100 | FB_DO_BISTABLE_001.InitMqttDiscoveryAsSwitch(
101 | Name := 'switch 001', (* The name show in Home Assistant frond-end*)
102 | Device := ADR(PLC_DEVICE), (* The device show in Home Assistant *)
103 | );
104 |
105 | (* light entity *)
106 | FB_DO_BISTABLE_001.InitMqttDiscoveryAsLight(
107 | Name := 'light 001', (* The name show in Home Assistant frond-end*)
108 | Device := ADR(PLC_DEVICE), (* The device show in Home Assistant *)
109 | );
110 |
111 | (* siren entity *)
112 | FB_DO_BISTABLE_001.InitMqttDiscoveryAsSiren(
113 | Name := 'siren 001', (* The name show in Home Assistant frond-end*)
114 | Device := ADR(PLC_DEVICE), (* The device show in Home Assistant *)
115 | );
116 |
117 | (* lock entity *)
118 | FB_DO_BISTABLE_001.InitMqttDiscoveryAsLock(
119 | Name := 'lock 001', (* The name show in Home Assistant frond-end*)
120 | Device := ADR(PLC_DEVICE), (* The device show in Home Assistant *)
121 | );
122 | ```
123 |
124 | By default a 'NO' (Normally Open) contact is asumed for MQTT discovery yet this can be inverted to a 'NC' (Normally Closed) contact by leveraging the 'Invert' parameter:
125 |
126 | ```
127 | FB_DO_BISTABLE_001.InitMqttDiscoveryAsLock(
128 | Name := 'lock 001', (* The name show in Home Assistant frond-end*)
129 | Device := ADR(PLC_DEVICE), (* The device show in Home Assistant *)
130 | Invert := TRUE (* FALSE by default = NO, TRUE = NC *)
131 | );
132 | ```
133 |
134 | ### **Home Assistant YAML**
135 | If [MQTT discovery](../AdditionalFunctionality/MQTT_Discovery.md) is not working for you, you can use the YAML code below in your [MQTT lights](https://www.home-assistant.io/components/light.mqtt/) config:
136 |
137 | ```YAML
138 |
139 | mqtt:
140 | light:
141 | - name: "FB_DO_BISTABLE_001"
142 | state_topic: "Devices/PLC/House/Out/DigitalOutputs/FB_DO_BISTABLE_001"
143 | command_topic: "Devices/PLC/House/In/DigitalOutputs/FB_DO_BISTABLE_001"
144 | payload_on: "TRUE"
145 | payload_off: "FALSE"
146 | qos: 2
147 | optimistic: false
148 | availability_topic: "Devices/PLC/House/availability"
149 | payload_available: "online"
150 | payload_not_available: "offline"
151 | ```
--------------------------------------------------------------------------------
/docs/FunctionBlocks/FB_PLC_MQTT_DISCOVERY_DEVICE.md:
--------------------------------------------------------------------------------
1 | ## FB_PLC_MQTT_DISCOVERY_DEVICE
2 |
3 | INPUT(S)
4 |
5 | OUTPUT(S)
6 |
7 | METHOD(S)
8 | - initDevice: collects all device info once
9 | - `url` this sets the url to your PLC.
10 | - `availabilityTopic` : topic to publish availability;
11 | - `availabilityOnline`: the word to puslish when the plc is online;
12 | - `availabilityOffline`: the word to puslish when the plc is offline;
13 |
14 |
15 | ### **Code example**
16 | - variables initiation:
17 | ```
18 | PLC_device :FB_PLC_MQTT_DISCOVERY_DEVICE;
19 | ```
20 |
21 | - Init MQTT method call (called once during startup):
22 | ```
23 | PLC_Device.initPlcDevice(
24 | MqttDiscoveryPrefix := MqttVariables.MqttHADiscoveryPrefix,
25 | pMqttPublishQueue := ADR(MqttVariables.fbMqttPublishQueue),
26 | availabilityTopic := MqttVariables.MqttAvailabilityTopic,
27 | availabilityOnline := MqttVariables.MqttAvailabilityOnlinePayload,
28 | availabilityOffline := MqttVariables.MqttAvailabilityOfflinePayload
29 | );
30 | ```
31 |
32 |
33 | ## Device info in Home Assistant
34 |
35 | Device name:
36 | - open device structure
37 | - change controller
38 |
39 | App desc/auth:
40 | - edit application settings
41 |
42 | Time last start:
43 | - autogenerated last time the `ecp` was saved
44 |
45 | Device:
46 | - autogenerated from hardware
47 |
48 |
49 | 
--------------------------------------------------------------------------------
/docs/FunctionBlocks/FB_RS485_BUSCONTROLLER.md:
--------------------------------------------------------------------------------
1 | ## FB_RS485_BUSCONTROLLER
2 |
3 | ### **General**
4 | Used to control the RS485 bus in order to allow only one device with one Modbus RTU query at the time. In addition it manages the silence time on the bus between two requests and is capable of introducing a startup delay to allow devices on the bus to start up on power cycles.
5 |
6 | ### **Block diagram**
7 |
8 | 
9 |
10 | OUTPUT(S):
11 | - BusOcupied: datatype bool, indicates whether the RS485 bus is occupied or not.
12 |
13 | METHOD(S)
14 | - Init: configures the buscontroller, an overview of the parameters:
15 | - `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.
16 | - `SilenceTime`: datatype *TIME*, the silence time between two requests. Typically 10-20ms.
17 | - `BusTrigger`: datatype *POINTER TO BOOL*, boolean controlling bus actions.
18 | - `BusData`: datatype *POINTER TO ARRAY [0..124] OF WORD*, array containing bus read data.
19 | - `BusError`: datatype *POINTER TO BOOL*, boolean indicating bus error.
20 | - SetBusOccupied: used internally to set the RS485 bus as occupied.
21 | - ReleaseBus: used internally to release the RS485 bus.
22 |
23 | ### **Code example**
24 |
25 | - variables initiation:
26 | ```
27 | RS485BusController : FB_RS485_BUSCONTROLLER;
28 | ```
29 |
30 | - Init method call -é!COCKPIT version- (called once during startup):
31 | ```
32 | RS485BusController.Init(
33 | StartupDelay := T#5S, (* Time to wait after startup to start using the bus, prevents boot delay issues when RS485 are not ready yet on startup *)
34 | SilenceTime := T#50MS, (* Silence time between two requests, important to not get faulty data on bus *)
35 | BusTrigger := ADR(Trigger), (* Pointer to the bool used to initiate bus requests *)
36 | BusData := ADR(RtuResponse.awData), (* Pointer to the array containing the bus response data *)
37 | BusError := ADR(ModbusMaster.xError)(* Pointer to the bus error bool *)
38 | );
39 | ```
40 |
41 | - Init method call -Codesys 3S version- (called once during startup):
42 | ```
43 | RS485BusController.Init(
44 | StartupDelay := T#5S, (* Time to wait after startup to start using the bus, prevents boot delay issues when RS485 are not ready yet on startup *)
45 | SilenceTime := T#50MS, (* Silence time between two requests, important to not get faulty data on bus *)
46 | BusTrigger := ADR(Trigger), (* Pointer to the bool used to initiate bus requests *)
47 | BusData := ADR(awReadBuffer), (* Pointer to the array containing the bus response data *)
48 | BusError := ADR(xComPortError) (* Pointer to the bus error bool *)
49 | );
50 | ```
51 |
52 | - Adding a device to the bus (called once during startup):
53 | ```
54 | RS485BusController.RegisterDevice(device := FB_RS485_EASTRON_SDM220_1);
55 | ```
--------------------------------------------------------------------------------
/docs/FunctionBlocks/FB_RS485_EASTRON_SDM_POWER_MQTT.md:
--------------------------------------------------------------------------------
1 | ## FB_RS485_EASTRON_SDM_POWER_MQTT
2 |
3 | ### **General**
4 | Used to process Modbus RTU data through RS485 to human understandable values and publish data updates through MQTT if desired.
5 | This function block aims to read power consumption from a range of Eastron SDM power meters. Currently the Eastron SDM120, SDM220 and SDM630 are supported.
6 |
7 | Eastron SDM120 datasheets:
8 | - [Manual](../RS485/datasheets/SDM120_Manual.pdf)
9 | - [Modbus registers](../RS485/datasheets/SDM120_Modbus_Registers.pdf)
10 |
11 | Eastron SDM220 datasheets:
12 | - [Manual](../RS485/datasheets/SDM220_Manual.pdf)
13 | - [Modbus registers](../RS485/datasheets/SDM220_Modbus_Registers.pdf)
14 |
15 | Eastron SDM630 datasheet:
16 | - [Manual and Modbus registers](../RS485/datasheets/SDM630-Modbus-V2.pdf)
17 |
18 | ### **Block diagram**
19 |
20 | 
21 |
22 | OUTPUT(S):
23 | - ACTIVEPOWER: datatype real.
24 | - DataAvailable: datatype bool, high when data is available read by modbus read commando. This means the output is only low on startup until modbus read commando has been executed successfully.
25 | - Error: datatype bool, high when an error occured while executing modbus read commando.
26 |
27 | METHOD(S)
28 | - InitMQTT: enables MQTT events on the FB, an overview of the parameters:
29 | - `MQTTPublishPrefix`: datatype *POINTER TO STRING*, pointer to the MQTT publish prefix that should be used for publishing any messages/events for this FB. Suffix is automatically set to FB name.
30 | - `pMqttPublishQueue`: datatype *POINTER TO FB_MqttPublishQueue*, pointer to the MQTT queue to publish messages.
31 | - `pMqttCallbackCollector`: datatype _POINTER TO MQTT.CallbackCollector, pointer to the MQTT callback collector to receive subscribe messages.
32 | - InitRS485: configures the Modbus RTU device address and the execution/polling interval for the modbus read command.
33 | - RequestBusTime: method implemented by each RS485 device function block. More information in the [RS485Device interface docs](../RS485/RS485Device_Interface.md).
34 | - GetRtuQuery: method implemented by each RS485 device function block. More information in the [RS485Device interface docs](../RS485/RS485Device_Interface.md).
35 | - ProcessDataArray: method implemented by each RS485 device function block. More information in the [RS485Device interface docs](../RS485/RS485Device_Interface.md).
36 |
37 | ### **MQTT publish behavior**
38 | Requires method call `InitMQTT` to enable MQTT capabilities.
39 |
40 | | Event | Description | MQTT payload | QoS | Retain flag | Published on startup |
41 | |:-------------|:------------------|:------------------|:------------------|:--------------------------|:--------------------------|
42 | | **output is updated** | the output is updated. | real value | 2 | `FALSE` | no
43 |
44 | MQTT publish topic is a concatenation of the publish prefix and the function block name and a unique value:
45 | | output | MQTT topc suffic | Unit |
46 | |:-------------|:------------------|:------------------|
47 | | ACTIVEPOWER | `/ACTP` | Watts
48 |
49 | ### **Code example**
50 |
51 | - variables initiation:
52 | ```
53 | MQTTPubRS485Prefix :STRING(100) := 'Devices/PLC/House/Out/RS485/';
54 | FB_RS485_EASTRON_SDM_POWER_001 :FB_RS485_EASTRON_SDM_POWER_MQTT;
55 | ```
56 |
57 | - Init RS485 method call (called once during startup):
58 | ```
59 | FB_RS485_EASTRON_SDM_POWER_001.InitRS485(
60 | DataPollingInterval := T#15S, (* Polling interval for data array *)
61 | DeviceAddress := 1, (* Device address of the modbus device *)
62 | DeviceType := RS485_EASTRON_SDM_Devices.SDM630 (* Type of Eastron SDM device *)
63 | );
64 | ```
65 |
66 | - Init MQTT method call (called once during startup):
67 | ```
68 | FB_RS485_EASTRON_SDM_POWER_001.InitMqtt(
69 | MQTTPublishPrefix:= ADR(MqttRS485Prefix), (* pointer to string prefix for the mqtt publish topic *)
70 | pMqttPublishQueue := ADR(MqttVariables.fbMqttPublishQueue) (* pointer to MqttPublishQueue to send a new Mqtt event *)
71 | );
72 |
73 | ```
74 | The MQTT publish topic in this code example will be `Devices/PLC/House/Out/RS485/FB_RS485_EASTRON_SDM_POWER_001` (MQTTPubSwitchPrefix variable + function block name).
75 |
76 | - Registering device to a buscontroller (called once during startup):
77 | ```
78 | RS485BusController.RegisterDevice(device := FB_RS485_EASTRON_SDM_POWER_001);
79 | ```
80 |
81 | ### **Home Assistant YAML**
82 | To integrate with Home Assistant use the YAML code below in your [MQTT sensors](https://www.home-assistant.io/components/sensor.mqtt/) config:
83 |
84 | ```YAML
85 | mqtt:
86 | sensor:
87 | - name: "car charger power"
88 | object_id: "car_charger_power"
89 | state_topic: "Devices/PLC/House/Out/RS485/FB_RS485_EASTRON_SDM_POWER_001/ACTP"
90 | unit_of_measurement: "W"
91 | device_class: "power"
92 | state_class: "measurement"
93 | qos: 2
94 | availability:
95 | - topic: "Devices/PLC/House/Out/RS485/FB_RS485_EASTRON_SDM_POWER_001/availability"
96 | - topic: "Devices/PLC/House/availability"
97 | availability_mode : "all"
98 | payload_available: "online"
99 | payload_not_available: "offline"
100 | ```
101 |
102 | In addition to the above a [Riemann sum integral](https://www.home-assistant.io/integrations/integration/) integration can be added to calculate the energy (kWh) from the power (W):
103 | ```YAML
104 | - platform: integration
105 | source: sensor.car_charger_power
106 | name: "car charger energy"
107 | unit_prefix: k
108 | round: 3
109 | ```
--------------------------------------------------------------------------------
/docs/FunctionBlocks/FB_RS485_ESERA_1WIRE_GATEWAY_MQTT.md:
--------------------------------------------------------------------------------
1 | ## FB_RS485_ESERA_1WIRE_GATEWAY_MQTT
2 |
3 | ### **General**
4 | Designed to communicate with [Esera](https://esera.de/) 1-Wire modbus gateway this functionality allows pulling data from an extensive 1-Wire network in the PLC and publish updates through MQTT if desired.
5 |
6 | Esera supports and produces a wide range of 1-Wire devices; indoor/outdoor temperature sensors, humidity sensors, brightness sensors, air quality sensors, etc.
7 |
8 | Required hardware:
9 |
10 | [1-Wire Gateway 10 Modbus RTU](https://esera.de/en/Produkte/11324/1-Wire-Gateway-10-Modbus-RTU): [manual](../RS485/datasheets/Esera_ModbusGateway10_Manual.pdf), [wiring](../RS485/datasheets/Esera_ModbusGateway10_Wiring.pdf), [software](https://download.esera.de/download/technical/config%20tool%203)
11 |
12 | ### **Modbus configuration**
13 | The Esera gateways & controllers use a fixed communication baudrate of 19200 with a 8N1 bit configuration making it a dominant slave device in terms of configuration. Make sure any other Modbus devices on the network are able to leverage the same settigs.
14 |
15 | The slave id of the gateway is configurable by setting the controller number in the Esera configuration tool.
16 |
17 | ### **OWD**
18 | The gateway exposes 30 so called "OWD's" (One Wire Devices). The Esera configtool allows assigning a specific and static OWD number to a sensor. This allows the user to create a sensormap, for example: 'OWD1: temperature sensor living room'.
19 |
20 | Programmatically each OWD is represented by a [FB_RS485_ESERA_OWD_MQTT](FB_RS485_ESERA_OWD_MQTT.md) function block where the sensor data is processed to.
21 |
22 | ### **Code example**
23 |
24 | - variables initiation:
25 | ```
26 | MqttRS485Prefix : STRING(100) := 'Devices/PLC/Home/Out/RS485/';
27 | FB_RS485_ESERA_1WIRE_GATEWAY_MQTT_HOME : FB_RS485_ESERA_1WIRE_GATEWAY_MQTT;
28 | ```
29 |
30 | - Init RS485 method call (called once during startup):
31 | ```
32 | FB_RS485_ESERA_1WIRE_GATEWAY_MQTT_HUIS.InitRS485(
33 | DeviceAddress := 2
34 | );
35 | ```
36 |
37 | - Init MQTT method call (called once during startup):
38 | ```
39 | FB_RS485_ESERA_1WIRE_GATEWAY_MQTT_HOME.InitMqtt(
40 | MQTTPublishPrefix:= ADR(MqttRS485Prefix),
41 | pMqttPublishQueue := ADR(MqttVariables.fbMqttPublishQueue)
42 | );
43 | ```
44 | The MQTT publish topic in this code example will be `Devices/PLC/Home/Out/RS485/FB_RS485_ESERA_1WIRE_GATEWAY_MQTT_HOME` (MQTTPubSwitchPrefix variable + function block name).
45 |
46 | - Registering device to a buscontroller (called once during startup):
47 | ```
48 | RS485BusController.RegisterDevice(device := FB_RS485_ESERA_1WIRE_GATEWAY_MQTT_HOME);
49 | ```
50 |
--------------------------------------------------------------------------------
/docs/FunctionBlocks/FB_RS485_ESERA_OWD_MQTT.md:
--------------------------------------------------------------------------------
1 | ## FB_RS485_ESERA_OWD_MQTT
2 |
3 | ### **General**
4 | Represents a single One Wire Device (OWD) on the 1-Wire bus network.
5 | The following 1-Wire devices are currently supported:
6 |
7 | | Device | Devicecode | exports | link |
8 | |:-------------|:------------------|:------------------|:------------------|
9 | | Maxim integrated DS1820 & DS18B20 | 1820 | temperature | [link](https://www.analog.com/media/en/technical-documentation/data-sheets/ds18b20.pdf)
10 | | Esera multisensor Pro 1 | 11151 | air quality, humidity, temperature | [link](https://esera.de/en/Produkte/11151/1-Wire-Multisensor-Air-Quality-Humidity-and-Temperature-Pro-I)
11 | | Esera multisensor Pro 2 | 11152 | air quality, humidity, temperature | [link](https://esera.de/en/Produkte/11152/1-Wire-Multisensor-Air-Quality-Humidity-and-Temperature-Sensor-Pro-II)
12 | | Esera temperature sensor living space Pro | 11148 | humidity, temperature | [link](https://esera.de/en/Produkte/11148/1-Wire-temperature-sensor-living-space-Pro)
13 | | Esera MSP 105 multisensor Pro Air Humidity and Temperature Sensor | 11150 | humidity, temperature | [link](https://esera.de/en/Produkte/11150/MSP-105-1-Wire-Multisensor-Pro-Air-Humidity-and-Temperature-Sensor)
14 | | Esera multisensor Pro temperature, humidity living room flush-mounted for Berker, Jung, Merten | 11160 | humidity, temperature | [link](https://esera.de/en/Produkte/11160.3/1-Wire-Multisensor-Pro-temperature-humidity-living-room-flush-mounted-for-Berker-Jung-Merten)
15 | | Esera MS105 multisensor temperature, humidity living room flush-mounted for Berker, Jung, Merten | 11132 | humidity, temperature, brightness | [link](https://esera.de/en/Produkte/11132.3/MS105-1-Wire-Multisensor-temperature-humidity-living-room-flush-mounted-for-Berker-Jung-Merten-Kopie)
16 | | Esera multisensor for temperature, humidity, brightness, indoor, surface | 11134 | humidity, temperature, brightness | [link](https://esera.de/en/Produkte/11134/1-Wire-multi-sensor-for-temperature-humidity-brightness-indoor-surface)
17 |
18 |
19 | Note that the Esera documents the full list of supported devices over here: [link](https://esera.de/en/Produkte/11324/1-Wire-Gateway-10-Modbus-RTU). Yet, only the devices are above are supported in the software due to lack of actual testing devices.
20 | Nevertheless, adding a new device is a simple task, feel free to reach out.
21 |
22 | ### **Block diagram**
23 |
24 | 
25 |
26 | ### **MQTT publish behavior**
27 | Requires method call `InitMQTT` to enable MQTT capabilities.
28 |
29 | | Event | Description | MQTT payload | QoS | Retain flag | Published on startup |
30 | |:-------------|:------------------|:------------------|:------------------|:--------------------------|:--------------------------|
31 | | **sensor data is received** | temperature, humidity, etc readings received. | real value | 2 | `FALSE` | no
32 |
33 | MQTT publish topic is a concatenation of the publish prefix and the function block name, the OWD number and a unique sensor value. For example:
34 |
35 | `Devices/PLC/House/Out/RS485/FB_RS485_ESERA_1WIRE_GATEWAY_MQTT_HOME/OWD/1/TEMP`
36 |
37 | Naturally `/TEMP` will only be omitted by the OWD if the physical sensor exposes it.
38 |
39 | | output | MQTT topc suffic | Unit |
40 | |:-------------|:------------------|:------------------|
41 | | TEMPERATURE | `/TEMP` | °C
42 | | HUMIDITY | `/HUM` | %
43 | | OWD_VOLTAGE | `/OWDV` | V
44 | | AIR_QUALITY | `/AIRQ` | ppm
45 | | DEW_POINT | `/DEWP` | °C
46 | | BRIGHTNESS | `/BNESS` | Lux
47 |
48 | ### **Code example**
49 |
50 | - Enabling the OWD & configuring the OWD polling interval (called once during startup using the managing gateway function block):
51 | ```
52 | FB_RS485_ESERA_1WIRE_GATEWAY_MQTT_HOME.EnableOwd(
53 | OwdNumber := 1,
54 | DataPollingInterval := T#2M
55 | );
56 | ```
57 |
58 | ### **Home Assistant YAML**
59 | To integrate with Home Assistant use the YAML code below in your [MQTT sensors](https://www.home-assistant.io/components/sensor.mqtt/) config. Adopt where necessary depending on the exposed values of your OWD.
60 |
61 | ```YAML
62 |
63 | mqtt:
64 | sensor:
65 | - name: "temperature kitchen"
66 | object_id: "kitchen_temp"
67 | state_topic: "Devices/PLC/House/Out/RS485/FB_RS485_ESERA_1WIRE_GATEWAY_MQTT_HOME/OWD/1/TEMP"
68 | unit_of_measurement: "°C"
69 | qos: 2
70 | availability:
71 | - topic: "Devices/PLC/House/Out/RS485/FB_RS485_ESERA_1WIRE_GATEWAY_MQTT_HOME/OWD/1/availability"
72 | - topic: "Devices/PLC/House/availability"
73 | availability_mode : "all"
74 | payload_available: "online"
75 | payload_not_available: "offline"
76 | ```
--------------------------------------------------------------------------------
/docs/FunctionBlocks/FB_VIRTUAL_BOOL_MQTT.md:
--------------------------------------------------------------------------------
1 | ## FB_VIRTUAL_BOOL_MQTT
2 |
3 | ### **General**
4 | A virtual function block can be used in one of two modes:
5 | - input: inputs a value in the PLC processing logic through MQTT.
6 | - output: outputs a value from the PLC processing logic through MQTT.
7 |
8 | ### **Block diagram**
9 |
10 | 
11 |
12 | INPUT(S)
13 | - IN: datatype *BOOL*, input for the value that should be published through MQTT, provision this input when using the virtual function block in output mode.
14 |
15 | OUTPUT(S)
16 | - OUT: datatype *BOOL*, output for the value that is received through the MQTT subscription. provision this output in other processing logic when using the virtual function block in input mode.
17 |
18 | METHOD(S)
19 | - ConfigureFunctionBlockAsVirtualInput: configures the behaviour of the function block as a virtual input using the parameters below:
20 | - `DefaultValue`: datatype *BOOL*, value to set at startup if default value at startup behavior is configured.
21 | - `SetDefaultValueStartup`: datatype *BOOL*, set to TRUE to set the DefaultValue at PLC startup.
22 | - `PublishAtStartup`: datatype *BOOL*, set to TRUE to get an MQTT publish message of the virtual input value at PLC startup.
23 | - `UsePersistentAtStartup`: datatype *BOOL*, set to TRUE to use persistence to maintain the virtual input value through power cycles.
24 | - `ConfirmReceival`: datatype *BOOL*, set to TRUE to get an MQTT publish message when the value is updated.
25 |
26 | - ConfigureFunctionBlockAsVirtualOutput: configures the behaviour of the function block as a virtual output using the parameters below:
27 | - `PublishAtStartup`: datatype *BOOL*, set to TRUE to get an MQTT publish message of the virtual output value at PLC startup.
28 |
29 | - InitMQTT: enables MQTT events on the FB, an overview of the parameters:
30 | - `MQTTPublishPrefix`: datatype *POINTER TO STRING*, pointer to the MQTT publish prefix that should be used for publishing any messages/events for this FB. Suffix is automatically set to FB name.
31 | - `MQTTSubscribePrefix`: datatype *POINTER TO STRING*, pointer to the MQTT subscribe prefix that should be used for publishing any messages/events to this FB. Suffix is automatically set to FB name.
32 | - `pMqttPublishQueue`: datatype *POINTER TO FB_MqttPublishQueue*, pointer to the MQTT queue to publish messages.
33 | - `pMqttCallbackCollector`: datatype *SD_MQTT.CallbackCollector*, pointer to the MQTT callback collector, required to register FB for subscriptions on a certain topic.
34 | - `MqttQos`: datatype *SD_MQTT.QoS*, configures the MQTT Qos for the function block published messages.
35 | - `MqttRetain`: datatype *BOOL*, configures the MQTT retain flag for the function block published messages.
36 |
37 | - PublishReceived: callback method called by the callbackcollector when a message is received on the subscribed topic by the callbackcollector.
38 |
39 | - SetValue: method to set the function block virtual value, only works if the function block is in output mode.
40 |
41 |
42 | ### **MQTT publish behavior**
43 | Requires method call `InitMQTT` to enable MQTT capabilities. Only applicable if the function block is configured in output mode, outputting the value on input `IN` or set using the SetValue method through MQTT.
44 |
45 | | Event | Description | MQTT payload | QoS | Retain flag | Published on startup |
46 | |:-------------|:------------------|:------------------|:------------------|:--------------------------|:--------------------------|
47 | | **input changes: IN** | A change is detected on input `IN`. | `TRUE/FALSE` | configured in method call `InitMQTT` | configured in method call `InitMQTT` | configured in method call `InitMQTT`
48 |
49 | MQTT publish topic is a concatenation of the publish prefix and the function block name.
50 |
51 | ### **MQTT subscribe behavior**
52 | Requires method call `InitMQTT` to enable MQTT capabilities. Only applicable is the function block is configured in input mode which will allow the input of a value to the PLC through MQTT which will be exposed on the function block `OUT` output.
53 | Commands are executed by the FB if the topic `MQTTSubscribeTopic` matches the MQTT topic and the payload exists in the table below.
54 |
55 | | Command | Description | expected payload | Additional notes |
56 | |:-------------|:------------------|:------------------|:------------------|
57 | | **Change output to high** | Request to change output to high. | `TRUE` |
58 | | **Change output to low** | Request to change output to low. | `FALSE` |
59 |
60 | MQTT subscription topic is a concatenation of the subscribe prefix variable and the function block name.
61 |
62 | ### **Code example**
63 |
64 | - variables initiation:
65 | ```
66 | MqttPubVirtualPrefix :STRING(100) := 'Devices/PLC/House/Out/Virtuals/';
67 | MqttSubVirtualPrefix :STRING(100) := 'Devices/PLC/House/In/Virtuals/';
68 | FB_VIRTUAL_BOOL_001 :FB_VIRTUAL_BOOL_MQTT;
69 | ```
70 |
71 | - Init MQTT method call (called once during startup):
72 | ```
73 | FB_VIRTUAL_BOOL_001.InitMqtt(MQTTPublishPrefix:= ADR(MqttPubVirtualPrefix),
74 | MQTTSubscribePrefix:= ADR(MqttSubVirtualPrefix),
75 | pMqttPublishQueue := ADR(MqttVariables.fbMqttPublishQueue),
76 | pMqttCallbackCollector := ADR(MqttVariables.collector_FB_VIRTUAL_MQTT),
77 | MqttQos:=SD_MQTT.QoS.ExactlyOnce,
78 | MqttRetain:=FALSE
79 | );
80 | ```
81 | The MQTT publish topic in this code example will be `Devices/PLC/House/Out/Virtuals/FB_VIRTUAL_BOOL_001` (MQTTPubSwitchPrefix variable + function block name). The subscription topic will be `Devices/PLC/House/In/Virtuals/FB_VIRTUAL_BOOL_001` (MQTTSubSwitchPrefix variable + function block name).
82 |
83 |
84 | - Configuring the function block as a virtual input (called once during startup):
85 | ```
86 | FB_VIRTUAL_BOOL_001.ConfigureFunctionBlockAsVirtualInput(DefaultValue:=FALSE,
87 | SetDefaultValueStartup:=TRUE,
88 | PublishAtStartup:=TRUE,
89 | UsePersistentAtStartup:=FALSE,
90 | ConfirmReceival:=TRUE
91 | );
92 | ```
93 |
94 | - Calling the virtual function block to allow processing (cyclic):
95 | ```
96 | FB_VIRTUAL_BOOL_001();
97 | ```
98 |
99 | - Using the virtual function block value when using input mode (cyclic):
100 | ```
101 | X:=FB_VIRTUAL_BOOL_001.OUT;
102 | ```
103 | A value X in the PLC is set to the OUT value of the virtual function block, the OUT value being controlled through MQTT.
104 |
105 | - Using the virtual function block value when using output mode (cyclic):
106 | ```
107 | FB_VIRTUAL_BOOL_001.IN:=X;
108 | ```
109 | A value X in the PLC is set to the IN value of the virtual function block, the IN value being published through MQTT.
110 |
111 | ### **Home Assistant YAML**
112 |
113 | When using the function block as a virtual output use the YAML code below in your [MQTT Sensor](https://www.home-assistant.io/integrations/sensor.mqtt/) config to integrate with Home Assistant:
114 |
115 | ```YAML
116 | - platform: mqtt
117 | name: "FB_VIRTUAL_BOOL_001"
118 | state_topic: "Devices/PLC/House/Out/Virtuals/FB_VIRTUAL_BOOL_001"
119 | qos: 2
120 | availability_topic: "Devices/PLC/House/availability"
121 | payload_available: "online"
122 | payload_not_available: "offline"
123 | ```
124 |
125 | When using the function block as a virtual input use the YAML code below in your [MQTT Switch](https://www.home-assistant.io/integrations/switch.mqtt/) config to integrate with Home Assistant:
126 |
127 | ```YAML
128 | mqtt:
129 | switch:
130 | - name: "FB_VIRTUAL_BOOL_001"
131 | command_topic: "Devices/PLC/House/In/Virtuals/FB_VIRTUAL_BOOL_001"
132 | payload_on: "TRUE"
133 | payload_off: "FALSE"
134 | qos: 2
135 | optimistic: true
136 | availability_topic: "Devices/PLC/House/availability"
137 | payload_available: "online"
138 | payload_not_available: "offline"
139 | ```
140 |
--------------------------------------------------------------------------------
/docs/FunctionBlocks/FB_VIRTUAL_INT_MQTT.md:
--------------------------------------------------------------------------------
1 | ## FB_VIRTUAL_INT_MQTT
2 |
3 | ### **General**
4 | A virtual function block can be used in one of two modes:
5 | - input: inputs a value in the PLC processing logic through MQTT.
6 | - output: outputs a value from the PLC processing logic through MQTT.
7 |
8 | ### **Block diagram**
9 |
10 | 
11 |
12 | INPUT(S)
13 | - IN: datatype *INT*, input for the value that should be published through MQTT, provision this input when using the virtual function block in output mode.
14 |
15 | OUTPUT(S)
16 | - OUT: datatype *INT*, output for the value that is received through the MQTT subscription. provision this output in other processing logic when using the virtual function block in input mode.
17 |
18 | METHOD(S)
19 | - ConfigureFunctionBlockAsVirtualInput: configures the behaviour of the function block as a virtual input using the parameters below:
20 | - `DefaultValue`: datatype *INT*, value to set at startup if default value at startup behavior is configured.
21 | - `SetDefaultValueStartup`: datatype *BOOL*, set to TRUE to set the DefaultValue at PLC startup.
22 | - `PublishAtStartup`: datatype *BOOL*, set to TRUE to get an MQTT publish message of the virtual input value at PLC startup.
23 | - `UsePersistentAtStartup`: datatype *BOOL*, set to TRUE to use persistence to maintain the virtual input value through power cycles.
24 | - `ConfirmReceival`: datatype *BOOL*, set to TRUE to get an MQTT publish message when the value is updated.
25 |
26 | - ConfigureFunctionBlockAsVirtualOutput: configures the behaviour of the function block as a virtual output using the parameters below:
27 | - `PublishAtStartup`: datatype *BOOL*, set to TRUE to get an MQTT publish message of the virtual output value at PLC startup.
28 |
29 | - InitMQTT: enables MQTT events on the FB, an overview of the parameters:
30 | - `MQTTPublishPrefix`: datatype *POINTER TO STRING*, pointer to the MQTT publish prefix that should be used for publishing any messages/events for this FB. Suffix is automatically set to FB name.
31 | - `MQTTSubscribePrefix`: datatype *POINTER TO STRING*, pointer to the MQTT subscribe prefix that should be used for publishing any messages/events to this FB. Suffix is automatically set to FB name.
32 | - `pMqttPublishQueue`: datatype *POINTER TO FB_MqttPublishQueue*, pointer to the MQTT queue to publish messages.
33 | - `pMqttCallbackCollector`: datatype *SD_MQTT.CallbackCollector*, pointer to the MQTT callback collector, required to register FB for subscriptions on a certain topic.
34 | - `MqttQos`: datatype *SD_MQTT.QoS*, configures the MQTT Qos for the function block published messages.
35 | - `MqttRetain`: datatype *BOOL*, configures the MQTT retain flag for the function block published messages.
36 |
37 | - PublishReceived: callback method called by the callbackcollector when a message is received on the subscribed topic by the callbackcollector.
38 |
39 | - SetValue: method to set the function block virtual value, only works if the function block is in output mode.
40 |
41 |
42 | ### **MQTT publish behavior**
43 | Requires method call `InitMQTT` to enable MQTT capabilities. Only applicable if the function block is configured in output mode, outputting the value on input `IN` or set using the SetValue method through MQTT.
44 |
45 | | Event | Description | MQTT payload | QoS | Retain flag | Published on startup |
46 | |:-------------|:------------------|:------------------|:------------------|:--------------------------|:--------------------------|
47 | | **input changes: IN** | A change is detected on input `IN`. | `TRUE/FALSE` | configured in method call `InitMQTT` | configured in method call `InitMQTT` | configured in method call `InitMQTT`
48 |
49 | MQTT publish topic is a concatenation of the publish prefix and the function block name.
50 |
51 | ### **MQTT subscribe behavior**
52 | Requires method call `InitMQTT` to enable MQTT capabilities. Only applicable is the function block is configured in input mode which will allow the input of a value to the PLC through MQTT which will be exposed on the function block `OUT` output.
53 | Commands are executed by the FB if the topic `MQTTSubscribeTopic` matches the MQTT topic and the payload exists in the table below.
54 |
55 | | Command | Description | expected payload | Additional notes |
56 | |:-------------|:------------------|:------------------|:------------------|
57 | | **Change output to integer value** | Request to change output to a specific integer value. | an integer value |
58 |
59 | MQTT subscription topic is a concatenation of the subscribe prefix variable and the function block name.
60 |
61 | ### **Code example**
62 |
63 | - variables initiation:
64 | ```
65 | MqttPubVirtualPrefix :STRING(100) := 'Devices/PLC/House/Out/Virtuals/';
66 | MqttSubVirtualPrefix :STRING(100) := 'Devices/PLC/House/In/Virtuals/';
67 | FB_VIRTUAL_INT_001 :FB_VIRTUAL_INT_MQTT;
68 | ```
69 |
70 | - Init MQTT method call (called once during startup):
71 | ```
72 | FB_VIRTUAL_INT_001.InitMqtt(MQTTPublishPrefix:= ADR(MqttPubVirtualPrefix),
73 | MQTTSubscribePrefix:= ADR(MqttSubVirtualPrefix),
74 | pMqttPublishQueue := ADR(MqttVariables.fbMqttPublishQueue),
75 | pMqttCallbackCollector := ADR(MqttVariables.collector_FB_VIRTUAL_MQTT),
76 | MqttQos:=SD_MQTT.QoS.ExactlyOnce,
77 | MqttRetain:=FALSE
78 | );
79 | ```
80 | The MQTT publish topic in this code example will be `Devices/PLC/House/Out/Virtuals/FB_VIRTUAL_INT_001` (MQTTPubSwitchPrefix variable + function block name). The subscription topic will be `Devices/PLC/House/In/Virtuals/FB_VIRTUAL_INT_001` (MQTTSubSwitchPrefix variable + function block name).
81 |
82 |
83 | - Configuring the function block as a virtual input (called once during startup):
84 | ```
85 | FB_VIRTUAL_INT_001.ConfigureFunctionBlockAsVirtualInput(DefaultValue:=12,
86 | SetDefaultValueStartup:=TRUE,
87 | PublishAtStartup:=TRUE,
88 | UsePersistentAtStartup:=FALSE,
89 | ConfirmReceival:=TRUE
90 | );
91 | ```
92 |
93 | - Calling the virtual function block to allow processing (cyclic):
94 | ```
95 | FB_VIRTUAL_INT_001();
96 | ```
97 |
98 | - Using the virtual function block value when using input mode (cyclic):
99 | ```
100 | X:=FB_VIRTUAL_INT_001.OUT;
101 | ```
102 | A value X in the PLC is set to the OUT value of the virtual function block, the OUT value being controlled through MQTT.
103 |
104 | - Using the virtual function block value when using output mode (cyclic):
105 | ```
106 | FB_VIRTUAL_INT_001.IN:=X;
107 | ```
108 | A value X in the PLC is set to the IN value of the virtual function block, the IN value being published through MQTT.
109 |
110 | ### **Home Assistant YAML**
111 | When using the function block as a virtual output use the YAML code below in your [MQTT Sensor](https://www.home-assistant.io/integrations/sensor.mqtt/) config to integrate with Home Assistant:
112 |
113 | ```YAML
114 | mqtt:
115 | sensor:
116 | - name: "FB_VIRTUAL_INT_001"
117 | state_topic: "Devices/PLC/House/Out/Virtuals/FB_VIRTUAL_INT_001"
118 | qos: 2
119 | availability_topic: "Devices/PLC/House/availability"
120 | payload_available: "online"
121 | payload_not_available: "offline"
122 | ```
123 |
124 | When using the function block as a virtual input use the YAML code below in your [Input Number](https://www.home-assistant.io/integrations/input_number/) config to integrate with Home Assistant:
125 |
126 | ```YAML
127 | input_number:
128 | fb_virtual_int_001:
129 | name: friendly name
130 | min: 1
131 | max: 30
132 | step: 1
133 | unit_of_measurement: degrees
134 | icon: mdi:target
135 | ```
136 |
137 | Configure the automation below in your automations.yaml file to publish any changes on the Input Number slider on a MQTT topic:
138 |
139 | ```YAML
140 | - id: fb_virtual_int_001-to-mqtt
141 | alias: FB_VIRTUAL_INT_001 slider moved
142 | trigger:
143 | platform: state
144 | entity_id: input_number.fb_virtual_int_001
145 | action:
146 | service: mqtt.publish
147 | data_template:
148 | topic: 'Devices/PLC/House/In/Virtuals/FB_VIRTUAL_INT_001'
149 | retain: true
150 | payload: "{{ states('input_number.fb_virtual_int_001') | int }}"
151 | ```
--------------------------------------------------------------------------------
/docs/FunctionBlocks/FB_VIRTUAL_REAL_MQTT.md:
--------------------------------------------------------------------------------
1 | ## FB_VIRTUAL_REAL_MQTT
2 |
3 | ### **General**
4 | A virtual function block can be used in one of two modes:
5 | - input: inputs a value in the PLC processing logic through MQTT.
6 | - output: outputs a value from the PLC processing logic through MQTT.
7 |
8 | ### **Block diagram**
9 |
10 | 
11 |
12 | INPUT(S)
13 | - IN: datatype *REAL*, input for the value that should be published through MQTT, provision this input when using the virtual function block in output mode.
14 |
15 | OUTPUT(S)
16 | - OUT: datatype *REAL*, output for the value that is received through the MQTT subscription. provision this output in other processing logic when using the virtual function block in input mode.
17 |
18 | METHOD(S)
19 | - ConfigureFunctionBlockAsVirtualInput: configures the behaviour of the function block as a virtual input using the parameters below:
20 | - `DefaultValue`: datatype *REAL*, value to set at startup if default value at startup behavior is configured.
21 | - `SetDefaultValueStartup`: datatype *BOOL*, set to TRUE to set the DefaultValue at PLC startup.
22 | - `PublishAtStartup`: datatype *BOOL*, set to TRUE to get an MQTT publish message of the virtual input value at PLC startup.
23 | - `UsePersistentAtStartup`: datatype *BOOL*, set to TRUE to use persistence to maintain the virtual input value through power cycles.
24 | - `ConfirmReceival`: datatype *BOOL*, set to TRUE to get an MQTT publish message when the value is updated.
25 |
26 | - ConfigureFunctionBlockAsVirtualOutput: configures the behaviour of the function block as a virtual output using the parameters below:
27 | - `PublishAtStartup`: datatype *BOOL*, set to TRUE to get an MQTT publish message of the virtual output value at PLC startup.
28 |
29 | - InitMQTT: enables MQTT events on the FB, an overview of the parameters:
30 | - `MQTTPublishPrefix`: datatype *POINTER TO STRING*, pointer to the MQTT publish prefix that should be used for publishing any messages/events for this FB. Suffix is automatically set to FB name.
31 | - `MQTTSubscribePrefix`: datatype *POINTER TO STRING*, pointer to the MQTT subscribe prefix that should be used for publishing any messages/events to this FB. Suffix is automatically set to FB name.
32 | - `pMqttPublishQueue`: datatype *POINTER TO FB_MqttPublishQueue*, pointer to the MQTT queue to publish messages.
33 | - `pMqttCallbackCollector`: datatype *SD_MQTT.CallbackCollector*, pointer to the MQTT callback collector, required to register FB for subscriptions on a certain topic.
34 | - `MqttQos`: datatype *SD_MQTT.QoS*, configures the MQTT Qos for the function block published messages.
35 | - `MqttRetain`: datatype *BOOL*, configures the MQTT retain flag for the function block published messages.
36 |
37 | - PublishReceived: callback method called by the callbackcollector when a message is received on the subscribed topic by the callbackcollector.
38 |
39 | - SetValue: method to set the function block virtual value, only works if the function block is in output mode.
40 |
41 |
42 | ### **MQTT publish behavior**
43 | Requires method call `InitMQTT` to enable MQTT capabilities. Only applicable if the function block is configured in output mode, outputting the value on input `IN` or set using the SetValue method through MQTT.
44 |
45 | | Event | Description | MQTT payload | QoS | Retain flag | Published on startup |
46 | |:-------------|:------------------|:------------------|:------------------|:--------------------------|:--------------------------|
47 | | **input changes: IN** | A change is detected on input `IN`. | `TRUE/FALSE` | configured in method call `InitMQTT` | configured in method call `InitMQTT` | configured in method call `InitMQTT`
48 |
49 | MQTT publish topic is a concatenation of the publish prefix and the function block name.
50 |
51 | ### **MQTT subscribe behavior**
52 | Requires method call `InitMQTT` to enable MQTT capabilities. Only applicable is the function block is configured in input mode which will allow the input of a value to the PLC through MQTT which will be exposed on the function block `OUT` output.
53 | Commands are executed by the FB if the topic `MQTTSubscribeTopic` matches the MQTT topic and the payload exists in the table below.
54 |
55 | | Command | Description | expected payload | Additional notes |
56 | |:-------------|:------------------|:------------------|:------------------|
57 | | **Change output to float value** | Request to change output to a specific float value. | an float value |
58 |
59 | MQTT subscription topic is a concatenation of the subscribe prefix variable and the function block name.
60 |
61 | ### **Code example**
62 |
63 | - variables initiation:
64 | ```
65 | MqttPubVirtualPrefix :STRING(100) := 'Devices/PLC/House/Out/Virtuals/';
66 | MqttSubVirtualPrefix :STRING(100) := 'Devices/PLC/House/In/Virtuals/';
67 | FB_VIRTUAL_REAL_001 :FB_VIRTUAL_REAL_MQTT;
68 | ```
69 |
70 | - Init MQTT method call (called once during startup):
71 | ```
72 | FB_VIRTUAL_REAL_001.InitMqtt(MQTTPublishPrefix:= ADR(MqttPubVirtualPrefix),
73 | MQTTSubscribePrefix:= ADR(MqttSubVirtualPrefix),
74 | pMqttPublishQueue := ADR(MqttVariables.fbMqttPublishQueue),
75 | pMqttCallbackCollector := ADR(MqttVariables.collector_FB_VIRTUAL_MQTT),
76 | MqttQos:=SD_MQTT.QoS.ExactlyOnce,
77 | MqttRetain:=FALSE
78 | );
79 | ```
80 | The MQTT publish topic in this code example will be `Devices/PLC/House/Out/Virtuals/FB_VIRTUAL_REAL_001` (MQTTPubSwitchPrefix variable + function block name). The subscription topic will be `Devices/PLC/House/In/Virtuals/FB_VIRTUAL_REAL_001` (MQTTSubSwitchPrefix variable + function block name).
81 |
82 |
83 | - Configuring the function block as a virtual input (called once during startup):
84 | ```
85 | FB_VIRTUAL_REAL_001.ConfigureFunctionBlockAsVirtualInput(DefaultValue:=12.234,
86 | SetDefaultValueStartup:=TRUE,
87 | PublishAtStartup:=TRUE,
88 | UsePersistentAtStartup:=FALSE,
89 | ConfirmReceival:=TRUE
90 | );
91 | ```
92 |
93 | - Calling the virtual function block to allow processing (cyclic):
94 | ```
95 | FB_VIRTUAL_REAL_001();
96 | ```
97 |
98 | - Using the virtual function block value when using input mode (cyclic):
99 | ```
100 | X:=FB_VIRTUAL_REAL_001.OUT;
101 | ```
102 | A value X in the PLC is set to the OUT value of the virtual function block, the OUT value being controlled through MQTT.
103 |
104 | - Using the virtual function block value when using output mode (cyclic):
105 | ```
106 | FB_VIRTUAL_REAL_001.IN:=X;
107 | ```
108 | A value X in the PLC is set to the IN value of the virtual function block, the IN value being published through MQTT.
109 |
110 | ### **Home Assistant YAML**
111 | When using the function block as a virtual output use the YAML code below in your [MQTT Sensor](https://www.home-assistant.io/integrations/sensor.mqtt/) config to integrate with Home Assistant:
112 |
113 | ```YAML
114 | mqtt:
115 | sensor:
116 | - name: "FB_VIRTUAL_REAL_001"
117 | state_topic: "Devices/PLC/House/Out/Virtuals/FB_VIRTUAL_REAL_001"
118 | qos: 2
119 | availability_topic: "Devices/PLC/House/availability"
120 | payload_available: "online"
121 | payload_not_available: "offline"
122 | ```
123 |
124 | When using the function block as a virtual input use the YAML code below in your [Input Number](https://www.home-assistant.io/integrations/input_number/) config to integrate with Home Assistant:
125 |
126 | ```YAML
127 | input_number:
128 | fb_virtual_real_001:
129 | name: friendly name
130 | min: 1
131 | max: 30
132 | step: 0.1
133 | unit_of_measurement: degrees
134 | icon: mdi:target
135 | ```
136 |
137 | Configure the automation below in your automations.yaml file to publish any changes on the Input Number slider on a MQTT topic:
138 |
139 | ```YAML
140 | - id: fb_virtual_real_001-to-mqtt
141 | alias: FB_VIRTUAL_REAL_001 slider moved
142 | trigger:
143 | platform: state
144 | entity_id: input_number.fb_virtual_real_001
145 | action:
146 | service: mqtt.publish
147 | data_template:
148 | topic: 'Devices/PLC/House/In/Virtuals/FB_VIRTUAL_REAL_001'
149 | retain: true
150 | payload: "{{ states('input_number.fb_virtual_real_001') | float }}"
151 | ```
--------------------------------------------------------------------------------
/docs/FunctionBlocks/FB_VIRTUAL_STRING_MQTT.md:
--------------------------------------------------------------------------------
1 | ## FB_VIRTUAL_STRING_MQTT
2 |
3 | ### **General**
4 |
5 | A virtual function block can be used in one of two modes:
6 |
7 | - input: inputs a value in the PLC processing logic through MQTT.
8 | - output: outputs a value from the PLC processing logic through MQTT.
9 |
10 | ### **Block diagram**
11 |
12 | 
13 |
14 | INPUT(S)
15 |
16 | - IN: datatype _STRING_, input for the value that should be published through MQTT, provision this input when using the virtual function block in output mode.
17 |
18 | OUTPUT(S)
19 |
20 | - OUT: datatype _STRING_, output for the value that is received through the MQTT subscription. provision this output in other processing logic when using the virtual function block in input mode.
21 |
22 | METHOD(S)
23 |
24 | - ConfigureFunctionBlockAsVirtualInput: configures the behaviour of the function block as a virtual input using the parameters below:
25 |
26 | - `DefaultValue`: datatype _STRING_, value to set at startup if default value at startup behavior is configured.
27 | - `SetDefaultValueStartup`: datatype _BOOL_, set to TRUE to set the DefaultValue at PLC startup.
28 | - `PublishAtStartup`: datatype _BOOL_, set to TRUE to get an MQTT publish message of the virtual input value at PLC startup.
29 | - `UsePersistentAtStartup`: datatype _BOOL_, set to TRUE to use persistence to maintain the virtual input value through power cycles.
30 | - `ConfirmReceival`: datatype _BOOL_, set to TRUE to get an MQTT publish message when the value is updated.
31 |
32 | - ConfigureFunctionBlockAsVirtualOutput: configures the behaviour of the function block as a virtual output using the parameters below:
33 |
34 | - `PublishAtStartup`: datatype _BOOL_, set to TRUE to get an MQTT publish message of the virtual output value at PLC startup.
35 |
36 | - InitMQTT: enables MQTT events on the FB, an overview of the parameters:
37 | - `MQTTPublishPrefix`: datatype _POINTER TO STRING_, pointer to the MQTT publish prefix that should be used for publishing any messages/events for this FB. Suffix is automatically set to FB name.
38 | - `MQTTSubscribePrefix`: datatype _POINTER TO STRING_, pointer to the MQTT subscribe prefix that should be used for publishing any messages/events to this FB. Suffix is automatically set to FB name.
39 | - `pMqttPublishQueue`: datatype _POINTER TO FB_MqttPublishQueue_, pointer to the MQTT queue to publish messages.
40 | - `pMqttCallbackCollector`: datatype _SD_MQTT.CallbackCollector_, pointer to the MQTT callback collector, required to register FB for subscriptions on a certain topic.
41 | - `MqttQos`: datatype _SD_MQTT.QoS_, configures the MQTT Qos for the function block published messages.
42 | - `MqttRetain`: datatype _BOOL_, configures the MQTT retain flag for the function block published messages.
43 | - PublishReceived: callback method called by the callbackcollector when a message is received on the subscribed topic by the callbackcollector.
44 |
45 | - SetValue: method to set the function block virtual value, only works if the function block is in output mode.
46 |
47 | ### **MQTT publish behavior**
48 |
49 | Requires method call `InitMQTT` to enable MQTT capabilities. Only applicable if the function block is configured in output mode, outputting the value on input `IN` or set using the SetValue method through MQTT.
50 |
51 | | Event | Description | MQTT payload | QoS | Retain flag | Published on startup |
52 | | :-------------------- | :---------------------------------- | :----------- | :----------------------------------- | :----------------------------------- | :----------------------------------- |
53 | | **input changes: IN** | A change is detected on input `IN`. | `TRUE/FALSE` | configured in method call `InitMQTT` | configured in method call `InitMQTT` | configured in method call `InitMQTT` |
54 |
55 | MQTT publish topic is a concatenation of the publish prefix and the function block name.
56 |
57 | ### **MQTT subscribe behavior**
58 |
59 | Requires method call `InitMQTT` to enable MQTT capabilities. Only applicable is the function block is configured in input mode which will allow the input of a value to the PLC through MQTT which will be exposed on the function block `OUT` output.
60 | Commands are executed by the FB if the topic `MQTTSubscribeTopic` matches the MQTT topic and the payload exists in the table below.
61 |
62 | | Command | Description | expected payload | Additional notes |
63 | | :-------------------------------- | :--------------------------------------------------- | :--------------- | :--------------- |
64 | | **Change output to string value** | Request to change output to a specific string value. | a string value |
65 |
66 | MQTT subscription topic is a concatenation of the subscribe prefix variable and the function block name.
67 |
68 | ### **Code example**
69 |
70 | - variables initiation:
71 |
72 | ```
73 | MqttPubVirtualPrefix :STRING(100) := 'Devices/PLC/House/Out/Virtuals/';
74 | MqttSubVirtualPrefix :STRING(100) := 'Devices/PLC/House/In/Virtuals/';
75 | FB_VIRTUAL_STRING_001 :FB_VIRTUAL_STRING_MQTT;
76 | ```
77 |
78 | - Init MQTT method call (called once during startup):
79 |
80 | ```
81 | FB_VIRTUAL_STRING_001.InitMqtt(MQTTPublishPrefix:= ADR(MqttPubVirtualPrefix),
82 | MQTTSubscribePrefix:= ADR(MqttSubVirtualPrefix),
83 | pMqttPublishQueue := ADR(MqttVariables.fbMqttPublishQueue),
84 | pMqttCallbackCollector := ADR(MqttVariables.collector_FB_VIRTUAL_MQTT),
85 | MqttQos:=SD_MQTT.QoS.ExactlyOnce,
86 | MqttRetain:=FALSE
87 | );
88 | ```
89 |
90 | The MQTT publish topic in this code example will be `Devices/PLC/House/Out/Virtuals/FB_VIRTUAL_STRING_001` (MQTTPubSwitchPrefix variable + function block name). The subscription topic will be `Devices/PLC/House/In/Virtuals/FB_VIRTUAL_STRING_001` (MQTTSubSwitchPrefix variable + function block name).
91 |
92 | - Configuring the function block as a virtual input (called once during startup):
93 |
94 | ```
95 | FB_VIRTUAL_STRING_001.ConfigureFunctionBlockAsVirtualInput(DefaultValue:='helloworld',
96 | SetDefaultValueStartup:=TRUE,
97 | PublishAtStartup:=TRUE,
98 | UsePersistentAtStartup:=FALSE,
99 | ConfirmReceival:=TRUE
100 | );
101 | ```
102 |
103 | - Calling the virtual function block to allow processing (cyclic):
104 |
105 | ```
106 | FB_VIRTUAL_STRING_001();
107 | ```
108 |
109 | - Using the virtual function block value when using input mode (cyclic):
110 |
111 | ```
112 | X:=FB_VIRTUAL_STRING_001.OUT;
113 | ```
114 |
115 | A value X in the PLC is set to the OUT value of the virtual function block, the OUT value being controlled through MQTT.
116 |
117 | - Using the virtual function block value when using output mode (cyclic):
118 |
119 | ```
120 | FB_VIRTUAL_STRING_001.IN:=X;
121 | ```
122 |
123 | A value X in the PLC is set to the IN value of the virtual function block, the IN value being published through MQTT.
124 |
125 | ### **Home Assistant YAML**
126 |
127 | When using the function block as a virtual output use the YAML code below in your [MQTT Sensor](https://www.home-assistant.io/integrations/sensor.mqtt/) config to integrate with Home Assistant:
128 |
129 | ```YAML
130 | mqtt:
131 | sensor:
132 | - name: "FB_VIRTUAL_STRING_001"
133 | state_topic: "Devices/PLC/House/Out/Virtuals/FB_VIRTUAL_STRING_001"
134 | qos: 2
135 | availability_topic: "Devices/PLC/House/availability"
136 | payload_available: "online"
137 | payload_not_available: "offline"
138 | ```
139 |
140 | When using the function block as a virtual input use the YAML code below in your [Input Text](https://www.home-assistant.io/integrations/input_text/) config to integrate with Home Assistant:
141 |
142 | ```YAML
143 | input_text:
144 | fb_virtual_string_001:
145 | name: friendly name
146 | initial: Hello PLC!
147 | ```
148 |
149 | Configure the automation below in your automations.yaml file to publish any changes on the Input Text entity on a MQTT topic:
150 |
151 | ```YAML
152 | - id: fb_virtual_string_001-to-mqtt
153 | alias: FB_VIRTUAL_STRING_001 value changed
154 | trigger:
155 | platform: state
156 | entity_id: input_text.fb_virtual_string_001
157 | action:
158 | service: mqtt.publish
159 | data_template:
160 | topic: 'Devices/PLC/House/In/Virtuals/FB_VIRTUAL_STRING_001'
161 | retain: true
162 | payload: "{{ states('input_text.fb_virtual_string_001') | string }}"
163 | ```
164 |
--------------------------------------------------------------------------------
/docs/RS485/RS485Device_Interface.md:
--------------------------------------------------------------------------------
1 | ## RS485 Device Interface
2 |
3 | The RS485Device interface is a simple interface designed to guarantee the presence of several methods with a correct input and output type so the RS485 Function block can be used in both é!COCKPIT and Codesys 3S.
4 |
5 | The interface implements three methods:
6 | 1. RequestBusTime: Should check whether RS485 is initialized and if the function block requires the bus for executing a modbus command.
7 |
8 | 1. GetRtuQuery: Should return an RTU query to execute depending on the state of the interval timer(s). In case there are multiple Modbus RTU queries to be executed for a device the FB should keep track of the active RTU query.
9 |
10 | 1. ProcessDataArray: Should process the result returned by the RTU query returned by method 'GetRtuQuery'. In case there are multiple Modbus RTU queries to be executed for a device the correct one should be processed.
11 |
12 |
--------------------------------------------------------------------------------
/docs/RS485/UsingModbusRTU_CODESYS3S.md:
--------------------------------------------------------------------------------
1 | ## Using Modbus RTU with the CODESYS 3S runtime
2 |
3 | ### **Content**
4 | This page describes adding a modbus RTU device using the CODESYS 3S runtime.
5 | In case a function block for your specific device is not present yet in this project. Please consider reading the [RS485 tips and tricks](../FAQ/RS485_tips_and_tricks.md) page if this is your first time connecting a RS485 device.
6 |
7 | ### **Assign the PLC serial port to the PLC runtime**
8 | In order use the onboard PLC serial port from the PLC runtime this needs to be configured from the web based management tool:
9 |
10 | 
11 |
12 | Note that it's necessary to reboot the controller after a change to this setting.
13 |
14 | ### **Required libraries**
15 | Make sure the following libraries are present in the project:
16 | ```
17 | IoDrvModbus
18 | SysCom
19 | SysTypes2 Interfaces
20 | ```
21 |
22 | ### **Setting the serial mode on the PLC**
23 | Although the PLC serial port is already assigned to the PLC runtime it isn't configured yet in RS485 mode.
24 | To do so:
25 | 1. Open Codesys
26 | 1. Connect to your PLC
27 | 1. Use the PLC shell to set the serialmode to RS485:
28 |
29 | 
30 |
31 | Note that even when the serialmode is already set to RS485 it is adviced to explicitly do so again. This has proven to fix connectivity issues when first using RS485 on a controller.
32 |
33 | ### **Using code to access the RS485 serial port**
34 | The device configurator overview can be used to add modbus RTU slave devices but it doesn't allow for troubleshooting. Therefore it's preferable to use code to read out the Modbus RTU devices.
35 |
36 | A specific implementation example can be found inside the project:
37 |
38 | 
39 |
40 | As this project uses a 'é!COCKPIT first' approach the code that needs to be used withing a controller using the Codesys 3S runtime has been commented out.
41 | There are minor differences to the é!COCKPIT and Codesys 3S Modbus RTU implementation. Main reason for this is that both systems have different libraries containing different function blocks and types to work with Modbus RTU.
42 | Nevertheless, any RS485 function block developed in this project can be used in both the é!COCKPIT and Codesys 3S Modbus RTU approach.
--------------------------------------------------------------------------------
/docs/RS485/UsingModbusRTU_éCOCKPIT.md:
--------------------------------------------------------------------------------
1 | ## Using Modbus RTU with the é!COCKPIT runtime
2 |
3 | ### **Content**
4 | This page describes adding a modbus RTU device using the é!COCKPIT runtime.
5 | In case a function block for your specific device is not present yet in this project. Please consider reading the [RS485 tips and tricks](../FAQ/RS485_tips_and_tricks.md) page if this is your first time connecting a RS485 device.
6 |
7 | ### **Assign the PLC serial port to the PLC runtime**
8 | In order use the onboard PLC serial port from the PLC runtime this needs to be configured from the web based management tool:
9 |
10 | 
11 |
12 | Note that it's necessary to reboot the controller after a change to this setting.
13 |
14 | ### **Required libraries**
15 | Make sure the following libraries are present in the project:
16 | ```
17 | WagoAppPlcModbus
18 | ```
19 |
20 | ### **Using code to access the RS485 serial port**
21 | A specific implementation example can be found inside the project in the 'PLC_PRG_RS485' program.
22 |
23 |
24 |
--------------------------------------------------------------------------------
/docs/RS485/datasheets/DUCO_DUCOBOX_Modbus_Registers.pdf:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/MichielVanwelsenaere/HomeAutomation.CoDeSys3/142d843d1793334ca58b8826e49266a14f71159b/docs/RS485/datasheets/DUCO_DUCOBOX_Modbus_Registers.pdf
--------------------------------------------------------------------------------
/docs/RS485/datasheets/Esera_ModbusGateway10_Manual.pdf:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/MichielVanwelsenaere/HomeAutomation.CoDeSys3/142d843d1793334ca58b8826e49266a14f71159b/docs/RS485/datasheets/Esera_ModbusGateway10_Manual.pdf
--------------------------------------------------------------------------------
/docs/RS485/datasheets/Esera_ModbusGateway10_Wiring.pdf:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/MichielVanwelsenaere/HomeAutomation.CoDeSys3/142d843d1793334ca58b8826e49266a14f71159b/docs/RS485/datasheets/Esera_ModbusGateway10_Wiring.pdf
--------------------------------------------------------------------------------
/docs/RS485/datasheets/SDM120_Manual.pdf:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/MichielVanwelsenaere/HomeAutomation.CoDeSys3/142d843d1793334ca58b8826e49266a14f71159b/docs/RS485/datasheets/SDM120_Manual.pdf
--------------------------------------------------------------------------------
/docs/RS485/datasheets/SDM120_Modbus_Registers.pdf:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/MichielVanwelsenaere/HomeAutomation.CoDeSys3/142d843d1793334ca58b8826e49266a14f71159b/docs/RS485/datasheets/SDM120_Modbus_Registers.pdf
--------------------------------------------------------------------------------
/docs/RS485/datasheets/SDM220_Manual.pdf:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/MichielVanwelsenaere/HomeAutomation.CoDeSys3/142d843d1793334ca58b8826e49266a14f71159b/docs/RS485/datasheets/SDM220_Manual.pdf
--------------------------------------------------------------------------------
/docs/RS485/datasheets/SDM220_Modbus_Registers.pdf:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/MichielVanwelsenaere/HomeAutomation.CoDeSys3/142d843d1793334ca58b8826e49266a14f71159b/docs/RS485/datasheets/SDM220_Modbus_Registers.pdf
--------------------------------------------------------------------------------
/docs/RS485/datasheets/SDM630-Modbus-V2.pdf:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/MichielVanwelsenaere/HomeAutomation.CoDeSys3/142d843d1793334ca58b8826e49266a14f71159b/docs/RS485/datasheets/SDM630-Modbus-V2.pdf
--------------------------------------------------------------------------------
/docs/SoftwareArchitecture.md:
--------------------------------------------------------------------------------
1 | ## SoftwareArchitecture
2 |
3 | ### **General Overview**
4 | The software is designed to have a loosely coupled architecture making it possible to add new home automation functionality without the need to worry about the MQTT communication to much.
5 | This results in a task for the main home automation logic and a seperate task to handle the MQTT communication to the broker. A global variable list is used to share memory objects between the two tasks enabling communication.
6 |
7 | 
8 |
9 | ### **Main Task (PLC_PRG_MAIN)**
10 |
11 | The main task is build using a SFC (Sequential Function Chart) with the following actions:
12 |
13 | 
14 |
15 | 1. `MAIN_INIT`: action ran once at startup to init FB's with static values/references.
16 | 2. `READ_PUSHBUTTONS`: action ran continously to read out digital inputs (FB's used in this action assume usage of pushbutton).
17 | 3. `WRITE_SWITCHES`: action ran continously after `READ_PUSHBUTTONS` to switch outputs using the results from `READ_PUSHBUTTONS`.
18 |
19 | Each of the Function Blocks (FB's) used to read inputs and switch outputs has a reference to a `MQTTPublishQueue` which is used to queue events to send to the MQTT broker.
20 | The events are sent towards the broker in the MQTT Task which has a lower priority so it never interferes with the main task which does the critical work.
21 |
22 | ### **MQTT Task (PLC_PRG_MQTT)**
23 | The main task is build using a SFC (Sequential Function Chart) with the following actions:
24 |
25 | 
26 |
27 | 1. `MQTT_INIT`: action ran once at startup to init FB's with static values/references.
28 | 2. `MQTT_PUBLISH`: action ran continously to read the events to publish from the `MQTTPublishQueue`. Has a number of `MQTTPublishWorkers` who are able to send MQTT events simultanously.
29 | 3. `MQTT_SUBSCRIBE`: action ran continously after `MQTT_PUBLISH` to handle subscriptions.
30 |
31 | ### **Global Variable list MQTT (MQTTVariables)**
32 |
33 | Contains function blocks to enable communication between the main task and the MQTT task. For example:
34 | - `MQTTPublishQueue` FB where the main task queue's messages to be published.
35 | - Callbackcollectors FB's so FB's can register for a callback event in case a message is received on a topic.
--------------------------------------------------------------------------------
/docs/_drawio/FB_INPUT_BINARYSENSOR_MQTT.drawio:
--------------------------------------------------------------------------------
1 |