Implementacja wymiany danych przy pomocy JSON API na przykładzie przekaźnika easyE4

Projekty, w których miałem okazję uczestniczyć mógłbym przyporządkować do trzech grup: projekty typu „które zrobić trzeba”, projekty ciekawsze oraz projekty najciekawsze. Zabawa zaczyna się od projektów ciekawszych, w których pojawia się okazja do przygotowania programu sterującego dla maszyny lub automatu. Pomimo stosowania znanych sobie wzorców programistycznych (np. szkielet programu PLC) zmuszają one do gimnastyki umysłowej, a uruchomienia gwarantują dodatkową dawkę nowych doświadczeń.

Do projektów najciekawszych zaliczam te, w których ponadto dochodzi możliwość zastosowania niestandardowych w branży rozwiązań. Takim rozwiązaniem w mojej opinii jest wymiana danych i dostęp do urządzeń automatyki z wykorzystaniem protokołu HTTP (Hypertext Transfer Protocol). W zamian za większy nakład pracy typowo programistycznej dostajemy dużą swobodę w dostępie do zasobów urządzenia. Urządzeniem gdzie znajdziemy taką możliwość jest sterownik easyE4 firmy EATON. Posiada on wbudowany Web Serwer, dzięki któremu uzyskujemy dostęp do JSON API, a korzyści z tego wynikające postaram się przybliżyć w poniższym artykule.

HTTP oraz JSON API kilka informacji

Zanim przejdziemy do części praktycznej nakreślmy czym jest JSON API. JSON czyli JavaScript Object Notation to lekki format kodowania danych, który został zaprojektowany w celu wyeliminowania potrzeby stosowania doraźnego kodu do komunikowania się z serwerami. Format JSON jest obsługiwany przez wiele języków programowania m.in. C, C#, Java, JavaScript, PHP, Python. JSON jest jedynie tekstowym formatem danych, a do jego obsługi w ramach konkretnego języka wykorzystuje się dodatkowe biblioteki. API (Application Programming Interface) jest modułem, przy pomocy którego serwery udostępniają klientom swoje funkcje lub zasoby danych. W API zdefiniowane są operacje realizowane po stronie serwera na podstawie żądań przesyłanych przez klienta.

Żądanie oraz odpowiedź czyli request i response to dwa typy wiadomości protokołu HTTP, które służą do wymiany danych pomiędzy klientem i serwerem. Request jest wiadomością do serwera wysłaną przez klienta. Posiada ściśle określoną składnię: linię początkową, nagłówek oraz ciało (start line, header, body). Na początku żądania wysyłanego na serwer znajduje się metoda czyli czasownik lub rzeczownik wskazujący serwerowi jakie akcje należy podjąć na otrzymane zapytanie. Dwa najpopularniejsze to POST oraz GET. GET wywołuje pobranie danych z serwera natomiast POST powoduje wysłanie danych do serwera. Odpowiedź składa się z: linii statusu odpowiedzi, nagłówków oraz ciała (status line, headers, body). Linia statusu zawiera między innymi kod statusu odpowiedzi, który wskazuje na powodzenie lub porażkę wysłanego żądania. Zapewne większość osób może skojarzyć błąd 404 (404 Not Found).

Kurs programowania sterownika easyE4: http://kurseasye4.pl

Czy serwer każdorazowo po nieautoryzowanym zapytaniu powinien udostępniać wrażliwe dane? Jeżeli takie jest życzenie właściciela danych to dlaczego nie. Natomiast jeżeli zależy nam aby dane były przekazywane osobom do nich upoważnionym z pomocą przychodzi mechanizm uwierzytelnienia. Istnieje wiele typów uwierzytelniania. W przypadku API sterownika easyE4 zastosowano dwa typy: Basic Authentication oraz API key. Basic Authentication jest najprostszym typem uwierzytelniania. Polega na przesłaniu wraz z żądaniem nazwy użytkownika oraz hasła i walidacji przesłanych danych po stronie serwera. API key jest ciągiem znaków wysyłanym przez klienta wraz z żądaniem. Powinien być znany jedynie klientowi oraz serwerowi. Wymienione dwa typy uwierzytelniania można traktować jako bezpieczne jeżeli używane są wraz z innymi mechanizmami bezpieczeństwa jak np. HTTPS/SSL.

Uruchomienie web serwera przekaźnika easyE4

Konfiguracja funkcji Web Servera w programie easySoft 7 została pokazana na filmiku dostępnym pod tym linkiem.

Poniższy rysunek przedstawia konfigurację wykonaną na potrzeby opisywanego projektu.

Dla uściślenia, w projekcie wykorzystano następujące wersje oprogramowania:

• EasySoft – V7.11.
• Ustawienia systemowe w oprogramowaniu easySoft – od wersji oprogramowania V1.10.
• Wersja sprzętowa oprogramowania (oprogramowanie sterownika) – V1.20.

