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

PlcTool je nástroj příkazové řádky, který umí řadu funkcí známých z Mervis IDE. Existují 4 varianty, pro Windows (x64) a pro Linux (x64, ARM, ARM64).
<WRAP group center round box 95%>
{{ :files:img_warning-line_b.png?nolink |}}
<WRAP half column 13%>
{{ :en:hw:08_safety-instructions_pseudo-ISO-7010-info.png?nolink |(i)}}
</WRAP>
<WRAP half column 83%>
**Poznámka:** \\
Hlavní výhodou nástroje PlcTool oproti Mervis IDE je, že jej lze využít ve vlastním skriptu či programu.
</WRAP>
</WRAP>

----

Nástroj umožňuje řadu operací s kontroléry obsahující Mervis RT:
  * vyhledat kontrolér ve zvolené síti (určené IPv4 adresou)
  * získat informace o konkrétním kontroléru na specifické adrese
  * nahrát zkompilovanou sestavu (image RT)
  * aktualizovat RT
  * licencovat RT
  * stáhnout konfiguraci RT
  * nahrát konfiguraci RT
  * restart RT
  * nahrát HMI (soubory webu)


===== Ke stažení =====
Po stažení vybrané varianty je **nutné** archiv rozbalit.

<WRAP center round box>
  * {{ :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)}}
</WRAP>


**Staré** verze:

  * {{ :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)}}
  * {{ :files:software:mervis:plctool:2023-11-01_plctool_linux-arm.zip |PlcTool - Linux ARM (1.0.0)}}
  * {{ :files:software:mervis:plctool:2023-11-01_plctool_linux-arm64.zip |PlcTool - Linux ARM64 (1.0.0)}}



===== První spuštění =====

==== Windows ====
Pro OS Windows je k dispozici pouze varianta x64 (64 bit OS). Pokud jsou se spuštěním nástroje potíže, aktualizujte .NET Framework.

----

Pro spuštění nástroje je zapotřebí jen stisknout kombinaci kláves ''%%WIN%%''+''%%R%%'', zadat ''%%cmd.exe%%'' a zvolit OK. Poté v příkazové řádce otevřít adresář obsahující ''%%PlcTool.exe%%'' a spustit příkazem:

<code>.\PlcTool.exe --help</code>


==== Linux ====
Pro OS Linux je nástroj k dispozici pro 3 různé architektury procesorů: x64, ARM a ARM64 (AArch64). Vždy záleží také na tom, jaká verze OS je na zařízení, např. na Neuron je možné nahrát 32 bit, ale také 64 bit operační systém.

<WRAP center round box 95%>
Přímo do kontroléru je možné nástroj (soubor) přenést pomocí nástroje SCP (popř. programem WinSCP ve Windows).
</WRAP>

----

Následně je nutné v terminálu otevřít adresář obsahující nástroj ''%%PlcTool%%'' a nastavit soubor jako spustitelný (příkazem ''%%chmod +x PlcTool%%''). 

V závislosti na systému, může PlcTool vyžadovat doplnění balíků (pro verzi 1.0.27 na Mervis OS 2.6.5.16 a novější není třeba):
<code>
sudo apt install icu-devtools libssl-dev libssl1.1
</code>

a/nebo úpravy prostředí, ty lze jednoduše provést příkazem:
<code>export DOTNET_SYSTEM_GLOBALIZATION_INVARIANT=1 DOTNET_BUNDLE_EXTRACT_BASE_DIR=/tmp/</code>

----

Nyní je nástroj možné spustit:

<code>./PlcTool --help</code>

===== Použití =====

Nápovědu je možné získat spuštěním nástroje s argumentem ''%%--help%%''. Tento argument lze použít i pro rozšířený příkaz (''scan'', ''wait'', atd.) a získat tak konkrétní nápovědu.

<WRAP group center round box 95%>
{{ :files:img_warning-line_b.png?nolink |}}
<WRAP half column 13%>
{{ :en:hw:08_safety-instructions_pseudo-ISO-7010-info.png?nolink |(i)}}
</WRAP>
<WRAP half column 83%>
**Poznámka:** \\
Všechny parametry kromě ''scan'' umožňují namísto IP adresy použít také mDNS, proxy, či adresu jiného serveru (doménu).
</WRAP>
</WRAP> 


