====== MQTT ======

V Mervis IDE je protokol MQTT technicky implementován jako **klientský driver**. Protože však Mervis RT dokáže data jak publikovat (poskytovat), tak i odebírat (přijímat), funguje efektivně oběma směry. Do sekce serverových protokolů je zařazen proto, že prostřednictvím centrálního Brokeru funguje jako poskytovatel dat pro ostatní systémy.

Data jsou organizována pomocí „Topics“, což jsou hierarchické struktury fungující jako cesty, kam jsou data publikována. Například základní složka může být ''building/hvac'', se podsložkami jako ''building/hvac/temp''. 

//(Poznámka k organizaci: Mervis podporuje Prototypy, které pomáhají systematicky organizovat pojmenování v rozsáhlých projektech. Nebudeme se jim zde detailně věnovat, ale jejich použití je velmi doporučeno pro udržení přehlednosti proměnných.)//

===== Krok 1: Nastavení připojení k brokeru =====

Nejprve je potřeba vytvořit komunikační spojení mezi vaším Mervis zařízením a MQTT brokerem.

{{:en:mervis-ide:35-help:023-server-communication-protocols:mqtt1.png?400|Nastavení TCP a MQTT parametrů zařízení}}

==== 1. Konfigurace TCP parametrů ====
  * **Pro testování**: Můžete použít veřejný broker jako ''broker.emqx.io'' na portu 1883. Pozor: Toto je pouze pro testování a nikdy by nemělo být použito pro produkční data.
  * **Pro produkci (KRITICKÉ)**: Použijte šifrovanou a autentizovanou komunikaci. Nastavte adresu vašeho privátního brokeru, povolte TLS/SSL a použijte port 8883.

==== 2. Konfigurace parametrů zařízení ====
  * Ujistěte se, že máte zvolenou správnou verzi MQTT pro vaši aplikaci (např. MQTT v5.0).
  * Definujte vaše Client ID (např. MervisClient). Obvykle je k dispozici API přístup pro přihlašovací údaje, pokud broker vyžaduje autentizaci.
  * Nastavte Base Topic (hlavní datovou složku) na ''building/hvac''.

**Užitečné makra**
Při nastavování Client ID nebo Topics můžete použít makra (nerozlišují velikost písmen), která automaticky doplní systémová data. Tím zajistíte plný kontext bez nutnosti opakovaného psaní.

^ Makro ^ Popis ^
| ''%%ClientId%%'' | Vloží definované MQTT Client ID. |
| ''%%PlcName%%'' | Vloží přiřazený název PLC. |
| ''%%system.rtc%%'' | Vloží systémový reálný čas (lokální čas). |
| ''%%system.rtcutc%%'' | Vloží systémový čas v UTC (Coordinated Universal Time). |

==== 3. Nastavení rozumného intervalu čtení/zápisu (KRITICKÉ) ====
  * Výchozí hodnota intervalu Read/Write může být nastavena na 0 ms. 
  * Je nutné ji změnit na rozumnou hodnotu (např. 1m nebo 2m). 
  * Pokud zůstane 0 ms, dojde k zahlcení brokeru a neustálým komunikačním chybám.

===== Krok 2: Organizace skupin pro čtení a zápis =====

Mervis RT organizuje komunikaci oddělením příchozích a odchozích dat.

{{:en:mervis-ide:35-help:023-server-communication-protocols:mqtt2.png?600|Prohlížeč proměnných s přehledně oddělenými Read_Group a Write_Group}}

==== 1. Read Group (Subscribing) ====
Mervis RT používá Read Group pro odběr topicu, parsování dokumentu a aktualizaci hodnot v programu. 

{{:en:mervis-ide:35-help:023-server-communication-protocols:mqtt3.png?300|Vlastnosti Read Group}}

  * Vytvořte skupinu s názvem ''Read_Group''. 
  * Nastavte formát payloadu podle toho, co broker odesílá. 
  * Pro čtení a odběr Mervis nativně podporuje JSON, CSV a prostý text.

==== 2. Write Group (Publishing) & šablony ====
Mervis RT používá tuto skupinu pro vytvoření dokumentu a jeho odeslání do brokeru. 

