O API! Cz. 2
Oprogramowanie IIoT bez wchodzenia w świat OT – gateway

Poniższy wpis jest drugim z serii traktującej o pobieraniu danych z sieci OT z wykorzystaniem REST API. Tym razem skupię się na oprogramowaniu ThingsPro Edge dla bram przemysłowych Moxa z rodziny UC. Dokładnie mówiąc pokażę, jak wykorzystać wbudowane REST API, aby skonfigurować i pobierać dane ze środowiska przemysłowego.

Jeśli nie miałeś wcześniej okazji, zapraszam w pierwszej kolejności do zapoznania się z poprzednim wpisem, w którym omówiłem m.in. to, czym jest REST API i jaką rolę może odegrać w projektach IIoT.

---

 

Czy ThingsPro Edge sczytuje dane po Modbus RTU/TCP?

To może być jedno z pierwszych Twoich pytań, na które odpowiem krótko: Tak.

Wbudowany Modbus Master pozwala na skonfigurowanie zapytań w protokole Modbus RTU oraz Modbus TCP, aby uzyskiwać dane z urządzenie po stronie OT. Mogą być to sterowniki PLC, rozproszone wyspy I/O, czujnik i wszystko, co komunikuje się w protokole Modbus i chce udostępnić nam swoje rejestry pamięci.

Widok opogramowania ThingsPro Egde z okna przeglądarki. 

ThingsPro Edge pozwala na znacznie więcej.
Kiedy pobierzemy interesujące nas dane ze środowiska OT planujemy zapewne coś z nimi zrobić – przesłać je do innego oprogramowania IT, zapisać, zwizualizować lub przeanalizować.

Czy ThingsPro Edge potrafi to wszystko?: Nie.
Ale może w tym pomóc. ;) 

To oprogramowanie zostało stworzone jako dodatek do gateway’i przemysłowych z rodziny UC od Moxa, które oparte są o system Linux w pełni dostępny dla użytkownika. W zasadzie wszystko możemy zrobić sami: zaprogramować, oskryptować, przetestować, wdrożyć…

Z tym, że ThingsPro Edge jest już gotowe do instalacji, darmowe, przetestowane i pozwala m.in. na przesłanie danych po protokole MQTT czy standardzie Spurkplug, wysłanie danych do chmury Azure, AWS (przez wbudowane wtyczki) czy przesłać dane do oprogramowania OPC UA.
Może również przesyłać dane do Brokera MQTT, np. zainstalowanego jako oddzielna aplikacja w systemie, a następnie „subskrybować” (w protokole MQTT mamy do czynienia ze wzorcem „publish-subscribe”) je na przykład do NodeRED, zapisać w lokalnej bazie danych, a nawet zwizualizować np. w Grafana.

Lokalna wizualizacja zaimplementowana w oprogramowaniu Grafana na komputerze z rodziny UC.

I to wszystko można uruchomić na jednym urządzeniu z pomocą oprogramowania ThingsPro Edge.

Ale nie chciałbym się skupiać tyle na samym oprogramowaniu, ile na REST API, które udostępnia.
Tak, instalując ThingsPro Edge dostajemy dostęp do API, umożliwiające skonfigurowanie parametrów komunikacji, zapytań modbusowych czy ustawienia dostępu… a przede wszystkim zintegrowanie się z własnym oprogramowaniem.
Samą dokumentację do API zostawiam tutaj i zapraszam na część praktyczną niniejszego wpisu.

---

Jak się uwierzytelnić?

Istotna sprawa. Przeglądarkowe ThingsPro Edge ma panel logowania. W przypadku API uwierzytelnienie wygląda oczywiście inaczej – przybiera formę zapytania HTTP. W manualu znajdziemy wytyczne jak ma wyglądać nasze zapytanie HTTP wraz z przykładową strukturą „body” oraz przykładem pomyślnej i niepomyślnej odpowiedzi zwrotnej.

