System sterowania oświetleniem Philips Hue z użyciem środowiska Zerynth oraz języka Python (2)

W kolejnym kroku, po poprawnym nawiązaniu połączenia z siecią Wi-Fi, możemy przystąpić do utworzenia interfejsu graficznego, umożliwiającego wprowadzenie adresu IP, przypisanego do urządzenia Philips Hue Bridge. Do budowy interfejsu zastosujemy metodę bt81x.add_keys(), która umieszcza na ekranie pojedynczy wiersz przycisków – dla przykładowego wywołania:

bt81x.add_keys(450, 70, 280, 60, 30, 0, "123")

Uzyskany efekt pokazuje rysunek 4.

Rysunek 4. Pojedynczy wiersz przycisków utworzony z użyciem bt81x.add_keys()

Okno wprowadzania adresu IP jest pierwszym elementem budowanego interfejsu użytkownika, który wymaga obsługi panelu dotykowego. Dzięki możliwości przypisania unikalnego identyfikatora TAG, do każdego tworzonego obiektu graficznego, programista jest zwolniony z obowiązku odczytu surowych danych, w postaci współrzędnych X i Y. Obsługa panelu dotykowego, wymaga od programisty wyłącznie wywołania funkcji bt81x.touch_loop(), która wskazuje funkcje zwrotne obsługi zdarzenia dotyku. Dla każdej wartości parametru TAG istnieje możliwość przypisania wydzielonej funkcji obsługi zdarzenia, lub, jak ma to miejsce w omawianej aplikacji, przygotowanie jednej funkcji zwrotnej do obsługi wszystkich zdarzeń (wówczas argument funkcji bt81x.touch_loop() przyjmuje wartość –1):

bt81x.touch_loop(((-1, pressed), ))

Wróćmy do operacji przygotowywania interfejsu graficznego. Ekran wprowadzania adresu IP, będzie składał się z 4-wierszowej klawiatury (cyfry od 0-9, symbol kropki oraz przycisk umożliwiający skasowanie błędnie wprowadzonych wartości), przycisku Connect oraz prostej grafiki. Całość operacji związanych z przygotowaniem interfejsu, została zrealizowana w postaci jednej funkcji showAddrScreen(), której kod znajduje się na listingu 4.

Poprzez zastosowanie metody bt81x.tag() w funkcji showAddrScreen(), do przycisku Connect przypisano wartość identyfikatora TAG równą 1.

Przyciski z klawiatury wygenerowanej za pomocą szeregu wywołań bt81x.add_keys(), jako wartość pola TAG zwracają kody ASCII, odpowiadające oznaczeniom poszczególnych klawiszy. Obsługa wszystkich zdarzeń realizowana jest w funkcji zwrotnej pressed(), jak zdefiniowano to w wywołaniu bt81x.touch_loop(). Fragment funkcji pressed(), związany z obsługą klawiatury, pokazuje listing 5.

Wywołanie funkcji showAddrScreen() realizowane jest w pętli while() (w pliku main.py), do momentu wybrania przycisku Connect (proces ten jest powtarzany, jeśli wprowadzony adres IP urządzenia jest nieprawidłowy) (listing 6).

Finalny efekt wywołania funkcji showAddrScreen() został pokazany na fotografii 3.

Fotografia 3. Interfejs wprowadzania adresu IP dla urządzenia Philips Hue Bridge

Po poprawnym wskazaniu adresu IP urządzenia Philips Hue Bridge, panel kontrolny przechodzi do etapu autoryzacji (zagadnienia związane bezpośrednio z nawiązaniem połączenia, autoryzacją oraz protokołem komunikacji z Philips Hue Bridge, zostaną omówione w dalszej części artykułu). W tym miejscu, komunikat wyświetlany dla użytkownika, ograniczy się wyłącznie do prostej grafiki oraz krótkiego komunikatu, z prośbą o wciśnięcie przycisku umieszczonego na obudowie mostka Philips (jest to potwierdzenie, że użytkownik systemu ma fizyczny dostęp do urządzenia). Za wyświetlenie komunikatu oraz grafiki, odpowiedzialna będzie funkcja showAuthScreen() z pliku gui.py (listing 7).