{{:en:mervis-ide:35-help:023-server-communication-protocols:mqtt4.png?300|Vlastnosti Write Group}}

  * Vytvořte skupinu s názvem ''Write_Group''. 
  * Zde definujete Publish Template, který přesně určuje strukturu odchozích dat. 
  * Do této šablony můžete psát libovolný formát—JSON, CSV, XML apod. 
  * Řídicí blok ''%%foreach%%'' je velmi užitečný pro iteraci přes více proměnných, ale není povinný. Šablonu lze vytvořit i kompletně ručně.

===== Krok 3: Vytváření a mapování datových bodů =====

//(Poznámka pro nové uživatele: Mapování datových bodů a práce s Enumy je obecná vlastnost klientských kanálů v Mervis. Pokud jste již používali Modbus nebo jiné protokoly v Mervis, bude vám tento proces velmi povědomý.)//

==== 1. Mapování vstupních proměnných ====
Uvnitř ''Read_Group'' vytvořte datový bod pro vstup.

{{:en:mervis-ide:35-help:023-server-communication-protocols:mqtt5.png?300|Mapování příchozích MQTT dat na interní proměnnou}}

  * **Mapování na interní proměnnou**: Nastavte ''IO => ST'' na cílovou proměnnou.
  * **Data Locator**: Použijte Value Path (např. ''$.temp'' pro JSON), aby Mervis přesně věděl, kde hledat hodnotu v příchozím payloadu. Pro CSV použijte vlastnost Index k určení přesné pozice hodnoty (indexování od 1).
  * **Přeskočení chybějících dat**: Nastavte Ignore Missing Data na True. Pokud hodnota v payloadu chybí, systém ji přeskočí bez vyvolání komunikační chyby.

==== 2. Mapování výstupních proměnných ====
Uvnitř ''Write_Group'' vytvořte datový bod pro výstup (např. Total).

{{:en:mervis-ide:35-help:023-server-communication-protocols:mqtt6.png?300|Mapování vypočtené interní proměnné do MQTT brokeru}}

  * **Mapování na výstup**: Namapujte interně vypočtenou proměnnou na výstup pomocí ''ST => IO''. 
  * Je důležité zdůraznit, že tato proměnná musí být globální, aby správně fungovala.

===== Krok 4: Logika funkčních bloků =====

Po namapování komunikačních proměnných je můžete použít ve standardní logice IEC 61131-3. 

{{:en:mervis-ide:35-help:023-server-communication-protocols:mqtt7.png?600|Jednoduchý FBD program sčítající vstupy logického bloku}}

V praktické aplikaci můžete například mapovat dva MQTT vstupy (např. ''Power_Zone_1'' a ''Power_Zone_2'') a sečíst je pro výpočet celkové spotřeby energie objektu. Matematický blok vypočítá součet a výsledek se zapíše přímo do globální MQTT výstupní proměnné (''Calculated_Total'').

===== Krok 5: Testování pomocí MQTTX =====

Pro ověření správné funkčnosti použijte desktopového klienta, jako je MQTTX, který simuluje reálný datový provoz. Umožní vám vidět výsledky Publish Templates vytvořených v Kroku 2.

{{:en:mervis-ide:35-help:023-server-communication-protocols:mqtt8.png?600|Simulace senzorických dat v MQTTX}}

  * **1. Připojení**: Připojte MQTTX k brokeru (''broker.emqx.io:1883'').
  * **2. Odběr (Subscribe)**: Přihlaste odběr ''building/hvac/#'', abyste mohli sledovat veškerá data v rámci base topicu.
  * **3. Simulace vstupu**: Publikujte payload na ''building/hvac/temp''. Použijte nastavený formát (např. JSON: ''{"temp":5,"humidity":50}'' nebo standardní CSV řádek).
  * **4. Ověření výstupu**: Sledujte příchozí zprávy v MQTTX. Měli byste vidět, že Mervis okamžitě publikuje novou zprávu obsahující vypočtenou hodnotu přesně ve formátu definovaném vaší šablonou.