====== PlcTool ====== PlcTool is a command line tool, which is able to perform many functions known from the Mervis IDE. There are 4 variants – for Windows (x64) and for GNU/Linux (x64, ARM, ARM64). {{ :files:img_warning-line_b.png?nolink |}} {{ :en:hw:08_safety-instructions_pseudo-ISO-7010-info.png?nolink |(i)}} **Note:** \\ The main advantage of PlcTool over Mervis IDE is that it can be used by your own script or a program. ---- PlcTool can perform many actions with controllers that contain Mervis RT: * search for PLCs in selected network (defined by IPv4 address) * obtain information about a specific PLC on a specific address * upload a compiled solution (RT image) * update RT * license RT * download RT configuration * upload RT configuration * restart RT * upload HMI (web files) ===== Downloads ===== It is **necessary** to unpack the archive after download. * {{ :files:software:mervis:plctool:plctool-1.0.27-linux-arm64.zip |PlcTool - Linux ARM64 (1.0.27)}} * {{ :files:software:mervis:plctool:plctool-1.0.27-linux-arm.zip |PlcTool - Linux ARM32 (1.0.27)}} * {{ :files:software:mervis:plctool:plctool-1.0.27-linux-x64.zip |PlcTool - Linux x64 (1.0.27)}} * {{ :files:software:mervis:plctool:plctool-1.0.27-win-x64.zip |PlcTool - Windows x64 (1.0.27)}} **Obsolete** versions: * {{ :files:software:mervis:plctool:2023-11-01_plctool_linux-arm64.zip |PlcTool - Linux ARM64 (1.0.0)}} * {{ :files:software:mervis:plctool:2023-11-01_plctool_linux-arm.zip |PlcTool - Linux ARM32 (1.0.0)}} * {{ :files:software:mervis:plctool:2023-11-01_plctool_linux-x64.zip |PlcTool - Linux x64 (1.0.0)}} * {{ :files:software:mervis:plctool:2023-11-01_plctool_win-x64.zip |PlcTool - Windows x64 (1.0.0)}} ===== First run ===== ==== Windows ==== Only x64 version is available for Windows OS (64 bit OS). If there are problems running the tool, update the .NET Framework. ---- To run the PlcTool, you have to press ''%%WIN%%''+''%%R%%'' key combination, enter ''%%cmd.exe%%'' and press OK. In the command line, open the directory containing the ''%%PlcTool.exe%%'' and run command: .\PlcTool.exe --help ==== Linux ==== There are 3 CPU architectures available for GNU/Linux OS: x64, ARM and ARM64 (AArch64). It depends on the OS type you use on your device, eg. Neuron can run both 32 bit and 64 bit OS. No modifications or additional software needed. It is possible to transfer tool (file) directly to the PLC by SCP (eventually by WinSCP on Windows). ---- Then you have to open terminal in the folder containing ''%%PlcTool%%'' and set the file as executable (by command ''%%chmod +x PlcTool%%'') Depending on the system, PlcTool may require additional of packages (not needed for PlcTool 1.0.27 on Mervis OS 2.6.5.16 and newer): sudo apt install icu-devtools libssl-dev libssl1.1 and/or modifications to the environment, these can be done with this command: export DOTNET_SYSTEM_GLOBALIZATION_INVARIANT=1 DOTNET_BUNDLE_EXTRACT_BASE_DIR=/tmp/ ---- You can run the tool now by: ./PlcTool --help ===== Usage ===== Help can be shown by running the tool with the ''%%--help%%'' argument. This argument can also be used for subcommands (''scan'', ''wait'', etc.) to get specific help. {{ :files:img_warning-line_b.png?nolink |}} {{ :en:hw:08_safety-instructions_pseudo-ISO-7010-info.png?nolink |(i)}} **Note:** \\ All subcommands except ''scan'' allow to use mDNS, proxy or address of different server (domain) instead of IP. ==== Searching for PLC ==== If no parameters are specified when searching for a controller (subcommand ''scan''), searching will be done only locally (loopback). This is useful especially if Mervis RT is on the same device as PlcTool, i.e. on a Unipi PLC. ./PlcTool.exe scan ---- To discover all controllers on the network, it's first necessary to get the IP address of the interface to be searched. For the purpose of this tutorial, the network ''192.168.2.0'' is used /* You can find out IP address of Unipi units by executing ''ip a''. */ Device IP address (interface) is ''192.168.2.59'', use this address for PlcTool on Windows. {{ :files:img_warning-line_b.png?nolink |}} {{ :en:hw:09_safety-instructions_pseudo-ISO-7010-attention.png?nolink |(!)}} **Attention:** \\ **Currently** in GNU/Linux, it is not possible to use interface address, nor addresses ''192.168.2.0'' and ''192.168.2.255''. Appropriate option for most networks is an address ending by ''.1'' (last byte). To search the whole network, add arguments ''-ia'' with IP address after ''scan'' subcommand: ./PlcTool.exe scan -ia 192.168.2.1 Output: Mervis Plc Tool | scan Detecting Controllers 0% Detecting Controllers 0% Detecting Controllers 33% Detecting Controllers 66% Detecting Controllers 100% Detecting Controllers 100% Id Address Slave Addr. Serial Number License RT Version Platform Name 192.168.2.59:8010 1 0000601592700320 NotLicensed 2.5.2609.152085 Generic05/12416 192.168.2.19:8010 1 0000B827EBDB3CD0 NotLicensed 2.5.2609.152085 Generic05/257 Scan command result OK ==== Verifying PLC ==== Subcommand ''wait'' allows you to send a request and wait set duration of time for positive response. This request can verify the controller status, license status, RT version, name, or IP address. ---- If only the mDNS address is available, license verification can be used to locate the controller and confirm that it is actually available: ./PlcTool wait -h s103-sn999 -u admin -p rw -lok ==== Licensing and checking license ==== It is possible to upload the license to the controller by using subcommand ''license''. If the license has already been used, the previous activation result will be used by adding ''-up''. ./PlcTool license -h s103-sn999 -u admin -p rw -l MRTUA774VCVMMGN5 -up You may check the license by using subcommand ''wait'': ./PlcTool wait -h s103-sn999 -u admin -p rw -lok ==== Uploading solution ==== You need to obtain compiled program (image) with the **exs** extension first, so you can upload a solution. This file is created by compiling the solution in Mervis IDE in **bin** directory. Upload is done by ''upload-image'' subcommand: ./PlcTool upload-image -h s103-sn999 -u admin -p rw -f PLC_3a861d94-ad77-4db8-ae4e-711c6fd0a334.exs You can use additional commands when uploading a solution, the most significant are listed below: -cf, --clear-flash-variables Clear Flash Variables on Controller Restart [default: False] -cr, --cold-restart Run as Cold Restart [default: False] ==== Uploading website (HMI) ==== The name of folder with website files contains the name of the controller and the HMI template. This folder is available in the solution directory after compilation in Mervis IDE. Uploading is done by ''upload-web'' subcommand: ./PlcTool upload-web -h s103-sn999 -u admin -p rw -w HMI-PLC-local/ You have to restart controller (Mervis services) after uploading the website: ./PlcTool reboot -h s103-sn999 -u admin -p rw ==== Configuration ==== PlcTool compatible configuration is stored in XML format, so manual edits are easy. You can also change the configuration in Mervis IDE, uploading to PLC and the downloading by PlcTool, instead of editing the file manually. === Downloading configuration === A file with a selected name is created when downloading using subcommand ''download-config'': ./PlcTool download-config -h s103-sn999 -u admin -p rw -f ./config.xml === Uploading configuration === You have to use subcommand ''upload-config'' with XML file in order to upload the configuration: ./PlcTool upload-config -h s103-sn999 -u admin -p rw -f ./config.xml ===== Automated usage ===== PlcTool requires a physical console for its function, to use it automatically, you have to run it via ''script'' command. Following script calls ''PlcTool'' and writes its output to **PlcTool.txt** file. Alternatively, you can process the output in the script itself. #!/bin/bash cd "$(dirname "$0")" export DOTNET_SYSTEM_GLOBALIZATION_INVARIANT=1 DOTNET_BUNDLE_EXTRACT_BASE_DIR=/tmp/ script -q -c "./PlcTool scan -o text | tee PlcTool.txt" Script also sets required environment variables, so it can be called by another services. ==== Calling the script via systemd ==== We can create a service for automatic startup after system boot (or triggering by timer). We assume that script mentioned above and ''PlcTool'' are located in **/home/unipi/linux-arm** folder. Create **/etc/systemd/system/plctoolscan.service** file and write: [Unit] Description=PlcTool scanning [Service] ExecStart=/home/unipi/linux-arm/plcscript.sh Type=oneshot [Install] WantedBy=multi-user.target ---- Reloading systemd services is required now, use command: sudo systemctl daemon-reload the service can be run by a command: sudo systemctl start plctoolscan.service