PlantLogic: Roots, Branches, and Leafs - ResgreenGroup/Botway-Documentation GitHub Wiki

Current Location: RGR Products->PlantLogic-> Roots, Branches, and Leafs

Summary

This page describes the main structure of PlantLogic. PlantLogic's input and output data structures are called roots. Roots read from and write to the datastore. Once data is in the datastore, it can be used in comparisons for the trigger logic in the branches. Branches do not need to be associated with a root. When the condition associated with a branch evaluates to true, all the leafs on that branch will execute. Branches have toggleable options that allow for rising edge logic and continue-on-fail. Leafs must be associated with a root; each leaf can only be associated with one root, but one root can be used by multiple leafs. Leafs cause keys in the datastore to be modified through their linked roots.

Roots

Roots are data structures responsible for listening to external resources and updating the datastore. Any communication that occurs from PlantLogic to another device or resource must go through a root. There are 6 types of roots: MQTT, OPC, API, SQL, File Read, and File Write.

MQTT Root

These roots listen to topics hosted by an MQTT broker. PlantLogic is not sold with an MQTT broker. Click on the "Create New Root" button in the main toolbar, then select an MQTT root type and click "Add." When creating a new MQTT root, PlantLogic should look like figure 1 below.

Figure 1: New MQTT root in sample PlantLogic Project.

Fill in the Host field with the MQTT IP address. Fill in the Port field with the channel that communications will come through. Fill in the client ID field with the name that PlantLogic will publish to the MQTT broker under. Go down to the details field and press the "add" button. Fill in the Topic field with the topic pathway, then press the "Save" button in the details section. A root can subscribe to multiple topics. When subscribing to a topic, all subtopics will be displayed. All of the MQTT topics that PlantLogic's MQTT root subscribes to will appear in the "Items" section. Click the "Save" button at the top of the "Settings" section. The MQTT root will now listen to all topics supplied to it and fill the datastore with label-value pairs. The label will be the topic path and the value will be whatever is published to the broker under that topic path. Best practice is to have one MQTT root per port.

The MQTT root can be made to publish to the MQTT broker as well, but that is a property of Leafs. Reference the "Leafs" section of this wiki for instructions on publishing to the MQTT broker.

API root

The API root is used to communicate between PlantLogic and an external API. Create a new root and select the API option, then click "Add." Specify the port that communications will go through, and that is all that needs to be done for the API root. The "Last Sent" and "Last Received" fields will populate on their own and cannot be interacted with. Click "Save" in the settings toolbar to finalize the root. This root needs no additional customization. This root relies on API leafs; the leafs contain the URL for external API calls and direct the root to make the calls. Reference the "API Leaf" section of the wiki for instructions on making external API calls. In addition, PlantLogic has its own API that can get values from the datastore or write values to the datastore. Reference the "Leafs" section of this wiki for instructions about performing an external API call.

Figure 2: New API root in sample PlantLogic Project.

OPC root

PlantLogic is not sold with an OPC server; the OPC server must already be present in order to use the OPC root. The OPC root is used to communicate with external OPC servers. Create a new root, select the OPC root type, then click "Add." Fill in the Host field with the OPC server address, fill in the port field with the port of the server that is being contacted, fill in the client ID with the name that PlantLogic will publish to the OPC server under, and fill in the poll rate with the highest possible time that will still capture the desired data. Click the "Add" button in the "Details" toolbar, then fill in the "Tag" field with the topic or subtopic from the OPC server that is to be captured. Just like with the MQTT root, if a selected topic has several subtopics or several pieces of data, all of them will be added to the datastore. Finally, click the "Save" button in the "Details" toolbar, then click the "Save" button in the "Settings" toolbar. The "Items" field will populate with all tags associated with the OPC root and each root can be associated with several tags. Best practice is one root per server port. The root can now listen to the OPC server and fill the datastore with information. The OPC root can also publish to the OPC server. This is done using OPC leafs. Reference the "Leafs" section of this wiki for instructions to publish to OPC servers.