Fragment dokumentacji API ThingsPro Edge.

Spróbujmy tego w praktyce. Do testowania API wykorzystuję Postman.
Wybieramy zapytanie typu POST, pole body ustawiamy na „raw” i wpisujemy odpowiednią strukturę danych, zgodnie z wytycznymi w instrukcji API.

Type	POST
URL	http(s)://adres_ip:port/api/v1/auth
Authorization	-
Body	{ "acceptEULA": false, "name":"admin", "password":"Admin@123" }

Zapytanie o uwierzytelnienie. 

Budowa zapytania HTTPS przy próbie uwierzytelnienia za pomocą API ThingsPro Edge.

W odpowiedzi otrzymujemy Token JWT, który możemy wykorzystać jako autoryzacja przy innych zapytaniach.

W odpowiedzi na próbę poprawną próbę uwierzytelnienia dostajemy Token JWT.

---

Konfiguracja ustawień sieciowych

Uwierzytelnienie, potwierdziło naszą tożsamość i otworzyło nam furtkę do dalszych działań.
Przeprowadzimy teraz konfigurację ustawień sieciowych portów Ethernet oraz skonfigurujemy połączenie z serwerem Modbus TCP, pobierając z niego dane środowiskowe a następnie prześlemy dane do brokera MQTT.

Działajmy!

Na początek sprawdźmy ustawienia sieci portów Ethernet. W modelu AIG-301-EU-AZU-LX, z którego korzystam mam 2 takie porty.

Type	GET
URL	http(s)://adres_ip:port/api/v1/device/ethernets
Authorization	Bearer Token
Body	-

Zapytanie o konfigurację portów Ethernet na komputerze UC. 

Zdjęcie poniżej przedstawia zwróconą odpowiedź.

Konfiguracja portów Ethernet. 

Spróbujmy ustawić stały adres IP oraz wyłączyć protokół DHCP dla pierwszego portu.

Type	PATCH
URL	http(s)://adres_ip:port/api/v1/device/ethernets/{id} (id – numer portu)
Authorization	Bearer Token
Body (example)	{ "enable": true, "ip": "192.168.10.164", "netmask": "255.255.255.0", "gateway": "192.168.10.1", "dns": [ "194.204.152.34", "8.8.8.8" ], "enableDhcp": false, "wan": true }

Zmiana parametrów portu Ethernet.  

Sprawdzając jeszcze raz konfigurację portów Ethernet możemy zobaczyć, że parametr „IP” oraz „enableDhcp” zostały zmienione.  

W rezultacie parametry portu Ethernet zostały zmienione.

Sukces!

Tak samo możemy edytować parametry portu 2, przez który połączymy się z urządzeniem, z którego będziemy pobierać dane. Akurat w przypadku mojego zestawienia nie ma potrzeby zmiany parametru portu LAN, więc zostawiam ustawienia takimi jakie są i przychodzę do protokołu Modbus.

---

Konfiguracja protokołu Modbus

Na samym początku warto wiedzieć, że ThingsPro Edge potrafi rozmawiać w protokole Modbus RTU/TCP. To spróbujmy zestawić taką komunikację z pomocą API.
Pierwszym krokiem będzie dodanie urządzenia Modbus, z którego dane będą pobierane. Będziemy to robić za pomocą protokołu Modbus TCP, więc z portami szeregowymi nie musimy się zajmować, a ustawienia portu LAN, przez który będzie przebiegać komunikacja, mamy już za sobą.
Konfigurację Modbus (dodane urządzenia, zdefiniowane zapytania) można sprawdzić za pomocą poniższego zapytania.

Type	GET
URL	http(s)://adres_ip:port/api/v1/ modbusmaster/config/remote-devs
Authorization	Bearer Token
Body	-

Sprawdzenie skonfigurowanych zewnętrznych urządzeń Modbus. 

Spróbujmy dodać nowe urządzenie Modbus.