W pliku main.py, przed wyświetleniem komunikatu z prośbą o autoryzację, dodajmy krótki ekran pośredni (z zastosowaniem uprzednio przygotowanej funkcji showSpinner()). W tym czasie do pamięci GRAM kontrolera BT81x, wgrywamy plik graficzny gui_auth_hue.png, który jest potrzebny w konstrukcji interfejsu z funkcji showAuthScreen(). Wszystkie operacje wykonywane zostaną w pętli while(), do momentu prawidłowej autoryzacji użytkownika (funkcja createUser() zostanie omówiona w dalszej części artykułu) (listing 8).

Opuszczenie pętli while() z listingu 8, jest równoznaczne z prawidłowym zakończeniem procesu łączenia z Philips Hue Bridge. Przyszedł więc czas na wyświetlenie głównego ekranu sterującego, złożonego z przycisków ON/OFF dla dwóch żarówek, oraz elementów sterujących dla jednej „kolorowej” żarówki (fotografia otwierająca).

Główny panel kontrolny jest zdecydowanie bardziej rozbudowany od poprzednich ekranów aplikacji – każdorazowe dodanie 10 przycisków i 8 elementów tekstowych mocno skomplikowałoby główną funkcję programu, a ewentualne wprowadzanie korekt położeń poszczególnych elementów interfejsu byłoby bardzo uciążliwe.

W tym celu, wszystkie komponenty głównego interfejsu opisane zostały za pomocą tablicy JSON, a umieszczenie ich na liście pogrupowane w dwie pętle for() (osobną dla elementów typu Button oraz Text). Fragmenty opisów JSON pokazuje listing 9.

Za parsowanie poszczególnych elementów opisu JSON, dodanie ich do listy oraz jej finalne wyświetlenie, odpowiada funkcja showMainMenu(), umieszczona w pliku gui.py (listing 10).

Cykliczne wywołanie funkcji showMainMenu(), umieszczone zostało w pliku main.py, w głównej pętli programu, która aktualizuje wartości prezentowane w interfejsie graficznym, sprawdza status zmiennych, reprezentujących stany sterowanych żarówek, oraz, w przypadku wystąpienia zmian (wynikających z obsługi panelu dotykowego i obsługi zdarzeń w funkcji zwrotnej pressed()), wysyła komunikaty do urządzenia Philips Hue Bridge (listing 11).

Zaktualizowany fragment funkcji pressed() znajduje się na listingu 12.

Udało się do tej pory skutecznie pominąć wszystkie aspekty związane z komunikacją z mostkiem Philips Hue. Czas na poświęcenie kilku chwil temu urządzeniu oraz sposobom jego komunikacji ze światem. W najpopularniejszej konfiguracji, Philips Hue Bridge pełni rolę pośrednika w komunikacji pomiędzy aplikacją mobilną, a urządzeniami końcowymi. Twórcy systemu Philips Hue, poszli jednak o krok dalej i zamiast tworzyć zamknięty system na linii aplikacja mobilna – mostek, zdecydowali się na przygotowanie otwartego i dobrze udokumentowanego API, umożliwiając tym samym programistom tworzenie własnych urządzeń sterujących i zarządzających pracą systemu. Komplet informacji związanych z tworzeniem własnych aplikacji, został udostępniony na stronie producenta: https://bit.ly/3qPCh7d.

Kolejnym ułatwieniem dla programistów jest przygotowanie prostego interfejsu, umożliwiającego przetestowanie API i działania systemu, bez tworzenia dedykowanej aplikacji. Interfejs ten – nazwany CLIP API Debugger – udostępniono pod adresem:

https://<bridge-ip-address>/debug/clip.html

Adres mostka Philips można ustalić wykorzystując protokół UPnP, poprzez stronę https://bit.ly/3mfuexi lub poprzez odczyt konfiguracji domowego routera. Wygląd okna interfejsu CLIP API Debugger pokazuje rysunek 5.

Rysunek 5. Interfejs panelu CLIP API Debugger