==== Vyhledání kontroléru ====

Pokud při vyhledání kontroléru (parametr ''scan'') nejsou zadány žádné parametry, bude vyhledáváno pouze lokálně (loopback). Toho je možné využít pouze pokud je Mervis RT na stejném zařízení jako PlcTool, tedy na kontroléru Unipi.

<code>
./PlcTool.exe scan
</code>

----

Pro vyhledání všech kontrolérů na síti je nejprve nutné zjistit IP adresu rozhraní, na kterém se bude vyhledávat. Pro případy tohoto návodu je využita síť ''192.168.2.0''.

/* <WRAP center round box 95%>
U jednotek Unipi je možné zjistit IP adresy rozhraní příkazem ''ip a''.
</WRAP> */

IP adresa zařízení (rozhraní) je ''192.168.2.59'', ve Windows použijte pro PlcTool tuto adresu.
<WRAP group center round box 95%>
{{ :files:img_warning-line_b.png?nolink |}}
<WRAP half column 13%>
{{ :en:hw:09_safety-instructions_pseudo-ISO-7010-attention.png?nolink |(!)}}
</WRAP>
<WRAP half column 83%>
**Upozornění:** \\
V Linuxu není **aktuálně** možné adresu rozhraní, ani adresy ''192.168.2.0'' a ''192.168.2.255'' využít. Vhodnou volbou pro většinu sítí je proto IP adresa končící ''.1'' (poslední bajt).
</WRAP>
</WRAP>

K prohledání celé sítě se za parametr ''scan'' doplní ''-ia'' společně s IP adresou: 

<code>
./PlcTool.exe scan -ia 192.168.2.1
</code>

Výstup:

<code>
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   <unknown>
192.168.2.19:8010     1    0000B827EBDB3CD0  NotLicensed  2.5.2609.152085  Generic05/257     <unknown>
Scan command result OK
</code>


==== Ověření kontroléru ====

Parametr ''wait'' umožňuje odeslat požadavek a nastavený čas čekat na kladnou odpověď. Požadavkem lze ověřit stav kontroléru, stav licence, verzi RT, název, nebo IP adresu.

----

Pokud je k dispozici pouze mDNS adresa, lze pro vyhledání kontroléru a potvrzení, že je skutečně dostupný, využít ověření licence:

<code>
./PlcTool wait -h s103-sn999 -u admin -p rw -lok
</code>


==== Licencování a kontrola licence ====
Nahrát licenci do kontroléru je možné parametrem ''license''. Po doplnění ''-up'' se použije předchozí výsledek aktivace, pokud existuje.

<code>
./PlcTool license -h s103-sn999 -u admin -p rw -l MRTUA774VCVMMGN5 -up
</code>

Ověření licence umožňuje parametr ''wait'':

<code>
./PlcTool wait -h s103-sn999 -u admin -p rw -lok
</code>


==== Nahrání sestavy ====
Před nahráním sestavy je nutné získat kompilovaný program (image) s příponou **exs**. Tento soubor je vytvořen při kompilaci sestavy Mervis IDE v adresáři **bin**.

Nahrání se provádí parametrem ''upload-image'':

<code>
./PlcTool upload-image -h s103-sn999 -u admin -p rw -f PLC_3a861d94-ad77-4db8-ae4e-711c6fd0a334.exs
</code>

Příkaz pro nahrání sestavy je možné doplnit o další volby, nejvýznamnější jsou uvedeny níže:
<code>
 -cf, --clear-flash-variables      Vymazat proměnné flash [výchozí: False]
 -cr, --cold-restart               Spustit PLC jako po studeném restartu [výchozí: False]
</code>


==== Nahrání webu (HMI) ====
Název adresáře se soubory webu je složen z názvu kontroléru a názvu HMI šablony. Tento adresář je také součástí adresáře sestavy a je dostupný až po kompilaci.

Nahrání se provádí parametrem ''upload-web'':

