API systemu

Wprowadzenie

RESTful API dzia┼éa na protokole http. Komunikacja poprzez ten protok├│┼é odbywa si─Ö za pomoc─ů kilku standardowych metod, my wykorzystujemy g┼é├│wnie metod─Ö POST (do wys┼éania danych) i GET (do pobierania). Webserwisy udost─Öpniane s─ů jako zasoby, do kt├│rych dost─Öp mo┼╝liwy jest poprzez odpowiedni adres URL wywo┼éywany z poziomu protoko┼éu http za pomoc─ů okre┼Ťlonej metody.

Na bramce mamy dwa webowe API:

  1. API bramki (dost─Öp do natywnych zasob├│w systemu Android) na porcie 8122
  2. Standardowe webowe API Home Assistant/Asystenta domowego na tych samych portach, co serwer WWW (80 i 8180 lub w przypadku dost─Öpu z zewn─ůtrz 433)
Wskaz├│wka

Interfejsy API akceptuj─ů i zwracaj─ů tylko obiekty zakodowane w JSON.

W przyk┼éadach poni┼╝ej u┼╝ywamy lokalnej nazwy hosta bramki: ais-dom.local, je┼╝eli bramka nie jest dost─Öpna w Twojej sieci pod t─ů nazw─ů to zamiast ais-dom.local u┼╝yj jej lokalnego adresu IP.

API bramki

Obecnie dost─Öpne s─ů 2 zasoby http://ais-dom.local:8122/text_to_speech i http://ais-dom.local:8122/command

Uwaga

To api dost─Öpne jest tylko w sieci lokalnej, dlatego nie wymagamy uwierzytelnienia i szyfrowania.

Je┼╝eli chcesz wywo┼éa─ç API na bramce z zewn─ůtrz, to robimy to przez API Asystenta domowego, tam wymagamy uwierzytelnienia i mamy szyfrowanie (protok├│┼é https). Ca┼ée lokalne API bramki jest dost─Öpne przez API Asystenta domowego - opisujemy to dok┼éadnie poni┼╝ej.

Zas├│b /text_to_speech

Ten zas├│b pozwala nam na wys┼éanie do bramki metod─ů POST tekstu do przeczytania:

curl -v --header "Content-Type: application/json" \
--request POST \
--data '{"text":"Witaj Jolka"}' \
http://ais-dom.local:8122/text_to_speech

Zas├│b /command

Ten zasób pozwala nam na wysłanie komendy do wykonania. Przykładowa komenda to wysłanie audio do odtwarzania na bramce:

curl -v --header "Content-Type: application/json" \
--request POST \
--data '{"playAudio": "http://stream3.polskieradio.pl:8080/"}' \
http://ais-dom.local:8122/command

Dost─Öpne komendy

KomendaPrzyk┼éadowa warto┼Ť─çOpis
playAudiohttp://stream3.polskieradio.pl:8080/Odtwarzanie audio/video
stopAudiotrueZatrzymanie odtwarzacza
pauseAudiotruePauza odtwarzacza
setVolume50Ustawienie g┼éo┼Ťno┼Ťci odtwarzacza od 0 do 100
upVolumetrueG┼éo┼Ťniej, to samo co naci┼Ťni─Öcie przycisku w pilocie
downVolumetrueCiszej, to samo co naci┼Ťni─Öcie przycisku w pilocie
setPlaybackPitch1Cz─Östotliwo┼Ť─ç audio, szczeg├│┼éy w dokumentacji PlaybackParams Android
setPlaybackSpeed1Szybko┼Ť─ç┬áodtwarzania
seekTo100Przewiń do pozycji w Milisekundach (ms)
skipTo100Przeskocz do pozycji w Milisekundach (ms)
tone86Odtworzenie tonu , szczegóły w dokumentacji ToneGenerator Android
setPlayerShufflefalseOdtwarzanie losowe, przydatne przy Spotify
setTtsVoicepl-pl-x-oda-localZmiana głosu asystenta, dostępne opcje to:
  • pl-pl-x-oda-network - "Jola online",
  • pl-pl-x-oda-local - "Jola lokalnie",
  • pl-pl-x-oda#female_1-local - "Celina",
  • pl-pl-x-oda#female_2-local - "An┼╝ela",
  • pl-pl-x-oda#female_3-local - "Asia",
  • pl-pl-x-oda#male_1-local - "Sebastian",
  • pl-pl-x-oda#male_2-local - "Bartek",
  • pl-pl-x-oda#male_3-local - "Andrzej"
