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

#1

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

#2

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.

#3

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.

#4

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

#5

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

#6

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.

#7

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

#8

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.

#9

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

#10

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()

#11

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()

#12

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

#13

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()

#14

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.

#15

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.

#18

Widżet sceny podwójnej do sterowania głośnością uruchamia dedykowane skrypty stworzone wcześniej.

#19

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.