<code>
./PlcTool upload-web -h s103-sn999 -u admin -p rw -w HMI-PLC-local/
</code>

Po nahrání webu je nutné kontrolér (služby Mervis) restartovat:

<code>
./PlcTool reboot -h s103-sn999 -u admin -p rw
</code>


==== Konfigurace ====
Konfigurace kompatibilní s nástrojem PlcTool je uložena v XML formátu, ruční editace je proto poměrně snadná. Alternativou k manuální editaci je konfigurace pomocí Mervis IDE a její následné stažení PlcToolem. 

=== Stažení konfigurace ===
Při stažení s parametrem ''download-config'' je vytvořen soubor se zvoleným názvem:
<code>
./PlcTool download-config -h s103-sn999 -u admin -p rw -f ./config.xml
</code>

=== Nahrání konfigurace ===
Pro nahrání je zapotřebí zadat parametr ''upload-config'' a soubor XML s konfigurací:
<code>
./PlcTool upload-config -h s103-sn999 -u admin -p rw -f ./config.xml
</code>


===== Automatizované použití =====

Nástroj PlcTool k funkci vyžaduje fyzickou konzoli, abyste jej mohli používat automatizovaně, je třeba jej spustit příkazem ''script''.

Následující skript zavolá ''PlcTool'' a zapíše jeho výstup do souboru **PlcTool.txt**. Alternativou je zpracovat výstup již v rámci skriptu.

<code>
#!/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"
</code>

Skript nastavuje také podmínky pro prostředí, takže může být volán jinými službami.


==== Volání skriptu pomocí systemd ====

Pro automatické spuštění při startu systému (nebo dle časovače) můžeme vytvořit službu. Předpokládáme, že výše uvedený skript i ''PlcTool'' se nachází ve složce **/home/unipi/linux-arm**.

Vytvoříme soubor **/etc/systemd/system/plctoolscan.service** a zapíšeme do něj:

<code>
[Unit]
Description=PlcTool scanning

[Service]
ExecStart=/home/unipi/linux-arm/plcscript.sh
Type=oneshot

[Install]
WantedBy=multi-user.target
</code>

----

Nyní je nutné provést obnovení služeb systemd příkazem:
<code>sudo systemctl daemon-reload</code> 

a můžeme službu spustit příkazem:
<code>sudo systemctl start plctoolscan.service</code>