Figure 3: New OPC root in sample PlantLogic Project.

MySQL root

SQL roots listen to and publish to databases. SQL databases are not sold with PlantLogic. Click on the "add root" button in the main toolbar, select the MySQL type, then select "Add." Fill out the "Connection" field with a valid server connection string. Click here to see a list of valid connection string formats. Fill in the poll rate with the largest amount of time (in milliseconds) possible that will still catch changes in the data. . Last, click "Save" in the settings toolbar. Best practice is one root per database. PlantLogic can now listen to SQL databases and publish changes to them. In order to publish, PlantLogic needs a leaf linked to the SQL root. See the "Leafs" section of this wiki for instructions on publishing to a database using a leaf.

Figure 4: New SQL root in sample PlantLogic Project.

File Read root

File read roots can read any file type as long as the data structure uses label-value pairs. Each root can read one data type of the following three: .xml, .csv, and .json. File read roots allow PlantLogic to get information from data files. Add a new root and select the "File Read" root type, then click "Add" in the main toolbar. Fill in the "Folder Watched" field with the path to the folder that PlantLogic should listen to. Fill in the File Name With the name or names of files to be listened to in that folder. DOS wildcards can be used here in the file name or extension. Fill in the data type with one of the file extensions from the dropdown menu. The Details section contains a "Last Contents" window that fills with the last set of information read by the root. It will fill by itself and cannot be interacted with.

Figure 5: New File Read root in sample PlantLogic Project.

File Write root

File Write roots are the simplest root type. They allow PlantLogic to write data to a file. There is no limit to the size of the file that PlantLogic can generate. Add a new root and select the "File Write" root type, then click "Add." That is all that is needed. There is no settings section to customize, and the details section automatically fills with whatever was last written out to the destination file. Creating the root only makes the mechanism that allows PlantLogic to write to files. In order to specify what and where to write, a linked leaf is needed. Reference the "Leafs" section of this wiki for instructions on writing to files.

Figure 6: New File Write root in sample PlantLogic Project.

Socket Root

Socket roots are used for direct network connection via wireless network or ethernet cable. These roots communicate directly with the external resources without the aid of a broker or server. Fill in the IP address, port number, protocol format and poll rate of the external resource. The Protocol prefills with TCP or UDP. The poll rate should be as long as possible that still captures the data. There are no items or details in a socket root. Socket roots expect data to be structured in XML, csv, or JSON. Reference the Leafs section of this wiki for instructions on sending communications to external resources using the socket root.

Figure 7: New Socket root in sample PlantLogic Project.

Branches

Branches are the parts of PlantLogic where trigger logic is implemented. All created branches share the same format, shown in figure below. When a Branch's trigger logic evaluates to "true," PlantLogic will execute the leafs associated with that branch one by one from top to bottom based on the order in the plant layout in the top left of the application.

Figure : New Branch in sample PlantLogic Project.

Name the branch by entering something into the "Name" field. This will appear in the plant, shown in the top left of the application. The branches are between the main trunk and the roots. Filling in the "Description" field is optional; it will only be visible when the branch is selected. There are two toggleable boxes in the branch: One-Shot and Continue-on-Failure. The "One Shot" toggle is activated by default on each new branch. This toggle changes the branch to use rising edge conditions; it will only begin executing its leafs when the trigger condition turns from false to true. It will not fire again until after its condition becomes false. The "Continue on Failure" box is disabled by default. This means that if a leaf fails to execute, PlantLogic will stop executing that leaf and any leafs below it in the plant structure. When this toggle is enabled, PlantLogic will not stop executing leafs if one of them fails. It will attempt to execute every one of its associated leafs, even if all of them fail.

The main feature of the branch creation window is the large section for creating trigger logic. Using C# syntax and operators, create trigger conditions. The data used by the trigger logic is the information in the datastore. In order to use information from the datastore, use the expression "DS["label name"]" where is replaced with the name of the label whose value is to be used in the condition. A list of accepted operators can be found here. An example condition is "(DateTime.Parse(DS["Sys.Time"].ToString()).Second % 10) == 0" This condition will return 0 unless the seconds part of the timestamp is a multiple of 10, when it returns 1. Use the C# operators and the datastore information to create conditions and branches.