Komunikacja z mostkiem realizowana jest za pomocą wywołań HTTPS oraz REST API, dlatego okno interfejsu zostało podzielone na pole adresu URL, wyboru typu metody (GET, PUT, POST lub DELETE) oraz sekcji BODY, w której umieszczane są zapytania w formacie JSON. Zanim przejdziemy do realizacji zapytań sterujących pracą żarówek, niezbędne jest uprzednie utworzenie nowego użytkownika oraz jego autoryzacja.

Aby utworzyć nowego użytkownika, wykonajmy następujące wywołanie:

URL: /api
Body: {"devicetype":"my_hue_app#IoT Display"}
Method: POST

W odpowiedzi uzyskamy:

[
{
"error": {
"type": 101,
"address": "",
"description": "link button not pressed"
}
}
]

Aby zwiększyć bezpieczeństwo systemu, niezbędna jest odpowiednia autoryzacja użytkownika. W otrzymanym komunikacie użytkownik jest proszony o wciśnięcie przycisku, umieszczonego na obudowie urządzenia – ten zabieg ma na celu potwierdzenie, że osoba próbująca uzyskać dostęp do sterowania oświetleniem, ma również fizyczny dostęp do mostka sterującego. Wciśnięcie przycisku oraz ponowne wysłanie powyższego zapytania POST, zostanie potwierdzone poniższym komunikatem:

[
{
"success": {
"username": "JxeQj8Xvi1zLDBnDz09w1aCjWA80rDxbQNYUlOCn"
}
}
]

Wartość pola username to nowa nazwa autoryzowanego użytkownika, która będzie wykorzystywana w dalszej komunikacji. Wróćmy na chwilę do kodu naszej aplikacji i zastanówmy się jak zrealizować powyższe zadania, z wykorzystaniem języka Python i zestawu bibliotek dostarczanych przez środowisko Zerynth. Z pomocą w tym zadaniu przychodzi moduł requests. Dla programistów Python nazwa ta jest zapewne dobrze znana – moduł pod kątem API jest inspirowany dość popularnym modułem o tej samej nazwie. Umożliwia szybką implementację obsługi HTTP oraz wywołań GET, POST, PUT, DELETE, w postaci pojedynczych funkcji. Pełna dokumentacja API dla modułu requests została udostępniona pod adresem: https://bit.ly/3qPFwM4.

Funkcję createUser(), bazującą na wywołaniach z modułu request, odpowiedzialną za utworzenie nowego użytkownika, pokazuje listing 13. Funkcja createUser() z listingu 13, wykonywana jest w pętli, aż do momentu odczytu wartości success, w odpowiedzi zwracanej przez mostek. Do głównej pętli programu funkcja ta zwraca wartość odczytaną z pola username, która zostanie wykorzystana w kolejnych wywołaniach sterujących stanem żarówek (listing 14).

Uzyskanie nazwy autoryzowanego użytkownika, umożliwia nam odczyt konfiguracji systemu, tj. listy podłączonych żarówek, ich stanu, numerów identyfikacyjnych, itp.:

URL: /api/<username>/lights
Body: [none]
Method: GET

Fragment odpowiedzi systemu, dla konfiguracji z trzema żarówkami pokazuje listing 15.

Aktualny stan pracy poszczególnych żarówek można sprawdzić, poprzez dodanie w zapytaniu GET numeru adresu identyfikacyjnego urządzenia, np.:

URL: /api/<username>/lights/2
Body: [none]
Method: GET

Zmiana stanu standardowej żarówki, realizowana jest poprzez wywołanie metody PUT:

URL: /api/<username>/lights/2/state
Body: {"on":false}
Method: PUT

Zmiana stanu kolorowej żarówki wymaga od użytkownika określenia nie tylko jej nowego stanu pracy ale również określenia wartości koloru, jasności oraz nasycenia:

URL: /api/<username>/lights/2/state
Body: {"on":true, "sat":254, "bri":254,"hue":10000}
Method: PUT

Na bazie powyższego API, z użyciem modułu requests, przygotowano funkcje turnLight() oraz changeColor() (listing 16).

Pełny kod źródłowy aplikacji został udostępniony pod adresem: http://bit.ly/3inwPok.

Łukasz Skalski
contact@lukasz-skalski.com