/******************************

=== Ukázka XML souboru konfigurace ===

<code>
<hwconfiguration version="2">
  <runtime>
    <lwip>
      <ipv4 mode="dhcp" ipaddress="192.168.1.121" mask="255.255.255.0">
        <gateway>192.168.1.1</gateway>
        <dns>192.168.1.1</dns>
      </ipv4>
      <ipv6 />
    </lwip>
    <advanced niccount="0" />
    <configservice enabled="true" port="8010" />
    <httpservice enabled="true" port="80" redirect="0" />
    <httpsservice enabled="false" port="443" />
    <sscp>
      <slaveaddress>1</slaveaddress>
      <groupscount>5</groupscount>
      <groupvariablecount>20</groupvariablecount>
      <tcp enabled="true" port="12346" />
      <serial enabled="false" port="1" baudrate="115200" mode="0" />
      <ssl enabled="true" port="12347" />
      <users>
        <user name="admin">
          <level>255</level>
          <password>#B:0x03,0x8C,0x0D,0xC8,0xA9,0x58,0xFF,0xEA,0x17,0xAF,0x04,0x72,0x44,0xFB,0x69,0x60</password>
        </user>
        <user name="user">
          <level>128</level>
          <password>#B:0x03,0x8C,0x0D,0xC8,0xA9,0x58,0xFF,0xEA,0x17,0xAF,0x04,0x72,0x44,0xFB,0x69,0x60</password>
        </user>
        <user name="readonly">
          <level>16</level>
          <password>#B:0x03,0x8C,0x0D,0xC8,0xA9,0x58,0xFF,0xEA,0x17,0xAF,0x04,0x72,0x44,0xFB,0x69,0x60</password>
        </user>
      </users>
    </sscp>
    <rcwaredb enabled="false">
      <urls>
        <url protocol="https" host="db.unipi.technology" path="/plc/save" port="443" username="unipi_00000" password="password" certificatevalidation="false" />
      </urls>
      <updateperiod>1</updateperiod>
    </rcwaredb>
    <proxy enabled="false">
      <proxyid>PRX0000000000000</proxyid>
      <urls>
        <url protocol="https" host="proxy.unipi.technology" path="/" port="6678" certificatevalidation="false" />
      </urls>
      <keepalive>10</keepalive>
    </proxy>
    <certificates enabledefaultca="true" enableuserca="true" enableservercert="true" enablewebservercert="true" />
    <sshservice enabled="true">
      <port>22</port>
      <password>unipi.technology</password>
    </sshservice>
  </runtime>
  <timetransformation utcoffset="3600" count="20">
    <daylights>
      <daylight year="2018" start="7171200" end="25920000" daylightoffset="3600" />
      <daylight year="2019" start="7689600" end="25833600" daylightoffset="3600" />
      <daylight year="2020" start="7603200" end="25747200" daylightoffset="3600" />
      <daylight year="2021" start="7430400" end="26179200" daylightoffset="3600" />
      <daylight year="2022" start="7344000" end="26092800" daylightoffset="3600" />
      <daylight year="2023" start="7257600" end="26006400" daylightoffset="3600" />
      <daylight year="2024" start="7776000" end="25920000" daylightoffset="3600" />
      <daylight year="2025" start="7603200" end="25747200" daylightoffset="3600" />
      <daylight year="2026" start="7516800" end="25660800" daylightoffset="3600" />
      <daylight year="2027" start="7430400" end="26179200" daylightoffset="3600" />
      <daylight year="2028" start="7344000" end="26092800" daylightoffset="3600" />
      <daylight year="2029" start="7171200" end="25920000" daylightoffset="3600" />
      <daylight year="2030" start="7689600" end="25833600" daylightoffset="3600" />
      <daylight year="2031" start="7603200" end="25747200" daylightoffset="3600" />
      <daylight year="2032" start="7516800" end="26265600" daylightoffset="3600" />
      <daylight year="2033" start="7344000" end="26092800" daylightoffset="3600" />
      <daylight year="2034" start="7257600" end="26006400" daylightoffset="3600" />
      <daylight year="2035" start="7171200" end="25920000" daylightoffset="3600" />
      <daylight year="2036" start="7689600" end="25833600" daylightoffset="3600" />
      <daylight year="2037" start="7516800" end="25660800" daylightoffset="3600" />
    </daylights>
    <ntp>
      <urls>
        <url protocol="ntp" host="tik.cesnet.cz" path="/" port="123" certificatevalidation="false" />
      </urls>
      <keepalive>5</keepalive>
    </ntp>
  </timetransformation>
  <memorylayout usehistoryinram="true">
    <sdcard useforhistory="false" historysize="16384" />
  </memorylayout>
  <enablenetdrivers>false</enablenetdrivers>
  <cloudAccess enabled="false">
    <urls>
      <url protocol="tcps" host="domain.com" path="/" port="80" priority="0" certificatevalidation="false" />
    </urls>
    <items>
      <item enabled="false" id="" username="" password="" ipaddress="127.0.0.1" port="80" />
    </items>
  </cloudAccess>
</hwconfiguration>
</code>




PlcTool.exe help - a měli byste dostat všechny použitelné parametry
Funguje i PlcTool.exe help <konkrétní příkaz>, kdy dostanete více detailů.

PlcTool.exe wait  --host 192.168.20.33 --port 12346 -u administrator -p rw --license-ok --output-format json

se zkusí připojit k zadanému kontroléru a zkontroluje, zda má validní licenci. Výstup bude ve JSON formátu.


PlcTool.exe upload-rt -t 180 -s *2d5c -u admin -p rw -f "C:\mervisrt.unipi.sh" -ia 192.168.20.73

nahraje do kontroléru nový RT


----


-connection parameters - required -p or -h a and -u a -pw, unless function -d is used
	-prx --proxy { http(s)://x.y.z:123 } // connect via MervisProxy
	-prxid --proxyid PRXxxx // in case of -pr, the tool also needs MervisProxyID
	-h --host] { 127.0.0.1 } // connect directly to the specified IP, expect also connection on local loopback 127.0.0.1
	-s -ssl // use SSL
	-us --user // username
	-pw --password // password

-functions
	-i --info // get PLC info including license status, and runtime execution status,...
	-l --license [ additional parameters -e [--email] x@y.z -k [--key] MRTxxx // oneshot fingerprint download, licensing and upload to the PLC ---nechavam na vas, zda rozdelit do vice kroku jak je to v IDE
	-d --deploy /tmp/ide_project // path to the Mervis project files/folder to deploy to the PLC and other startup parameters(warm,cold a clearflash,...) ---dalsi veci jako run mode, boot project location zrejme nebudou v prvni verzi nutne
	-ur --updatert /tmp/rt // path to the runtime to update the PLC ---?? a kde ho vezme?? bude se distribuovat s timto balikem?
	-c --config // anything that can be configured in "PLC Setup > Upload configuration” (ie. additional parameters -cnetdhcp enable/disable -cnetip a.b.c.d --cnetmask a.b.c.d -cnetgw a.b.c.d -cnetdns a.b.c.d -cus u --c)
	-w --web //path to the folder containing file for Mervis HMI (website)
	-e --env /tmp/env [environment file, kde je mozne specifikovat cokoli z parametru pripojeni]

-output as structured information (ie. json) which can be easily parsed and understand

----

G100 (arm64)

    Instalace .net
        https://gist.github.com/richlander/467813274cea8abc624553ee72b28213
        sudo apt update
        sudo apt install curl
        curl -SL -o dotnet.tar.gz https://dotnetcli.blob.core.windows.net/dotnet/Sdk/master/dotnet-sdk-latest-linux-arm64.tar.gz
        sudo mkdir -p /usr/share/dotnet
        sudo tar -zxf dotnet.tar.gz -C /usr/share/dotnet
        sudo ln -s /usr/share/dotnet/dotnet /usr/bin/dotnet
        optional
            sudo apt install icu-devtools
            sudo apt install libssl-dev
    Nakopirovani PlcTool
        pri kopirovani pres WinSCP nastavit 'X' - executable atribut
    spusteni PlcTool
        .\PlcTool

S103 (arm)

    Zvetsit partitions (viz. screenshots)
        napr. primountovat SD do vmware ubuntu
            pustit vmware jako administrator
            https://www.htpcguides.com/how-to-use-sd-card-reader-in-vmplayer-and-vmworkstation/
        zvetsit partitions - gparted
        read-only partition 
            docasne: mount -o remount,rw /
            na stalo: v /etc/fstab pro /dev/mmcblk0p2 odebrat ,ro na konci radku (read only)
    Instalace .net
        https://gist.github.com/richlander/467813274cea8abc624553ee72b28213
        sudo apt update
        sudo apt install curl
        curl -SL -o dotnet.tar.gz https://dotnetcli.blob.core.windows.net/dotnet/Sdk/master/dotnet-sdk-latest-linux-arm.tar.gz
        sudo mkdir -p /usr/share/dotnet
        sudo tar -zxf dotnet.tar.gz -C /usr/share/dotnet
        sudo ln -s /usr/share/dotnet/dotnet /usr/bin/dotnet
        optional
            sudo apt install icu-devtools
            sudo apt install libssl-dev
    Nakopirovani PlcTool
        pri kopirovani pres WinSCP nastavit 'X' - executable atribut
    spusteni PlcTool
        .\PlcTool

Ubuntu (x64)

    na nekterych verzich je potreba doinstalovat libssl (ve verzi 1.0  nebo 1.1, .net na ni spoleha)
        wget http://security.ubuntu.com/ubuntu/pool/main/o/openssl1.0/libssl1.0.0_1.0.2n-1ubuntu5_amd64.deb
        sudo dpkg -i libssl1.0.0_1.0.2n-1ubuntu5_amd64.deb
        
*/