♾ Własna integracja - 7. Przykład nowej integracji

:infinity: 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:
image

Testowanie

Gdy już nasz integracja robi to co ma robić to ją testujemy w aplikacji:

  1. Sprawdzamy czy konfigurator działa poprawnie i integracja się dodaje:

  1. 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:

  1. 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ć.

image

  1. Atrybuty sensora zawsze zwracamy z pamięci
    Wartość sensora powinna zawsze zwracać tylko informacje z pamięci - self to obiekt sensora w pamięci.

  1. 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ć :wink:

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.

Czy ktoś ma źródła API dla stworzenie innych sensorów kursu cen? Interesują mnie sensory ceny surowców np. miedź czy aluminium.

1 polubienie

specjalnie dla Ciebie :slight_smile:

2 polubienia