Należy zaznaczyć, że EasyE4 JSON API obsługuje jedynie metodę GET. Niezależnie od tego czy zamierzamy odczytać czy zmodyfikować zmienną należy posługiwać się metodą GET. Ponadto, maksymalna długość adresu URL, który sterownik E4 jest w stanie poprawnie obsłużyć to 256 znaków. Zaleceniem producenta jest unikanie tworzenia w aplikacjach wielu drobnych zapytań, a zamiast tego tworzenie jednego większego. Oczywiście z zachowaniem maksymalnej dopuszczalnej długości. Zawartość pola body odpowiedzi zwracana jest w formacie JSON co oczywiście jest dużym ułatwieniem dla implementacji zapytań w wielu językach programowania. Przed interpretacją danych zwróconych przez easyE4 zaleca się wykonać obsługę wartości kodu statusu odpowiedzi. Jakie informacje zawarte są w poszczególnych kodach postarałem się opisać poniżej:

• 200 – wygenerowana odpowiedź jest wynikiem poprawnych operacji wynikających z żądania.
• 204 – odpowiedź jest wynikiem poprawnych operacji natomiast została zwrócona bez danych w polu body.
• 400 – żądanie jest nieprawidłowe. Prawdopodobna przyczyna to składnia żądania.
• 401 – brak uwierzytelnienia.
• 403 – zakazane. Żądanie jest poprawne natomiast serwer nie zezwala na jego wykonanie.
• 404 – nie znaleziono. Żądany URL nie istnieje.
• 501 – żądanie nie jest zaimplementowane na serwerze.
• 503 – serwer jest przeciążony.

Na podstawie wartości kodów wygenerować można komunikaty adekwatne do odpowiedzi i poinformować użytkownika napisanej przez nas aplikacji lub stwierdzić poprawność otrzymanych danych (przy założeniu, że żądanie było wygenerowane poprawnie).

Generowanie API key

API key wygenerować można korzystając z Web Serwera z poziomu przeglądarki Internetowej np. Microsoft Edge. W tym celu należy wpisać w adresie strony internetowej adres IP sterownika oraz zalogować się na konto administratora zdefiniowane uprzednio w projekcie podczas konfiguracji Web Serwera.

Po wybraniu opcji Klucz API w zakładce Ustawienia otwierane jest okno gdzie administrator może wygenerować klucz dla wskazanego użytkownika. Okno pokazano na poniższym zrzucie ekranu:

W polu Nazwa wpisać należy nazwę klucza – jego identyfikator. W polu Użytkownik należy podać nazwę użytkownika dla którego wygenerowany zostanie klucz. Nazwa użytkownika musi być zgodna z nazwą użytkownika zdefiniowaną w projekcie! Zakładając, że pola zostały wypełnione poprawnie oraz sterownik jest w trybie STOP wybranie przycisku Generuj klucz API spowoduje wygenerowanie klucza.

Implementacja zapytań w języku Python

Jak wspomniałem wcześniej z funkcjonalność JSON API skorzystać można w wielu językach programowania. Postanowiłem przedstawić mechanizm API w języku Python ze względu na szybki, w mojej opinii, czas implementacji.

Jakie zadania chciałbym zrealizować w ramach programu:

1. Sprawdzić czy połączenie z sterownikiem jest możliwe, a od wyniku uzależnić kontynuację zadań.
2. Wprowadzić sterownik w tryb RUN w sytuacji gdy aktywny jest tryb STOP
3. Wykonać zapytanie złożone.
4. Wyświetlić rezultat w konsoli.

Poniższe dwa zrzuty ekranu przedstawiają przygotowany skrypt w którym zrealizowałem postawione sobie zadania. Na początku wypunktowanych opisów znajdują się linie programu, które można zlokalizować po lewej stronie zamieszczonych zrzutów.