Type	POST
URL	http(s)://adres_ip:port/api/v1/ modbusmaster/config/remote-devs
Authorization	Bearer Token
Body (example)	{   "masterTcpIfaceId": 1,   "name": "ioLogik_E1242_",   "enable": 1,   "slaveIpaddr": "192.168.4.254",   "slaveTcpPort": 502 }

Dodanie nowych zewnętrznych urządzeń Modbus. 

Następnie dodajmy komendę Modbus, aby pobrać dane z dodanego urządzenia.

Type	POST
URL	http(s)://adres_ip:port/api/v1/modbusmaster/config/mcmds
Authorization	Bearer Token
Body (example)	{   "remoteDevId": 4,   "name": "engineRunParameter",   "mode": 0,   "func": 4,   "readAddress": 513,   "readQuantity": 1,   "pollInterval": 1000,   "swap": 0,   "pointSourceMax": 65535,   "pointTargetMax": 100 }

Dodawanie nowych zapytań Modbus.

W ostatnim kroku, aby móc dalej przetwarzać i udostępnić pobraną wartość, przypiszemy ją do Tagu (w aplikacji ThingsPro Edge, przy późnijeszym przesyłaniu danych, operujemy na tagach).

Type	POST
URL	http(s)://adres_ip:port/api/v1/modbusmaster/config/tags
Authorization	Bearer Token
Body (example)	{   "mcmdId": 9,   "name": "engineRunParameter",   "dataType": "uint16",   "access": "r",   "offset": 0 }

Przypisanie pobranych danych Modbus'owych do tagu w aplikacji ThingsPro Egde. 

Możemy sprawdzić czy dane z urządzenia Modbus są sczytywane poprawnie.

W zakładce Tag Management możliwe jest podlądanie pobierancyh danych w czasie rzeczywistym. 

Pozostaje nam zestawienie komunikacji MQTT. ThingsPro Edge jest w standardzie wyposażone w Klienta MQTT. Należy połączyć go z Brokerem MQTT. W naszym środowisku Broker dostępny jest pod adresem 172.19.0.5 na porcie 1883.

Type	POST
URL	http(s)://adres_ip:port/api/v1/mqtt
Authorization	Bearer Token
Body (example)	{   "enable": true,   "protocolVersion": "3.1.1",   "server": "172.19.0.5",   "port": 1883 }

Dodawanie nowego połączenia MQTT pomiędzy MQTT Client (zawartego w ThingsPro Edge) a MQTT Broker.

Po odpowiednim zestawieniu komunikacji z Brokerem możemy zdefiniować dane, które będą publikowane w Brokerze.

Type	POST
URL	http(s)://adres_ip:port/api/v1/mqtt/{id}/messages
Authorization	Bearer Token
Body (example)	{   "id": 1,   "enable": true,   "outputTopic": "MyLEDStatus",   "properties": [],   "tags": {     "modbus_tcp_master": {       "ioLogik_E1242_": [         "engineRunParameter",         "oilTempParameter"       ]     },     "system": {       "status": [         "cpuUsage",         "memoryUsage"       ]     }   },   "pollingInterval": 0,   "sendOutThreshold": {     "size": 4096,     "time": 0   },   "format": "" }

Publikowanie danych do Brokera MQTT. 

W przeglądarce, przechodząc do zakładki MQTT Client, możemy podejrzeć czy poprawnie zdefiniowano komunikację oraz publikowanie danych.

Podgląd skonfigurowanego połącznenia MQTT w ThingsPro Edge.

---

Podsumowanie

W dzisiejszym wpisie, to by było na tyle. Jak widać możliwości API w ThingsPro Edge są spore i mogą przysłużyć się w integracji z własnymi aplikacjami. Jeszcze raz odsyłam do dokumentacji, a jeśli coś wymaga doprecyzowania zachęcam do kontaktu pod adresem moxa@elmark.com.pl.