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

===== Model „Ústředny“ =====

Abychom pochopili, jak MQTT funguje v systému Mervis, představme si spíše **ústřednu** než přímý telefonní hovor.

V tradičních systémech si zařízení často „volají“ navzájem přímo. Pokud je jedna strana zaneprázdněná nebo offline, hovor selže. MQTT je jiné. Využívá centrální uzel (Broker), který funguje jako operátor ústředny.

  * **Vydavatelé (vaše zařízení)**: Připomínají pracovníky v terénu, kteří hlásí data. Nevolají přímo manažerovi – jednoduše zanechají hlášení na ústředně.
  * **Broker (Mervis Server)**: To je ona ústředna. Přijímá všechna hlášení, organizuje je do specifických „složek“ (Topics) a bezpečně je uchovává.
  * **Odběratelé (Mervis interní)**: V našem systému používáme **interní odběratele** pro maximální bezpečnost a kontrolu. I když Mervis může fungovat jako odběratel, nedovolujeme externím ani neautorizovaným odběratelům přístup k vašim datovým tokům.

===== Architektury připojení =====

Existují dva způsoby připojení, ale kvůli bezpečnosti a jednoduchosti **důrazně doporučujeme Embedded Broker**.

==== 1. Vestavěný broker v Mervis (Doporučeno) ====
V tomto režimu je ústředna přímo součástí Mervis Cloudu.
  * **Bezpečnost**: Uzavřený okruh. **Žádní externí odběratelé** nejsou povoleni. Přístup k datům má pouze systém Mervis, což zajišťuje vysokou úroveň kontroly a soukromí.
  * **Jednoduchost**: Nemusíte spravovat externí server.
  * **Provozní tok**: Zařízení odesílá data přímo na `mqtt.mervis.info`.

==== 2. Externí broker (Klientský režim) ====
V tomto režimu používáte vlastní broker třetí strany. Mervis funguje pouze jako další odběratel.
  * **Riziko**: Méně bezpečné, protože Mervis nemá kontrolu nad tím, kdo další broker poslouchá.
  * **Využití**: Smysluplné při integraci do již existující infrastruktury.

===== Provozní tok připojení (Embedded) =====