• 1 – import bibliotek.
• 3-5 – deklaracja adresu sterownika oraz klucza API. Jest to wygenerowany wcześniej z poziomu Web Serwera klucz.
• 8-17 – definicja funkcji isConnectionOpen(). Test połączenia wykonałem wewnątrz instrukcji try. Instrukcja zostanie wykonana, a wartość zwracana r zostanie ustawiona na True, tylko jeśli połączenie ze sterownikiem będzie możliwe.
• 19-27 – deklaracja funkcji request(). W ramach funkcji request() wykonywane jest zapytanie do API sterownika E4. W linii 20 zadeklarowano header, w którym określono sposób autoryzacji. W moim przypadku było to uwierzytelnienie kluczem API. Następnie wewnątrz instrukcji try wykonywane jest zapytanie z metodą GET pod adres wskazany w parametrach funkcji. W parametrze funkcji przekazywana jest ścieżka zapytania – bez adresu sterownika. Rezultatem poprawnie wykonanej funkcji powinny być obiekty resp oraz content. Obiekty te zawierają zwróconą przez JSON API odpowiedź. Wewnątrz obiektu resp znajduje się m.in. kod statusu odpowiedzi. Obiekt content zawiera dane w formacie JSON (jeżeli zapytanie wymaga zwrócenia danych).
• 29-39 – deklaracja funkcji isRunning(). Funkcja działa analogicznie do opisanej wcześniej funkcji isConnectionOpen(). Różnica polega na tym, że wartość zwracana przez funkcję ustawiana jest na podstawie odpowiedzi uzyskanej na zapytanie wygenerowane przy pomocy funkcji request(). W liniach 33 i 34 znajdują się instrukcje, w których dane zawarte w obiekcie content są odczytywane. Zwracane przez serwer dane mają format JSON dlatego po załadowaniu danych do obiektu json dostęp do nich działa w typowy dla tego formatu sposób. Zwracana wartość r będzie miała wartość True jeśli pole STATE będzie miało wartość RUN.
• 41-43 – deklaracja funkcji setOp(). Funkcja wykorzystywana do przygotowania oraz wykonania zapytania mającego na celu nadpisanie wartości znaczników. Jako parametry przyjmuje 3 zmienne: pOp – typ znacznika („M”, „MB”, ”MW”, „MD”), pIndex – numer znacznika, pVal – żądana wartość.
• 45-47 – deklaracja funkcji getData(). Funkcja wykorzystywana do przygotowania oraz wykonania zapytania mającego na celu odpytanie sterownika o interesujące parametry lub zmienne. Jako parametr przekazywane są kody elementów jakie potrzebujemy odczytać.
• 49-71 – definicja funkcji mainTasks(). Na początku funkcji (linie 50-53) sprawdzany jest wynik funkcji isRunning(). Jeżeli wynik funkcji ma wartość False to wykonywane jest zapytanie do sterownika (linia 51) przy pomocy funkcji request() z poleceniem wprowadzenia sterownika w tryb RUN. Następnie wyświetlany jest komunikat o operacji oraz zatrzymywane jest działanie skryptu na sekundę potrzebną na wykonanie operacji przez sterownik. Linie 54 i 55 – wykonanie dwóch zapytań do sterownika przy pomocy funkcji setOp() oraz getData(). Drugie zapytanie jest przykładem zapytania złożonego przy pomocy którego zażądano od sterownika informacji o wejściach 1 oraz 3, wartości MW25 oraz o aktualną datę i godzinę sterownika. Linie 56-71 – Wynik zapytania wyświetlany jest po sprawdzeniu wartości statusu odpowiedzi. Jeżeli ma on wartość 200 to podejmowana jest próba dekodowania oraz wyświetlenia odpowiedzi. W przeciwnym razie wyświetlana jest wartość statusu odpowiedzi. W liniach 57-69 znajdują się instrukcje, w których odczytywane są dane zawarte w obiekcie content oraz wyświetlane w konsoli. Całość zawarta została w ramach instrukcji try oraz except pozwalającej obsłużyć ewentualne błędy oraz wyjątki.
• 73-74 – definicja funkcji main(), w której sprawdzany jest wynik funkcji isConnectionOpen(). Jeżeli funkcja zwraca wartość prawdziwą wykonywane są działania funkcji mainTasks().
• 76 – wywołanie funkcji main().

Rezultat skryptu przedstawia poniższy wycinek z konsoli. Skrypt wykonany został po wcześniejszym zatrzymaniu sterownika (tryb STOP).

Wygenerowany przez skrypt rezultat pozwala mi twierdzić, że zadania jakie sobie postawiłem udało się zrealizować.

Podsumowanie

Informacja o funkcjonalności JSON API w sterowniku easyE4 zaskoczyła mnie w pozytywny sposób. Pierwsze eksperymenty opisane w powyższym artykule pozwoliły mi ocenić przydatność udostępnionych przez producenta możliwości. Mój entuzjazm związany z wykorzystaniem sterownika w niestandardowych aplikacjach dla warstwy operacyjnej lub produkcyjnej, które mogą usprawnić wymianę informacji w zakładach produkcyjnych jest olbrzymi. Przyznam, że nie mogę doczekać się okazji do wykorzystania opisanych mechanizmów w aplikacjach webowych.

Na koniec kilka linków przydatnych w pogłębieniu wiedzy, z których korzystałem przygotowując artykuł:

• JSON API – specyfikacja,
• Protokół HTTP – kompedium technologii webowych,
• Dokumentacja JSON API udostępniona przez EATON

Artykuł został nagrodzony w Konkursie iAutomatyka – edycja Styczeń 2020Nagrodę Torba podróżna + kubek termiczny + zestaw gadżetów dostarcza ambasador konkursu, firma FINDER