Urządzenia Yamaha z serii Musiccast udostępniają w sieci lokalnej (ethernet i WiFi) Yamaha Extended Control API dla produktów audio i video.
Yamaha udostępniła wersję Basic do kontroli urządzenia w strefie (zonie) oraz Advanced do konfigurowania instalacji multiroom. Udostępnione API jest pełne i pozwala na konfigurowanie instalacji bez używania aplikacji mobilnej Yamaha Musiccast Control. Nie mniej polecam skonfigurować instalację multiroom, urządzenia za pomocą dedykowanej aplikacji.
W załączonych dokumentach znajdziecie pełną dokumentację API. W tym tutorialu dla przykładu pokazane będzie jak za pomocą myGrenton.
- włączyć / wyłączyć głośnik
- zmienić poziom głośności
- odczytać aktualnie odtwarzany utwór
W tym tutorialu będą użyte z API Basic:
- System - informacje i możliwości urządzenia
- ścieżka /YamahaExtendedControl/v1/system/...
- Zone
- ścieżka /YamahaExtendedControl/v1/{zone_id}/...
- Network/USB - kontrola odtwarzania
- ścieżka /YamahaExtendedControl/v1/netusb/...
Na początek należy skonfigurować multiroom Musiccast z pomocą aplikacji mobilnej Yamana Musicast Controller, dalej trzeba poznać adres IP urządzenia / urządzeń jakie nadał serwer DHCP (router).
Następnie należy poznać możliwości naszego sprzętu z punktu widzenia maszyny. Można to zrobić za pomocą end-point http://{adr_ip}/YamahaExtendedControl/v1/system/getFeatures
"zone": [
{
"id": "main",
"func_list": [
"power",
"sleep",
"volume",
"mute",
"sound_program",
"equalizer",
"signal_info",
"prepare_input_change",
"link_control",
"link_audio_delay"
],
...
}]
Przetestować API można za pomocą Postman, cUrl lub aplikacji na Windows Advanced REST Client https://install.advancedrestclient.com/install
Istotna informacja zawarta w zwrotnym JSON to lista "zone" oraz ich id. W tym przykładzie jest (i będzie) jedna zona "main". Jest to potrzebne do sterowania dźwiękiem, gdyż podstawowe API (Basic) daje funkcje dla zone.
Do zintegrowania się z Yamaha Musiccast potrzeba utworzyć następujące obiekty HttpListener do:
- pobierania aktualnego stanu
- /YamahaExtendedControl/v1/main/getStatus
- pobierrania informacji o odtwarzanym utworze
- /YamahaExtendedControl/v1/netusb/getPlayInfo
- sterowania odtwarzaniem
- /YamahaExtendedControl/v1/netusb/setPlayback
- ustawiania poziomu głośności
- /YamahaExtendedControl/v1/main/setVolume
- włączania, wyłączania urządzenia
- /YamahaExtendedControl/v1/main/setPower
Do tego obiekt timera do pobierania informacji z głośnika co 1 sekundę.
Oraz Cechy Użytkownika zdefiniowane w Module Gate Http w celu przechowania informacji o aktualnym stanie.
W krokach wyjaśnione jak skonfigurować powyższe elementy
Na początek trzeba utworzyć Cechy Użytkownika w Gate Http na potrzeby integracji:
- y_volume : liczba, poziom głośności
- y_state : liczba 0/1, wskaźnik czy urządzenia jest włączone czy w stanie czuwania
- y_played_track : string z informacja o aktualnie odtwarzanym utworze
- y_max_volume : liczba, informacja o maksymalnej głośności urządzenia
- y_played_artist : string z informacją o aktualnie odtwarzanym artyście
- y_played_alabum : string z informacją o odtwarzanym albumie
Dalej trzeba stworzyć obiekt wirtualny HttpRequest do pobierania informacji o staniu urządzenia:
- Host : adres ip urządzenia
- Path : /YamahaExtendedControl/v1/main/getStatus, gdzie 'main' to nazwa zony
- ResponseType : JSON
- reszta domyślnie
- zdarzenie OnResponse uruchamia skrypt zapisujące otrzymane dane do Cech Użytkownika.
Skrypt do przetwarzania otrzymanej odpowiedzi na temat stanu urządzenia. Zapisuje informacje o tym czy urządzenie jest włączone czy wyłączone, jaka jest maksymalna dopuszczalna głośność i aktualna głośność.
local body = GATE_HTTP->yGetStateReq->ResponseBody
if body ~= nil then
if body.response_code == 0 then
if body.power == "standby" then
GATE_HTTP->y_state = 0
elseif body.power == "on" then
GATE_HTTP->y_state = 1
end
if body.max_volume ~= nil then
GATE_HTTP->y_max_volume = body.max_volume
end
if body.volume ~= nil then
GATE_HTTP->y_volume = body.volume
end
end
end
Skrypt sprawdza czy dane, które chcemy odczytać istnieją a następnie je przypisuje do cech użytkownika.
Obiekt wirtualny HttpRequest do pobierania informacji o odtwarzanym utworze:
- Host : adres ip urządzenia
- Path : /YamahaExtendedControl/v1/netusb/getPlayInfo
- ResponseType : JSON
- reszta domyślnie
- zdarzenie OnResponse uruchamia skrypt zapisujące otrzymane dane do Cech Użytkownika
Skrypt przetwarzający informację o aktualnie odtwarzanym utworze. Pobiera informację o odtwarzanym utworze, artyście i albumie.
local body = GATE_HTTP->y_get_play_info->ResponseBody
if body ~= nil then
if body.response_code == 0 then
if body.artist ~= nil then
GATE_HTTP->y_played_artist = body.artist
end
if body.track ~= nil then
GATE_HTTP->y_played_track = body.track
end
if body.album ~= nil then
GATE_HTTP->y_played_album = body.album
end
end
end
Dla powyższych obiektów wirtualnych można stworzyć timer, który co 1 sekundę (cecha Interval ustawiona na 1000ms) uruchomi pobieranie aktualnych danych z głośnika po przez uruchomienie metod SendRequest() obiektów Http Request.
W celu odtwarzania, zatrzymania i zmiany utworu, potrzeba obiektu wirtualnego HttpRequest, który będzie łączył się z endpointem setPlayback
- Host : adres ip urządzenia
- Path : /YamahaExtendedControl/v1/netusb/setPlayback
- ResponseType : JSON
- reszta domyślnie
Utworzony w poprzednim kroku obiekt wirtualny HttpRequest będzie wykorzystywany przez skrypt do sterowania odtwarzaniem. Skrypt przyjmuje parametr 'action' określający polecenie do wykonania.
Aby sterować poziomem głośności, trzeba stworzyć obiekt HttpRequest który będzie łączył się z end-point
- Path : /YamahaExtendedControl/v1/main/setVolume
- Host : adres IP urządzenia
- ReposneType : JSON
- pozostałe cechy pozostawiamy w stanie domyślnym
Skrypt do zmniejszania poziomu głośności.
local vol = GATE_HTTP->y_volume
local query = "volume="
if (vol-1) >= 0 then
vol = vol - 1
GATE_HTTP->y_volume = vol
else
vol = 0
end
query = query..vol
GATE_HTTP->y_setVolume->SetQueryStringParams(query)
GATE_HTTP->y_setVolume->SendRequest()
Skrypt do zwiększania poziomu głośności.
local vol = GATE_HTTP->y_volume
local query = "volume="
local max = GATE_HTTP->y_max_volume
if (vol+1) <= max then
vol = vol + 1
GATE_HTTP->y_volume = vol
else
vol = max
end
query = query..vol
GATE_HTTP->y_setVolume->SetQueryStringParams(query)
GATE_HTTP->y_setVolume->SendRequest()
Do włączania i wyłączania urządzenia (głośnika) potrzebny będzie kolejny obiekt wirtualny HttpRequest, który konfigurujemy następująco:
- Host : adres ip urządzenia
- Path : /YamahaExtendedControl/v1/main/setPower
- ResponseType : JSON
- reszta domyślnie
Skrypt do przełączania stanu urządzenia.
if GATE_HTTP->y_state == 0 then
GATE_HTTP->y_state = 1
else
GATE_HTTP->y_state = 0
end
GATE_HTTP->y_toggle->SendRequest()
Powyższe skrypty będę potrzebne do zbudowania interfejsu w myGrenton, na którym zobaczyć można informację o aktualnie odtwarzanym utworze, uruchomić odtwarzanie, zatrzymać, przełączyć utwór, włączyć, wyłączyć urządzenie.
Widżety Value konfigurujemy by pokazywały wskazana Cechę Wbudowaną
#16 Widżet sceny podwójnej do zmiany odtwarzanego utworu wywołuje skrypt, który w parametrze przyjmuje informację o akcji zgodnie z dokumentacją API Yamaha.
#17 Widżet sceny podwójnej do odtwarzania/zatrzymania utworu wywołuje skrypt, który w parametrze przyjmuje informację o akcji zgodnie z dokumentacją API Yamaha.
Widżet sceny podwójnej do sterowania głośnością uruchamia dedykowane skrypty stworzone wcześniej.
Na koniec Widżet do włączania/wyłączania urządzenia. Wywołanie skryptu, który działa jak metoda Switch w modułach.
Wszystko gotowe można wgrać konfiguracje do CLU i Gate oraz przesłać interfejs do urządzenia mobilnego.