Branches will have sets of associated leafs. If a leaf is created under a branch, that leaf will execute when the branch's trigger logic evaluates to true, pending one shot and continue-on-fail checks.

Leafs

Leafs are sets of instructions to be carried out when their parent branch fires. These data structures tell their linked root to carry out the function assigned to the leaf. Create a new leaf by selecting the "New Leaf" option in the plant toolbar. It will only enable itself when a branch is selected. The customization section will fill with a blank new leaf template that looks like figure below.

Figure : New Leaf in sample PlantLogic Project.

Fill in the name and description of the leaf. The name will appear under the leaf's parent branch in the plant structure, and the description will show up when the leaf is selected. Assign the leaf to a root by using the "Linked Root" dropdown menu. Leafs cannot carry an action out or communicate with external resources by themselves. They rely on roots to do that. The settings section will change based on the linked root type.

Leafs linked to MQTT, API, or OPC roots all behave similarly and have the same settings section. These leafs do not need extra properties specified in the settings section. Create details for the leaf by selecting the "Add" button in the details section. For MQTT roots, specify the topic that PlantLogic will be publishing to in the key field, then select something from the datastore to publish. Use the datastore reference "DS["label name"]" and replace label name with a label from the datastore. When the leaf executes, the Data store reference will be replaced by the value associated with it. The "items" section will fill with all assigned topics.
For Leafs connected to API roots, fill in the key field with a description of the API method function. This will be the label that the returned value will be associated with in the datastore. Fill in the value field with the API request URL. An example is "http://127.0.0.1:3001/api/v1/getGreeting." The API leafs can use PlantLogic's API, which has 4 methods: getTime, getGreeting, getValue, and setValue. When contacting an external API, change the request URL to refer to the proper endpoint. The API root will write whatever the API returns to the datastore. The "items" field will fill with all assigned API calls.
For Leafs connected to OPC roots, fill in the key field with the tag that PlantLogic's OPC root will be publishing to. Fill in the value field with a datastore reference. Use the expression "DS["label name"]" and insert the label of something in the datastore. The OPC root will now publish to its specified OPC server when it fires.
For leafs connected to MySQL roots, additional information must be supplied to the settings section. In the "Table Name" field, write the name of the table that will be written to. The name, description, and linked root are the same as for all other leafs.
Leafs connected to File Read roots are unnecessary. When the root is created, the file to watch will be specified and the data store will populate with the contents of the file.
For leafs connected to File Write roots, Information on the destination and contents need to be supplied. Fill in the name and description of the leaf. then link the leaf to the file write root. Edit the "Settings" section and choose the file endpoint. This can be manually entered or selected from the file browser using the ellipsis next to the file name field. Specify the format using the "Format" dropdown menu. The data can be written in .json, .csv, .xml, or raw. Choose the operation type from the "Output" dropdown menu. PlantLogic can create new files, append the output to an existing file, or overwrite an existing file. When creating new files, PlantLogic will append the timestamp to the filename. The "Items" section will fill with the data being written to the file in the form of a list of label-value pairs. In the "Details" section, create the label value pairs. Click the "Edit" button in the settings section to enable the details toolbar. Add a new pair by clicking the "Add" button, then fill in the "Key" field with the label and the "Value" field with the data. The data store can be referenced here. Edit an existing pair by clicking on a pair in the "Items" section, then the "Edit" button in the "Details" section.
For leafs connected to Socket roots, fill in the name, description, and which root to link to. Then, add details using the "Add" button in the "Details" toolbar. Leafs that use the socket root are unlikely to have a data store element to send directly to the external resource, but they can be directed so send static label value pairs instead. Any data sent by a leaf linked to a socket root will be structured in JSON. Values from the datastore can be used in the value section of the details, but they do not have to be. Instead, enter the label name and static value that needs to be sent to the external resource. The value will not be dynamic, but it will work.