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.

Lokalne 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.

Wywołanie API bramki spoza sieci lokalnej (z Internetu) możliwe jest przez API Asystenta domowego. Takie wywołania wymagają uwierzytelnienia i szyfrowania (protokół https). Całe lokalne API bramki jest dostępne przez API Asystenta domowego - opisujemy to dokładnie poniżej.

Tekst JSON MUSI być zakodowany w Unicode. Domyślne kodowanie to UTF-8.

Znaki inne niż ASCII (np. symbole istniejące w językach świata), przed wysłaniem do api należy skonwertować do ich znaków kodowych w UTF-8. Takie konwertowanie wykonywane jest zwykle automatycznie przez program / klienta REST, ale można to zrobić też ręcznie, np na tych stronach:

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

Dostępne parametry TTS

ParametrDomyślna wartośćOpis / Dostępne opcje
text-Tekst do przeczytania / Dowolny tekst
pitch1.0Ton mowy / 1.0 to normalny ton, niższe wartości obniżają ton syntetyzowanego głosu, większe wartości go zwiększają.
rate1.0Szybkość mowy / 1.0 to normalna szybkość mowy, niższe wartości spowalniają mowę (0,5 to połowa normalnej szybkości mowy), większe wartości ją przyspieszają (2,0 to dwukrotność normalnej szybkości mowy).
languagepl_PLJęzyk / Inne dostępne opcje to uk_UA, en_GB, en_US
voicepl-pl-x-oda-localGłos / Dostępne opcje to:
pl_PL
  • 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"

uk_UA
  • uk-UA-language - "Mariya",

en_GB
  • en-GB-language - "Allison",

en_US
  • en-us-x-sfg#female_2-local - "Sophia",

path-Ścieżka do zapisu pliku / TODO
format-Format pliku / mp3 lub wav

Przykłady komunikatów:

  • informacja o alarmie pożarowym po angielsku

Attention. Attention. This is Fire alarm! Evacuation on fire route number five in two minutes

{
"language": "en_GB",
"voice": "en-GB-language",
"rate": "0.9",
"text": "Attention. Attention. This is Fire alarm!. Evacuation on fire route number five in two minutes."
}
  • informacja o przerwie po ukraińsku

Ми запрошуємо вас на 30-хвилинну перерву на сніданок. Смачного.

{
"language": "uk_UA",
"voice": "uk-UA-language",
"rate": "1",
"text": "\u041C\u0438 \u0437\u0430\u043F\u0440\u043E\u0448\u0443\u0454\u043C\u043E \u0432\u0430\u0441 \u043D\u0430 30-\u0445\u0432\u0438\u043B\u0438\u043D\u043D\u0443 \u043F\u0435\u0440\u0435\u0440\u0432\u0443 \u043D\u0430 \u0441\u043D\u0456\u0434\u0430\u043D\u043E\u043A. \u0421\u043C\u0430\u0447\u043D\u043E\u0433\u043E."
}
  • ogłoszenie po polsku

Mamy więcej zamówień do zrealizowania, prosimy chętnych o pozostanie 2 godziny dłużej w pracy. Płacimy 200% extra.

{
"language": "pl_PL",
"text": "Mamy wi\u0119cej zam\u00F3wie\u0144 do zrealizowania, prosimy ch\u0119tnych o pozostanie 2 godziny d\u0142u\u017Cej w pracy. P\u0142acimy 200% extra."
}

Przykład wywołania API z języka Python

import requests
requests.post('http://ais-dom.local:8122/text_to_speech', json={'text':'cześć'})

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.<br/>polskieradio.<br/>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] (https://developer.android.com/reference/android/media/PlaybackParams)
setPlaybackSpeed1Szybkość odtwarzania
seekTo100Przewiń do pozycji w Milisekundach (ms)
skipTo100Przeskocz do pozycji w Milisekundach (ms)
tone86Odtworzenie tonu , szczegóły w [dokumentacji ToneGenerator Android] (https://developer.android.com/reference/android/media/ToneGenerator)
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