Pro nastavení zabezpečeného Embedded připojení postupujte takto:

  - **1. Registrace v Portálu (DataNode)**:
    * Přihlaste se do portálu Mervis: **[[https://portal.mervis.info/|portal.mervis.info]]**.
    * Vytvořte **DataNode** pro váš projekt – digitální dvojče v cloudu.
    * Vyberte typ zařízení.
    * Portál vygeneruje **DeviceID**, **uživatelské jméno** a **heslo**.

  - **2. Konfigurace zařízení**:
    * Otevřete webovou administraci zařízení.
    * **Adresa brokeru**: nastavte na ``mqtt.mervis.info``.
    * **Port**: použijte zabezpečený port s TLS.
    * Zadejte přihlašovací údaje z portálu.

  - **3. Mervis Generator**:
    * Jakmile je DataNode aktivní, navštivte **[[https://generator.mervis.info|generator.mervis.info]]**.
    * Automaticky naskenuje vaše DataNodes a vygeneruje SCADA projekt, včetně propojení všech tagů bez ručního zadávání.

===== Podporované Embedded ovladače =====

Následující zařízení mají v Mervis dedikované ovladače `EmbeddedBroker`:

  * **BMR PLA34 / PLA44**: Analyzátory kvality elektrické energie. ([[https://www.bmr-trading.com|Navštivte BMR]])
  * **Shelly Pro 3EM**: Třífázové elektroměry. ([[https://www.shelly.com|Navštivte Shelly]])
  * **Wago PFC řady**: Programovatelné automaty. ([[https://www.wago.com|Navštivte Wago]])
  * **Weintek**: HMI panely a brány. ([[https://www.weintek.com|Navštivte Weintek]])
  * **Kornfeil**: Průmyslové pece. ([[https://www.kornfeil.cz|Navštivte Kornfeil]])

**Specializované senzory**
  * **IAQ03**: Senzory kvality vnitřního ovzduší. ([[https://www.iaq.cz|Navštivte IAQ]])

===== Datová struktura & Payloady =====

==== Analogie s vlakem ====
Představte si MQTT pakety jako vlak:
  * **Protokol (koleje)**: Tím je samotný MQTT.
  * **Payload (náklad)**: To jsou skutečná data uvnitř vagonů.

I když MQTT je způsob přepravy, „nákladem“ může být cokoliv. Mezi běžné typy patří:
  * **JSON** (preferovaný v Mervis)
  * **XML**
  * **Text / String**
  * **JPEG obrázky**
  * **Binární data**

==== Požadavky na payload ====
  * **Formát**: JSON je preferovaný standard. Pokud vaše zařízení odesílá jiný formát (např. XML nebo binární), bude nutné provést testování a úpravy.
  * **Topic**: Payload nebo hlavička musí jasně určovat „Topic“ (složku, kam daný soubor patří).
  * **Škálování**: Surové celočíselné hodnoty z PLC často vyžadují škálování. Např. hodnota `2305` může znamenat `230.5 Voltů` (děleno 10).

===== Řešení běžných problémů =====

^ Příznak ^ Možná příčina ^ Řešení ^
| **Žádné připojení** | Blokování firewallem | Ujistěte se, že síť umožňuje odchozí provoz na **mqtt.mervis.info**. |
| **Chyba ověření** | Nesoulad přihlašovacích údajů | Zkontrolujte, že ID, uživatelské jméno a heslo v zařízení odpovídají údajům z portálu. |
| **Offline stav** | Chybí heartbeat | Zkontrolujte, že zařízení odesílá „Keep Alive“ každých 60 sekund. |
| **Špatné hodnoty** | Chybějící škálování | Nastavte škálovací faktor (např. /10) ve značkách v Mervis. |

===== Pokročilý přehled: JSON struktury =====

Pro vývojáře, kteří ručně integrují zařízení Wago nebo Weintek, použijte následující vzorové payloady.

===== Podporované formáty =====

==== Formát kompatibilní s Wago ====

=== Registrace dostupných proměnných ===

  * Informuje odběratele o dostupných proměnných
  * Publikace s doručením „alespoň jednou“
  * Topic: deviceId/TagConfiguration
  * Kombinace ID kolekce a Tagu musí být pro každé zařízení jedinečná!
  * Payload: UTF-8 JSON dokument
    * /FormatId: (string), ID zprávy
    * /ApiVersion (int), verze API
    * /Complete (bool), nyní musí být true
    * /Collections (pole kolekcí)
      * /Id (int), ID kolekce
      * /CollectionName (string)
      * /SampleRate (int), vzorkovací rychlost v ms
      * /PublishInterval (int), interval publikace v ms
      * /TagData (pole proměnných)
        * /Tag (string), ID proměnné
        * /Unit (string), jednotka proměnné
        * /ValueType (string), ST typ; podporovány jsou pouze jednoduché typy

**Příklad**

<code json>
{
	"FormatId": "TagConfiguration",
	"ApiVersion": 1,
	"Complete": true,
	"Collections": [{
		"Id": 1,
		"CollectionName": "Building 1",
		"SampleRate": 60000,
		"PublishInterval": 60000,
		"TagData": [{
			"Tag": "Temperature1",
			"Unit": "ºC",
			"ValueType": "real"
		},
		{
			"Tag": "Humidity",
			"Unit": "%",
			"ValueType": "word"
		}]
	},
	{
		"Id": 2,
		"CollectionName": "Building 2",
		"SampleRate": 120000,
		"PublishInterval": 240000,
		"TagData": [{
			"Tag": "Water flow",
			"Unit": "m3/h",
			"ValueType": "byte"
		},
		{
			"Tag": "Current phase L1",
			"Unit": "A",
			"ValueType": "lreal"
		}]
	}]
}
</code>

=== Hodnoty proměnných ===
  * Publikuje hodnoty proměnných
  * Publikace s doručením „alespoň jednou“
  * Topic: deviceId/TagValues
  * Payload: UTF-8 JSON dokument
    * /FormatId: (string), ID zprávy
    * /ApiVersion (int), verze API
    * /CollectionId (int), ID kolekce
    * /TagData (pole hodnot)
      * /Time (datetime), časová známka v ISO formátu (YYYY-MM-DDTHH:MM:SSZ), ideálně v UTC
      * /Values (sbírka dvojic tag-hodnota)

**Příklad**

<code json>
{
	"FormatId": "TagValues",
	"ApiVersion": 1,
	"CollectionId": 1,
	"TagData": [{
		"Time": "2018-03-27T17:19:23.720+02:00",
		"Values": {
			"Temperature1": 15.52,
			"Humidity": 21
		}
	}]
}
</code>

==== Formát kompatibilní s Weintek ====
  * Předpokládáme, že všechny hodnoty času jsou v **UTC**
  * Screenshoty jsou z EasyBuilder Pro SW

=== Hodnoty proměnných ===
  * Publikuje hodnoty proměnných
  * Publikace s doručením „alespoň jednou“
  * Topic: $deviceId/mervis/values nebo $deviceId/mervis/values/*
  * Payload: UTF-8 JSON dokument
    * /d: kořenový prvek
      * "název_vlastnosti": hodnota - název může obsahovat metadata (nepovinné). Hodnoty vždy jako pole [...]
        * formát metadata:
          * "name" název
          * "type" typ vlastnosti (pouze [[https://kb.mervis.info/doku.php/en:mervis-scada:80-mqtt#our_supported_types|námi podporované typy]])
          * "unit" informace o jednotce

**Příklad**

<code json>
{
    "d" : {
        "name:MyHomeTemperature, type:generic_sint64, unit:°C" : [ 0 ],
        "number C" : [ 0 ],
        "Bit" : [ false ],
        "My array" : [ 0, 10, 20 ]
    },
    "ts" : "2020-08-27T07:10:24.360316"
}
</code>
{{ :en:mervis-scada:annotation_2020-08-27_120101.png?600 |}}

=== Registrace příkazů ===
  * Topic: $deviceId/mervis/cmd_reg nebo $deviceId/mervis/cmd_reg/*
  * Formát:
    * /d: kořenový prvek
      * "názevVlastnosti" musí obsahovat informace (oddělené čárkou). Hodnota je ignorována.
        * "id" – ID příkazu a určuje odběrové topic ($deviceId/mervis/command/change_temperature)
        * "name" – pro zobrazení zákazníkovi
        * "params" – parametry příkazu (**musí obsahovat všechny parametry z odběrového topicu**)
          * "name" – název parametru
          * "type" – typ parametru (pouze [[https://kb.mervis.info/doku.php/en:mervis-scada:80-mqtt#our_supported_types|námi podporované typy]])
          * "unit" – jednotka

        * "ts" – časový údaj
<code>
{
    "d" : {
        "id:change_temperature, name:change temperature in house ,params:[{name: temperature, type:generic_float64, unit:°C}, {name: date, type:generic_datetime, unit:UTC}]" : false
    },
    "ts" : "2020-08-27T07:10:11.356013"
}
</code>
choose/create $deviceId/mervis/cmd_reg/
{{ :en:mervis-scada:annotation_2020-08-27_110112.png?400 |}}
nastavte obecnou záložku dle screenshotu
{{ :en:mervis-scada:annotation_2020-08-27_121338.png?400 |}}
přidejte příkazy
{{ :en:mervis-scada:annotation_2020-08-27_115716.png?400 |}}

===Naše podporované typy===
              * "generic_bool"
              * "generic_sint8"
              * "generic_uint8"
              * "generic_sint16"
              * "generic_uint16"
              * "generic_sint32"
              * "generic_uint32"
              * "generic_sint64"
              * "generic_uint64"
              * "generic_float32"
              * "generic_float64"
              * "generic_string"
              * "generic_datetime"

===Vytvoření odběrového topicu pro spuštění příkazu===
  * pro předchozí příklad příkazu
  * vytvořte topic: $deviceId/mervis/command/change_temperature
  * se dvěma adresami:
    * temperature (32-bit float)
    * date (string)
{{ :en:mervis-scada:annotation_2020-08-27_110134.png?600 |}}