====== PlcTool ======

**PlcTool** is a standalone command-line utility capable of performing many functions available in the Mervis IDE. 

The main advantage of PlcTool over the standard IDE is its ability to be automated via **scripts** or external programs. It is ideal for batch management of controllers.

===== Downloads =====

Please download the appropriate version for your operating system and architecture below:

  * **Windows (x64):** [[https://drive.google.com/drive/u/0/folders/1DUvrbQAYkS-mICLPvo1raMqCVgHqRI4U|Download for Windows x64]]
  * **Linux (x64):** [[https://drive.google.com/drive/u/0/folders/1Iba_DBjlZU0s6dFEW0UjVzdHKV1gruDv|Download for Linux x64]]
  * **Linux (ARM):** [[https://drive.google.com/drive/u/0/folders/1cGMhBR3DnRUiR-PM5F-7Pj6BXkEmCDbX|Download for Linux ARM]]
  * **Linux (ARM64):** [[https://drive.google.com/drive/u/0/folders/1HPm10-7u7ZEeFP7iG6r5BcWKaGrX5m_G|Download for Linux ARM64]]

===== Key Features =====
PlcTool can perform the following actions on controllers running Mervis RT:
  * **Scan:** Search for PLCs on a selected network.
  * **Info:** Obtain status information about a specific PLC.
  * **Upload:** Upload compiled solutions (RT images) and HMI (web) projects.
  * **Update:** Update the Mervis RT version.
  * **License:** Apply or verify RT licenses.
  * **Configuration:** Download or upload RT configuration (XML).
  * **Control:** Restart the runtime.

===== Installation & First Run =====

The tool is distributed as an archive that must be unpacked after downloading.

==== Windows ====
  * **Requirement:** Windows x64. If issues occur, update your .NET Framework.
  * **How to run:**
    - Press `Win + R`, type `cmd.exe`, and press OK.
    - Navigate to the folder containing the unpacked tool.
    - Run the help command:
<code bash>
.\PlcTool.exe --help
</code>

==== GNU/Linux ====
  * **Supported Architectures:** x64, ARM, and ARM64 (AArch64).
  * **Setup:**
    - You can transfer the tool to the PLC via SCP or WinSCP.
    - Make the file executable: `chmod +x PlcTool`.
    - **Dependencies:** Depending on your system, you may need to install additional packages:
<code bash>
sudo apt install icu-devtools libssl-dev libssl1.1
</code>
    - **Environment Variables:** If necessary, export the following variables before running:
<code bash>
export DOTNET_SYSTEM_GLOBALIZATION_INVARIANT=1 
export DOTNET_BUNDLE_EXTRACT_BASE_DIR=/tmp/
</code>
  * **How to run:**
<code bash>
./PlcTool --help
</code>

===== Common Commands =====

**Note:** Most subcommands (except `scan`) accept mDNS names, proxy addresses, or domain names instead of IP addresses.

==== 1. Network Scan (scan) ====
  * **Local Scan:** If no parameters are specified, it searches locally (loopback).
<code bash>
./PlcTool scan
</code>
  * **Network Scan:** To search a specific network, use the `-ia` (Interface Address) argument.
    * //Note: On Linux, you cannot use the network address (e.g., .0) or broadcast (.255). Use an address ending in .1 (e.g., 192.168.2.1).//
<code bash>
./PlcTool scan -ia 192.168.2.1
</code>

==== 2. Verify Controller Status (wait) ====
Sends a request to verify controller status, license, and RT version.
<code bash>
./PlcTool wait -h <host_address> -u admin -p rw-lok
</code>

==== 3. Licensing (license) ====
Uploads a license code to the controller. Use `-up` if the license was already used previously.
<code bash>
./PlcTool license -h <host_address> -u admin -p rw -l <LICENSE_KEY> -up
</code>

==== 4. Upload Solution (upload-image) ====
Uploads a compiled program (`.exs` file found in the project's `bin` directory).
<code bash>
./PlcTool upload-image -h <host_address> -u admin -p rw -f <solution_guid>
</code>
  * **Useful flags:**
    * `-cf` : Clear Flash Variables
    * `-cr` : Cold Restart

==== 5. Upload HMI / Website (upload-web) ====
Uploads the web interface files. You must restart the controller after uploading.
<code bash>
./PlcTool upload-web -h <host_address> -u admin -p rw -w <web_folder>/
./PlcTool reboot -h <host_address> -u admin -p rw
</code>

==== 6. Configuration (download-config / upload-config) ====
Configuration is stored in XML format. You can download it, edit manually, and upload it back.
<code bash>
# Download
./PlcTool download-config -h <host_address> -u admin -p rw -f ./config.xml

# Upload
./PlcTool upload-config -h <host_address> -u admin -p rw -f ./config.xml
</code>

===== Automated Usage (Scripting) =====

PlcTool is designed for use in scripts. Below is an example Bash script that runs a scan and writes the output to a text file.

<code bash>
#!/bin/bash

# Navigate to script directory
cd "$(dirname "$0")"

# Set required environment variables
export DOTNET_SYSTEM_GLOBALIZATION_INVARIANT=1 DOTNET_BUNDLE_EXTRACT_BASE_DIR=/tmp/

# Run scan and pipe output to file
script -q -c "./PlcTool scan -o text | tee PlcTool.txt"
</code>