Własna integracja - 7. Przykład nowej integracji
Gdy już przebrniemy przez wszystkie części wprowadzenia do własnej integracji i zaczniemy chociaż pobieżnie rozumieć co się tam dzieje, to postarajmy się wykonać coś co ma sens i coś robi.
Bo wiadomo najlepiej się człowiek uczy jak coś próbuje sam zrobić.
Kopia szablonu integracji AIS
Szablon integracji to projekt AIS-hello, który dostepny jest w repozytorium kodów AI-Speaker
Logujemy się w Github, przechodzimy do projektu AIS-hello i robimy jego kopię/rozwidlenie (fork) do własnego repozytorium
Zmieniamy nazwę / domenę integracji
Moja integracja będzie pobierała dane o kursach walut z Narodowego Banku Polskiego, dlatego nazwę ją ais_nbp:
Klonujemy kody z własnego repozytorium
1. na własną bramkę
w konsoli na bramce:
mkdir -p ~/AIS/custom_components
cd ~/AIS/custom_components/
git clone https://github.com/araczkowski/ais_nbp.git
2. na własny komupter desktop/laptop
tam gdzie mamy ulubiony edytor do kodowania w Python
Ja sklonuje te kody bezpośrednio do kodu Asystenta domowego i tam je będę edytował - bo mam dostęp. W ostatniej części opiszę jak to zrobić.
Zmieniamy kody tak żeby działo się to co chcemy
Sprawdzamy API NBP jakie ma zasoby i jaki zwraca wyniki:
testujemy klientem RESTful działanie API, np. informacja o cenie złota w przeglądarce w formacie JSON:
Testowanie
Gdy już nasz integracja robi to co ma robić to ją testujemy w aplikacji:
- Sprawdzamy czy konfigurator działa poprawnie i integracja się dodaje:
- Sprawdzamy czy tworzą się odpowiednie encje
i czy są poprawnie pobierane dane, tu z pomocą przychodzą logi:
Uwaga, tu testowo dodałem odświeżanie informacji co minutę i logowanie ze statusem warning, nie jest to dobry pomysł w przypadku produkcyjnej integracji - patrz poniżej - Dobre praktyki
Dobre praktyki
Ważne jest żeby pisząc integrację zachować kilka zasad, dodałem w tym celu stosowne komentarze w tej przykładowej integracji. integracja która łamią te zasady, nie zostaną nigdy dodane do Asystenta domowego:
- SCAN_INTERVAL
Dostosowany do potrzeb i do bycia dobrym użytkownikiem API. Nie ma potrzeby pytać NBP co minutę o aktualny status waluty. Pytanie co sekundę z kilkuset bramek zostanie zauważone i potraktowane przez adminów jako atak jakiegoś botnetu - nie możemy tak robić.
- Atrybuty sensora zawsze zwracamy z pamięci
Wartość sensora powinna zawsze zwracać tylko informacje z pamięci - self to obiekt sensora w pamięci.
- Pobranie aktualnego statusu sensora
Pytanie serwisu zewnętrzngo czy urządzenia o status, powinno się odbywacć asynchronicznie
nie powinno się wykonywać częstych blokujących operacji I/O (we/wy) takich jak żądania sieciowe bo to prowadzi do problemów i blokowania systemu.
Integracja która powstała podczas pisania tego przykładu wnosi jakąś funkcjonalność - to było jej celem.
Możemy dodać teraz te mowe encje na kartę w widoku:
pytać Jolkę o kursy i cenę złota:
Możemy też dodać automatyzację, która po np. poinformuje nas, ze cena EUR jest 5zł lub cena złota to 300 zł/g… i trzeba sprzedawać 
Skoro integracja może coś robić pożytecznego to oczywiście dodamy ją w kolejnym wydaniu i tu trzeba pamiętać o jednej rzeczy dla tych co będą wykonywać dodanie tej integracji z przykładu:
integracja z custom_components ma priorytet i nadpisuje wbudowaną integrację Asystenta domowego (tak samo jak konfiguracja własna nadpisuje tą którą dostarczamy). Dlatego jeżeli dodasz w custom_components integrację o takiej samej nazwie domeny jak nasza, np.: ais_nbp to system będzie używał Twoich kodów a nie naszych wbudowanych.
