
Denon HEOS este o platformă audio multiroom wireless construită în jurul interfeței HEOS Command Line Interface (CLI) — un protocol text care face accesibile în rețeaua locală, pe portul TCP 1255, toate boxele, soundbarurile, amplificatoarele și componentele compatibile HEOS. TapHome folosește acest protocol pentru a controla redarea, volumul, dezactivarea sunetului și modul de redare pe boxele HEOS, fără nicio dependență de cloud.
Șablonul acoperă întreaga gamă wireless HEOS (HEOS 1, 3, 5, 7), soundbarurile HEOS Bar și HomeCinema, componentele HEOS Amp / Link / Drive, HEOS Sub, precum și boxele mai noi Denon Home 150 / 250 / 350 și Sound Bar 550. Este suficient un singur dispozitiv HEOS în rețeaua locală — CLI face accesibile toate celelalte playere HEOS din rețea prin endpointul său player/get_players.
Acest șablon este destinat numai boxelor HEOS, soundbarurilor și amplificatoarelor compatibile HEOS. Receiverele AV Denon și Marantz (seria AVR-X, seria SR etc.) folosesc un protocol separat de control Telnet Denon/Marantz pe portul 23 și nu sunt compatibile cu acest șablon, nici măcar modelele care au și HEOS Built-in.
Conexiunea la rețea
HEOS comunică prin TCP pe portul 1255 cu comenzi text ASCII terminate cu \r\n și returnează răspunsuri JSON. Nu este necesară autentificarea — orice dispozitiv din aceeași rețea locală se poate conecta la portul CLI.
Înainte ca TapHome să poată controla dispozitivul, boxa HEOS trebuie configurată cu aplicația mobilă HEOS:
- Instalați aplicația HEOS (Android / iOS) pe un telefon sau o tabletă conectată la aceeași rețea Wi-Fi.
- Conectați dispozitivul HEOS la Wi-Fi sau Ethernet cu ajutorul asistentului de configurare inițială din aplicație.
- Asigurați-vă că firmware-ul este actualizat (șablonul este realizat pentru HEOS CLI v1.17, ceea ce corespunde firmware-ului 2.41.140 sau mai nou).
- Notați adresa IP a boxei — o găsiți în aplicația HEOS la Settings → My Devices → About sau în lista de clienți DHCP a routerului.
Folosiți o adresă IP statică sau o rezervare DHCP pentru dispozitivul HEOS la care se conectează TapHome. Boxa funcționează ca gateway către toate celelalte playere HEOS, așa că o adresă stabilă menține accesibil întregul ecosistem.
HEOS CLI nu are autentificare. Păstrați boxa într-un segment de rețea locală de încredere — orice dispozitiv cu acces la portul 1255 poate controla redarea.
Configurare
Detaliile conexiunii TapHome
La importul șablonului în aplicația TapHome, introduceți adresa IP a boxei HEOS în parametrul IP Address. Portul TCP 1255 și delimitarea mesajelor protocolului sunt deja setate în șablon. TapHome deschide o singură conexiune TCP permanentă și trimite prin ea comenzile HEOS CLI una după alta.
Inițializarea PlayerId
Fiecare comandă heos://player/* necesită un ID de player (pid) — un număr întreg mare, cu semn, pe care HEOS îl atribuie fiecărei boxe din rețea. Șablonul îl păstrează în variabila personalizată PlayerId. Deoarece HEOS generează pid-urile dinamic pentru fiecare rețea, șablonul este livrat cu o valoare provizorie (-1857880384), care trebuie înlocuită la prima configurare.
Modulul pune la dispoziție două acțiuni de service pentru descoperirea și atribuirea pid-ului. Rulați-le o singură dată după importul șablonului:
- Obținere playere — trimite
heos://player/get_playersși păstrează payloadul JSON în variabila de modulPlayersResponse. Atributul de service Playere al modulului afișează apoi lista playerelor HEOS vizibile în rețea, inclusiv numele, pid-ul, modelul și adresa IP. - Setare ID player — primește parametrul
Index(poziția numerotată de la 0 în matricea Playere) și scrie pid-ul corespunzător în variabila personalizatăPlayerId. Alegeți indexul boxei pe care doriți să o controleze TapHome — același modul TapHome este legat la un moment dat de un singur player HEOS.
După acești doi pași, toate dispozitivele subordonate (Volum, Dezactivare sunet, Play, Pauză etc.) funcționează cu boxa selectată. Pentru a controla un al doilea player HEOS, importați o a doua instanță a șablonului pentru aceeași adresă IP HEOS (sau pentru alta) și repetați pasul Setare ID player cu un alt index.
Dacă atributul Playere este gol la prima rulare, modulul HEOS CLI poate fi în modul inactiv. Rulați din nou Obținere playere după câteva secunde — HEOS pornește nucleul CLI la prima conexiune și poate avea nevoie de puțin timp pentru a enumera toate playerele.
În depozitul de șabloane TapHome există un șablon separat
Denon discovery.xml, care realizează doar căutarea ID-ului de player, ca modul independent. Nu este necesar când folosiți acest șablon HEOS principal — Obținere playere și Setare ID player sunt deja incluse aici. Folosiți șablonul de descoperire numai dacă doriți un modul simplu, dedicat, care oferă doarpid-ul, și intenționați să introduceți manual valoarea într-un alt șablon HEOS.
Variabilele dispozitivelor
Trei dispozitive subordonate au variabile personalizate proprii, configurabile după importul șablonului:
| Dispozitiv | Variabilă | Implicit | Note |
|---|---|---|---|
| Redare URL | URL | MP3 de sonerie de pe Pixabay | Orice adresă URL HTTP(S) directă către un flux sau fișier audio |
| Creștere volum / Reducere volum | Step | 5 | Modificarea volumului la o apăsare; specificația HEOS limitează intervalul la 1–10 |
Deschideți detaliile fiecărui dispozitiv în aplicația TapHome și setați aceste variabile la valorile dorite. Caracterele speciale codificate URL din adresa fluxului (&, =, %) sunt tratate de scriptul șablonului.
Funcțiile dispozitivului
Șablonul oferă 12 dispozitive subordonate care acoperă redarea, volumul, dezactivarea sunetului și streamingul de la adrese URL pentru un singur player HEOS.
Controlul volumului
Dispozitivul Volum este un dimmer care citește heos://player/get_volume (nivel 0–100) și îl convertește în intervalul dimmerului 0,0–1,0 (Le := level / 100). La scriere trimite heos://player/set_volume cu ROUND(Le * 100). Volumul este interogat la fiecare 2,5 secunde, astfel încât modificările făcute din aplicația HEOS sau de pe alt controler apar în TapHome la următorul ciclu.
Creștere volum și Reducere volum sunt dispozitive de tip buton care trimit heos://player/volume_up și heos://player/volume_down cu pasul configurabil Step. Sunt utile pentru legarea la întrerupătoare fizice de perete sau la smart rules.
Dezactivarea sunetului
Dezactivare sunet este un comutator care citește heos://player/get_mute și scrie heos://player/set_mute cu state=on|off. Când sunetul este dezactivat, boxa tace fără ca nivelul volumului să se modifice.
Controlul redării
Cinci dispozitive de tip buton acoperă controlul de bază al redării:
- Play — scrie
heos://player/set_play_state?state=play - Pauză — scrie
heos://player/set_play_state?state=pause - Stop — scrie
heos://player/set_play_state?state=stop - Piesa următoare — scrie
heos://player/play_next - Piesa anterioară — scrie
heos://player/play_previous
Acestea sunt butoane doar pentru scriere — șablonul nu citește starea curentă a redării, așa că butoanele nu arată dacă boxa redă efectiv.
Modul de redare
Mod de redare este un comutator cu mai multe valori care combină indicatorii HEOS repeat și shuffle într-o singură enumerare cu 6 stări, citită și scrisă prin heos://player/get_play_mode și heos://player/set_play_mode:
| Valoare | Mod |
|---|---|
| 0 | Fără repetare, fără redare aleatorie |
| 1 | Repetare toate piesele |
| 2 | Repetare piesă |
| 3 | Redare aleatorie, fără repetare |
| 4 | Redare aleatorie, repetare toate piesele |
| 5 | Redare aleatorie, repetare piesă |
Șablonul XML rezervă pozițiile 6–9 în configurația cu mai multe valori, dar acestea nu sunt folosite — valorile 0–5 sunt singurele stări posibile.
Presetări Quick Select
Quick Select este un comutator cu mai multe valori (1–9) doar pentru scriere, care pornește o presetare HEOS QuickSelect prin heos://player/play_quickselect?id={1-9}. Presetările Quick Select se salvează chiar pe player (de obicei printr-un receiver AV Denon asociat sau prin HEOS Bar) și pot memora o intrare, o sursă sau un post preconfigurat.
Quick Select este definit în specificația HEOS §4.2.24 ca o comandă doar pentru AVR. Funcționează pe HEOS Amp, HEOS Link, HEOS Bar și pe produsele AVR/receiver compatibile HEOS, dar returnează o eroare pe boxele wireless HEOS independente, cum sunt HEOS 1, 3, 5 și 7.
Redare URL (flux propriu)
Redare URL este un buton care transmite către playerul HEOS selectat orice adresă URL audio HTTP(S), prin heos://browse/play_stream?pid={PlayerId}&url={URL}. Variabila de dispozitiv URL conține ținta fluxului — este livrată cu un MP3 de sonerie de pe Pixabay ca exemplu și de obicei se înlocuiește cu un flux de radio pe internet, un sunet de notificare sau orice adresă URL audio directă.
Utilizări potrivite: notificări de sonerie, anunțuri vocale de pe un server HTTP local, redarea unei adrese fixe de radio pe internet fără HEOS Favorites.
Funcții suplimentare
Protocolul HEOS CLI oferă multe funcții în plus față de cele implementate în prezent în șablon. Acestea pot fi adăugate într-o actualizare viitoare a șablonului:
- Metadatele piesei redate (
player/get_now_playing_media) — titlul piesei curente, artistul, albumul și adresa URL a copertei ca atribute text. - Starea redării (
player/get_play_state) — citirea stării play / pauză / stop, pentru ca butoanele să reflecte starea reală. - Comutare dezactivare sunet (
player/toggle_mute) — activarea sau dezactivarea sunetului cu o singură comandă, fără citirea prealabilă a stării. - Gestionarea cozii (
player/get_queue,play_queue,clear_queue) — răsfoirea și modificarea cozii de redare curente. - Favorite și presetări (
browse/play_preset) — pornirea favoritelor HEOS salvate după numărul presetării, mai simplu decât Redare URL pentru posturile salvate. - Selectarea intrării fizice (
browse/play_input) — comutarea pe AUX / Line-In la modelele HEOS Amp, Link și AVR. - Gruparea multiroom (
group/*) — crearea și desființarea grupurilor HEOS și controlul volumului lor pentru redare sincronizată în toată casa. - Întreținerea firmware-ului (
system/check_update,system/reboot) — verificarea actualizărilor de firmware și repornirea de la distanță. - Evenimente de modificare (
system/register_for_change_events) — notificări push opționale pentru modificările de volum, stare și piesă redată, în locul interogării periodice. - Autentificarea în contul HEOS (
system/sign_in) — necesară pentru accesul din TapHome la serviciile de streaming plătite (Tidal, Amazon Music, Deezer, posturi personalizate TuneIn).
Rezolvarea problemelor
Atributul Playere este gol după Obținere playere
HEOS rulează modulul CLI în modul inactiv și pornește nucleul la prima conexiune socket, ceea ce poate dura câteva secunde. Așteptați 5–10 secunde și rulați din nou Obținere playere. Dacă lista este tot goală, verificați că:
- Unitatea centrală TapHome (CCU) poate accesa adresa IP a boxei pe portul TCP 1255 (aceeași rețea locală / subrețea, fără firewall între ele).
- Dispozitivul HEOS este complet online în aplicația mobilă HEOS — CLI nu este disponibil până la finalizarea configurării Wi-Fi inițiale.
- Adresa IP din modul corespunde în continuare boxei — reînnoirea DHCP o poate schimba. Folosiți o rezervare DHCP sau o adresă IP statică.
Toate comenzile dispozitivelor returnează „ID Not Valid”
Variabila personalizată PlayerId conține încă valoarea implicită a șablonului (-1857880384) sau indică un pid care nu mai există (de exemplu, boxa a fost resetată la setările din fabrică). Rulați din nou Obținere playere, apoi Setare ID player cu indexul corect.
Acțiunea Redare URL nu face nimic sau returnează o eroare
Scriptul Redare URL din șablonul actual are o problemă cunoscută: folosește playerId (cu literă mică) în loc de variabila personalizată PlayerId. Dacă acțiunea nu are efect, deschideți scriptul dispozitivului Redare URL în aplicația TapHome și corectați numele variabilei în PlayerId. După această corectură, acțiunea trimite corect heos://browse/play_stream. Asigurați-vă și că adresa URL a fluxului este accesibilă din boxa HEOS și folosește un format audio acceptat (MP3, AAC, WAV — fluxurile HLS nu sunt acceptate în mod fiabil).
Quick Select returnează o eroare
Quick Select funcționează numai pe receiverele AV, amplificatoarele și soundbarurile compatibile HEOS. Pe boxele wireless HEOS (HEOS 1, 3, 5, 7 și boxele Denon Home fără funcții de soundbar) folosiți în schimb Redare URL sau fluxurile favorite.
Modificările făcute în aplicația HEOS nu sunt vizibile în TapHome
Șablonul interoghează starea la fiecare 2,5 secunde pentru Volum, Dezactivare sunet și Mod de redare. Starea redării (Play / Pauză / Stop) nu este interogată — acestea sunt doar butoane. Dacă un alt controler a schimbat modul de redare sau a asociat un nou cont de streaming, deconectarea și reconectarea modulului TapHome la boxă forțează o sesiune CLI nouă.
Mai multe playere HEOS — cum controlați mai mult de unul
Un modul TapHome controlează exact un player HEOS (un pid). Pentru a controla o a doua boxă, importați o a doua instanță a șablonului Denon HEOS. Adresa IP poate indica același dispozitiv HEOS — CLI de pe o boxă poate accesa toate celelalte playere HEOS din rețea — iar acțiunea Setare ID player cu un alt index leagă al doilea modul de o altă boxă.