micOntrueW┼é─ůczenie mikrofonu
micOfftrueWy┼é─ůczenie mikrofonu
addBookmarktrueDodanie zakładki do odtwarzanych multimediów, przydatne przy audiobookach
goToActivityActivityMenuPrzej┼Ťcie do aktywno┼Ťci (ekranu na bramce). Dost─Öpne opcje to:
  • ActivityMenu - "Aktywno┼Ť─ç menu - sterowanie na monitorze",
  • SplashScreenActivity - "Sterowanie bez monitora",
  • ExoPlayerActivity - "Aktywno┼Ť─ç odtwarzacz multimedi├│w",
  • ConsoleActivity - "Konsola Asystenta domowego",
  • AndroidSettingsActivity - "Ustawienia systemu Android",
  • SettingsActivity - "Ustawienia Serwisu Asystent domowy na bramce",
  • FilesActivity - "Aplikacja mened┼╝er plik├│w na bramce",
  • AndroidWifiActivity - "Ustawienia WiFi w systemie Android",
  • SpotifyActivity - "Przej┼Ťcie do aplikacji Spotify"

RESTful API Home Assistant

Asystent Domowy udost─Öpnia serwer WWW na porcie 80 oraz 8180

Wywoływanie/testowanie usług w aplikacji

Wskaz├│wka

Aby sprawdzić dostępne usługi w aplikacji, z głównego menu przejdź do Narzędzia deweloperskie -> USŁUGI Z tego miejsca możesz wywoływać/testować dowolne usługi dostępne na bramce.

informacja

Każda usługa ma w aplikacji:

  • opis
  • wylistowane parametry (parametr, opis i przyk┼éadowa warto┼Ť─ç parametru)

dlatego nie będziemy szczegółowo opisywać usług w dokumentacji, podamy tu tylko przykładowe wywołania.

W celu wywołania/przetestowania usługi:

  1. Zaloguj się do aplikacji Asystent domowy z uprawnieniami Administrator.
  2. Przejdź do Narzędzia deweloperskie -> USŁUGI.
  3. Wybierz usługę do wywołania z dostępnej listy.
  4. Podajemy parametry do przekazania w formacie JSON lub YAML.
  5. Naci┼Ťnij przycisk "Wywo┼éaj us┼éug─Ö".

Przykładowy parametr w formacie JSON:

{"text": "Cze┼Ť─ç, jak si─Ö masz?"}

odpowiednik w formacie YAML:

text: "Cze┼Ť─ç, jak si─Ö masz?"

Usługi

Wskaz├│wka

Ca┼ée API bramki (opisane szczeg├│┼éowo powy┼╝ej), dost─Öpne jest z poziomu Asystenta domowego za pomoc─ů us┼éugi ais_ai_service.publish_command_to_frame.

Dzi─Öki temu mo┼╝emy wywo┼éywa─ç api na bramce tak┼╝e z zewn─ůtrz, w bezpieczny spos├│b (szyfrowanie i uwierzytelnienie tokenem).

Usługi

Wywoływanie usług z curl

informacja

Żeby wywołać API Asystenta domowego z zewnętrznego systemu, potrzebujemy token dostępu. Najpierw z poziomu aplikacji wygenerujmy długoterminowy token dostępu (long-lived access token), który będzie ważny 10 lat.

Generowanie tokena dost─Öpu

Przechodzimy w aplikacji na nasz profil, następnie przewijamy na dół strony i wybieramy UTWÓRZ TOKEN:

Tokeny

podajemy nazw─Ö dla tokena:

Tokeny

kopiujemy token:

Tokeny

Uwaga

Nie ma mo┼╝liwo┼Ťci ponownego sprawdzenia warto┼Ťci tokena, dlatego nale┼╝y go skopiowa─ç w bezpieczne miejsce.

Jeżeli chcemy odwołać dostęp do api, to usuwamy token.

Tokeny

Metoda GET na zasobie /api/

Sprawdzamy czy /api/ jest dostępne i czy działa nam uwierzytelnianie.

curl -v -H "Authorization: Bearer TOKEN-DOST─śPU" \
-H "Content-Type: application/json" http://ais-dom.local:8180/api/

Zwraca nast─Öpuj─ůc─ů odpowied┼║, je┼╝eli API dzia┼éa:

{"message": "API running."}

Metoda POST na /api/services/<domain>/<service>

Komponenty dost─Öpne na bramce udost─Öpniaj─ů swoje us┼éugi. Te same us┼éugi komponentu, kt├│re automatycznie wywo┼éujemy w systemie po wyst─ůpieniu okre┼Ťonego zdarzenia, mo┼╝na r├│wnie┼╝ wywo┼éa─ç z zewn─Ötrznego systemu za pomoc─ů API.

Przyk┼éad wywo┼éania us┼éugi czytania tekstu przez bramk─Ö za pomoc─ů curl:

curl -X POST -H "Authorization: Bearer TOKEN-DOST─śPU" \
-H "Content-Type: application/json" \
-d '{"text": "Cze┼Ť─ç! Jak si─Ö masz?"}' \
http://ais-dom.local:8180/api/services/ais_ai_service/say_it