In our previous blog, we demonstrated how to seamlessly transfer a PLC program to an edge device's host filesystem using Portainer's Edge Configurations and spin up the CODESYS runtime container using Edge Stacks. In this post, we'll explore how to effortlessly integrate the PLC code (configs) into a Git repository and utilize docker-compose.yml to run the CODESYS runtime container, including the PLC program boot file within the container.
This blog guides you through the steps to easily onboard multiple edge devices using the auto-onboarding feature. You can then deploy a PLC program to a fleet of PLCs developed in the CODESYS IDE via Portainer's Edge Stacks. For this demo, we'll be using WAGO CC100 PLCs as our edge devices.
As a first step we onboard our edge devices onto the server the same as last time. Portainer’s Auto Onboarding feature will onboard many edge devices to a single server. The Fig.1 shows the architecture of connectivity from edge devices to a server.
Fig.1: Architecture of Portainer Server and Edge Devices for Auto Onboarding
To create the auto onboarding script in Portainer, navigate to the environment page of the Portainer server and click on the "Auto Onboarding" button. Set the agent to "Edge Agent Standard." The server details will be filled in automatically. Next, assign the remaining fields, such as Groups (for role-based access), Edge Groups, and Tags, to manage access. Provide an Edge ID generator function (e.g. uuidgen) so that Portainer can assign an identity within the Portainer platform. The edge ID generator retrieves the given identifier from the edge machine and assigns the corresponding name in the Portainer server as shown in figure 2 below.
Fig.2: Auto Onboarding Script generation
The Portainer server then generates an auto-onboarding script. This script is general for all new devices and can be deployed on each edge device via the CLI or other provisioning tools. Each device must have Docker installed as a prerequisite (WAGO Devices are delivered with Docker installed). Upon successful execution of the script, the edge devices are effectively onboarded to the "waiting room." Once the devices are in the waiting room, you can associate them with the dedicated edge group to complete the onboarding process as seen in the figure 3 below. The edge devices will then be visible as online on the homepage.
Fig.3: Waiting Room on the Portainer server
After successfully deploying the auto onboarding script on the edge machine, you will notice that the edge devices appear in the waiting room. Here, you need to assign them to specific edge groups or provide them with tags to systematically organize them into their respective groups to successfully onboard them onto the Portainer server.
CODESYS IDE is used to develop PLC code using a ladder diagram, which can then be deployed on edge devices or directly to a PLC using a USB-C cable. After creating a CODESYS program to control the WAGO CC100 PLC and testing it in the CODESYS runtime environment, you must create the boot application of the file as seen in the figure 4 below. A boot application file (.app) will be generated in the respective folder. This file needs to be deployed on the edge device to make the PLC operational. The program's operation is to blink the LEDs on the PLC. There are three different codes to perform this operation since, in this experiment, we are using three PLCs and we would like to recognize the three different programs later on just by looking at the devices.
Fig.4: Codesys IDE UI to create Boot Application
The CODESYS system generates two boot files: .app and .crc. Start by creating a GitHub repository and name a folder within it as configs. Since we have three different PLC boot application files, ensure that the folders inside the configs directory are named according to the "Portainer Edge ID," which can be found in the environment details of each edge device. The primary objective is to map the corresponding PLC program boot file to the relevant edge devices. This mapping is dynamically managed using the Portainer Edge identifier.
The GitHub repository link is provided below, and Figure 5 illustrates the organized structure of the repository, showing the configs folder along with the docker-compose.yaml file. For sure you can also use a different git repository provider than GitHub.
GitHub Repository: https://github.com/chebbs/codeys_final.git
Fig.5: GitHub repository for edge stack deployment, mapping boot file configs to Portainer Edge IDs as folder names
Now that the GitHub repository is ready, we can now deploy the application onto our edge devices. Make sure to add the edge devices to the respective edge group so that the deployment will be easy on the Portainer server platform. In our case I have named the edge group as Wago CC-100 Homelab where I have associated my edge devices to the group.
As discussed in our previous blog post, we explored running a CODESYS runtime container independently using the web editor. In this approach, the boot application files are embedded within the GitHub repository, as shown in the earlier steps. Additionally, the docker-compose.yml file orchestrates the deployment, ensuring that the configuration files are correctly placed on the appropriate edge devices and in the specified directories as required. Hence while creating an edge stack, we select repository and provide the repository details such as URL, branch and docker compose file details, as seen the figure 6 below.
Figure 6: Edge Stack deployment using repository
You can also enable the GitOps updates button to automate deploying updated versions of the stack based on a polling or webhook mechanism. This way, any changes made to the Git repository will be recognized by Portainer and reflected in your Edge Stack deployment. To utilize device-specific configurations, enable the GitOps Edge Configurations, and fill out the details such as the filesystem path on the host where the repository should be cloned, directory details where the config files are relative to the Git repository, and add any additional environment variables that may have been missed. The figure 7 below illustrates how you can configure the GitOps functionalities.
Please note: Make sure you are creating an empty directory in host file system. In my case I have created a “/home/codesys_root/PlcLogic/Application” directory and we have the compose unpacker image installed using ‘docker pull portainer/compose-unpacker:2.23.0’ command in PLC host file system.
Figure 7: GitOps Enablement and GitOps Edge Configuration details
It is best practice to enable “retry deployment” in case the deployment fails for any reason. There is also an option to enable parallel edge device(s) deployments when deploying to devices, allowing applications to be deployed concurrently to only a subset of devices at a time.
Once you have successfully deployed the stack, you can monitor it on the Edge Stack page. If the stack deployment is successful, the containers will be running on the edge devices, ready to receive the respective configuration boot files needed for specific operations. The architecture of the edge stack deployment is illustrated below in figure 8.
Figure 8: Architectural overview of CODESYS Runtime stack deployment on edge devices
The output of the PLC code can be seen in Figure 9 below, where the three PLCs have different LED blink actions. Imagine being able to control industrial equipment and deploy changes remotely, simplifying operations and making the process more efficient.
Figure 9: PLC LED Blinking in different frequencies
This demonstrates how you can easily onboard edge devices and deploy the necessary configurations to perform operations using Portainer’s Edge Stack feature with a single click. In this example, we have illustrated a simple case of deploying 3 PLC programs on a fleet of devices that control LED lights.
Portainer is versatile and can also be utilized to make changes in robotic operations within the manufacturing sector, modify data acquisition ports in DCS and SCADA systems, and manage to gather data from industrial assets like motors, turbines, pumps, and more.
Feel free to contact me to understand the detailed technicalities, I would be happy to get you equipped with Portainer for codesys application deployment directly onto the edge devices.