TapHome

Denon HEOS

Packet Parser → TCP
Inviato da
Ultimo aggiornamento: 04. 2026
Denon HEOS

Denon HEOS è una piattaforma audio multiroom wireless costruita attorno alla HEOS Command Line Interface (CLI) — un protocollo testuale che espone ogni diffusore, soundbar, amplificatore e componente HEOS-enabled sulla rete locale sulla porta TCP 1255. TapHome utilizza questo protocollo per controllare riproduzione, volume, mute e modalità di riproduzione dei diffusori HEOS senza alcuna dipendenza dal cloud.

Il template copre l’intera gamma wireless HEOS (HEOS 1, 3, 5, 7), le soundbar HEOS Bar e HomeCinema, i componenti HEOS Amp / Link / Drive, l’HEOS Sub e i più recenti diffusori Denon Home 150 / 250 / 350 e la Sound Bar 550. È sufficiente un solo dispositivo HEOS sulla LAN — la CLI espone ogni altro player HEOS della rete tramite l’endpoint player/get_players.

Questo template è destinato esclusivamente a diffusori HEOS, soundbar e amplificatori HEOS-enabled. I ricevitori AVR Denon e Marantz (serie AVR-X, serie SR, ecc.) utilizzano un protocollo Denon/Marantz Telnet control separato sulla porta 23 e non sono compatibili con questo template, nemmeno sui modelli che includono anche HEOS Built-in.

Connessione di rete

HEOS comunica via TCP sulla porta 1255 con comandi ASCII in chiaro terminati da \r\n e restituisce risposte in formato JSON. Non è richiesta autenticazione — qualsiasi dispositivo sulla stessa LAN può connettersi alla porta CLI.

Prima che TapHome possa controllare il dispositivo, il diffusore HEOS deve essere configurato tramite l’app mobile HEOS:

  1. Installate l’app HEOS (Android / iOS) su uno smartphone o tablet nella stessa rete Wi-Fi.
  2. Collegate il dispositivo HEOS al Wi-Fi o all’Ethernet tramite la procedura guidata iniziale dell’app.
  3. Assicuratevi che il firmware sia aggiornato (il template è basato su HEOS CLI v1.17, corrispondente al firmware 2.41.140 o successivo).
  4. Annotate l’indirizzo IP del diffusore — disponibile nell’app HEOS in Settings → My Devices → About oppure nella lista client DHCP del router.

Utilizzate un IP statico o una prenotazione DHCP per il dispositivo HEOS a cui si collega TapHome. Il diffusore funge da gateway verso tutti gli altri player HEOS, quindi un indirizzo stabile mantiene raggiungibile l’intero ecosistema.

La CLI HEOS non prevede autenticazione. Mantenete il diffusore in un segmento LAN attendibile — qualsiasi dispositivo con accesso di rete alla porta 1255 può controllare la riproduzione.

Configurazione

Parametri di connessione in TapHome

Durante l’importazione del template nell’app TapHome, inserite l’indirizzo IP del diffusore HEOS nel parametro IP Address. La porta TCP 1255 e il framing del protocollo sono già configurati nel template. TapHome apre una singola connessione TCP persistente e vi fa transitare i comandi HEOS CLI.

Inizializzazione del PlayerId

Ogni comando heos://player/* richiede un player id (pid) — un intero con segno di grandi dimensioni che HEOS assegna dinamicamente a ciascun diffusore sulla rete. Il template lo memorizza nella variabile personalizzata PlayerId. Poiché HEOS genera il pid dinamicamente per ogni rete, il template arriva con un valore segnaposto (-1857880384) che va sostituito alla prima configurazione.

Il modulo espone due service action per scoprire e assegnare il pid. Eseguitele una volta dopo l’importazione del template:

  1. Get Players — invia heos://player/get_players e memorizza la risposta JSON nella variabile di modulo PlayersResponse. Il service attribute Players del modulo mostra quindi l’elenco dei player HEOS visibili in rete, con nome, pid, modello e indirizzo IP.
  2. Set Player Id — riceve un parametro Index (posizione 0-based nell’array Players) e scrive il pid corrispondente nella variabile personalizzata PlayerId. Selezionate l’indice del diffusore che TapHome deve controllare — un modulo TapHome è legato a un solo player HEOS per volta.

Dopo questi due passaggi, tutti i dispositivi figli (Volume, Mute, Play, Pause, ecc.) operano sul diffusore selezionato. Per controllare un secondo player HEOS, importate una seconda istanza del template sullo stesso IP HEOS (o su un altro) e ripetete il passaggio Set Player Id con un indice diverso.

Se l’attributo Players è vuoto al primo avvio, il modulo HEOS CLI potrebbe essere in modalità dormiente. Eseguite nuovamente Get Players dopo qualche secondo — HEOS avvia il core CLI alla prima connessione e può impiegare qualche istante per enumerare tutti i player.

Variabili del dispositivo

Due dispositivi figli hanno variabili personalizzabili dopo l’importazione del template:

DispositivoVariabileDefaultNote
Play URLURLMP3 campanello PixabayQualsiasi URL HTTP(S) diretto verso uno stream o file audio
Volume Up / Volume DownStep5Variazione di volume a ogni pressione; la specifica HEOS limita il range a 1–10

Aprite il dettaglio di ciascun dispositivo nell’app TapHome e impostate queste variabili sui valori desiderati. I caratteri speciali URL-encoded nello stream URL (&, =, %) sono gestiti dallo script del template.

Funzionalità del dispositivo

Il template espone 12 dispositivi figli che coprono riproduzione, volume, mute e streaming URL per un singolo player HEOS.

Controllo del volume

Il dispositivo Volume è un dimmer che legge heos://player/get_volume (livello 0–100) e lo scala nell’intervallo dimmer 0.0–1.0 (Le := level / 100). La scrittura invia heos://player/set_volume con ROUND(Le * 100). Il volume viene interrogato ogni 2,5 secondi, quindi le variazioni esterne (dall’app HEOS o da un altro controller) si riflettono in TapHome al ciclo successivo.

Volume Up e Volume Down sono pulsanti che inviano heos://player/volume_up e heos://player/volume_down con il passo Step configurabile. Utile per l’associazione a interruttori fisici a parete o a smart rule.

Mute

Mute è un interruttore che legge heos://player/get_mute e scrive heos://player/set_mute con state=on|off. Quando disattivato, il diffusore viene silenziato senza modificare il livello di volume sottostante.

Transport

Quattro pulsanti coprono i comandi base di transport:

  • Play — scrive heos://player/set_play_state?state=play
  • Pause — scrive heos://player/set_play_state?state=pause
  • Stop — scrive heos://player/set_play_state?state=stop
  • Next Track — scrive heos://player/play_next
  • Previous Track — scrive heos://player/play_previous

Sono pulsanti solo di scrittura — il template non rilegge lo stato di riproduzione corrente, quindi i pulsanti transport non riflettono se il diffusore sta effettivamente suonando.

Modalità di riproduzione

Play Mode è un interruttore multi-valore che combina i flag HEOS repeat e shuffle in un enum a 6 stati, letto e scritto tramite heos://player/get_play_mode e heos://player/set_play_mode:

ValoreModalità
0Nessuna ripetizione, nessuno shuffle
1Ripeti tutto
2Ripeti uno
3Shuffle, nessuna ripetizione
4Shuffle, ripeti tutto
5Shuffle, ripeti uno

Il template XML riserva nella configurazione multi-valore gli slot 6–9, che sono però inutilizzati — solo i valori 0–5 sono stati raggiungibili.

Preset QuickSelect

Quick Select è un interruttore multi-valore di sola scrittura (1–9) che attiva un preset HEOS QuickSelect tramite heos://player/play_quickselect?id={1-9}. I Quick select sono memorizzati sul player stesso (tipicamente tramite un Denon AVR o HEOS Bar abbinato) e possono contenere un ingresso, una sorgente o una stazione preconfigurati.

Quick Select è definito nella specifica HEOS §4.2.24 come comando AVR-only. Funziona su HEOS Amp, HEOS Link, HEOS Bar e prodotti AVR/receiver HEOS-enabled, ma restituisce un errore sui diffusori HEOS wireless autonomi come HEOS 1, 3, 5 e 7.

Play URL (stream personalizzato)

Play URL è un pulsante che trasmette un URL audio HTTP(S) arbitrario al player HEOS selezionato tramite heos://browse/play_stream?pid={PlayerId}&url={URL}. La variabile URL del dispositivo contiene la destinazione dello stream — di default un MP3 campanello Pixabay come esempio, e viene tipicamente sovrascritta con uno stream di radio internet, un suono di notifica o qualsiasi URL audio diretto.

Buoni utilizzi: notifiche del campanello, annunci vocali da un server HTTP locale, riproduzione di un URL radio fisso senza ricorrere a HEOS Favorites.

Funzionalità aggiuntive

Il protocollo HEOS CLI espone molte più funzioni di quelle attualmente implementate nel template. Possono essere aggiunte in un aggiornamento futuro:

  • Metadati Now Playing (player/get_now_playing_media) — titolo corrente, artista, album e URL copertina come attributi stringa.
  • Feedback dello stato di riproduzione (player/get_play_state) — rilettura di play / pause / stop, così i pulsanti transport riflettono lo stato effettivo.
  • Toggle Mute (player/toggle_mute) — singolo comando per alternare il mute senza leggere prima lo stato.
  • Gestione della coda (player/get_queue, play_queue, clear_queue) — navigazione e manipolazione della coda di riproduzione corrente.
  • Preferiti e preset (browse/play_preset) — attivazione di HEOS Favorites salvati per numero di preset, più semplice di un Play URL grezzo per stazioni memorizzate.
  • Selezione ingressi fisici (browse/play_input) — commutazione su AUX / Line-In su HEOS Amp, Link e modelli AVR.
  • Raggruppamento multiroom (group/*) — creazione, distruzione e controllo volume di gruppo per riproduzione sincronizzata in tutta la casa.
  • Manutenzione firmware (system/check_update, system/reboot) — verifica aggiornamenti firmware e riavvio remoto.
  • Change event (system/register_for_change_events) — notifiche push opzionali per variazioni di volume, stato e now-playing al posto del polling.
  • Accesso all’account HEOS (system/sign_in) — necessario per accedere ai servizi di streaming a pagamento (Tidal, Amazon Music, Deezer, stazioni TuneIn personalizzate) da TapHome.

Risoluzione dei problemi

L’attributo Players rimane vuoto dopo Get Players

HEOS esegue il modulo CLI in modalità dormiente e avvia il core alla prima connessione socket, operazione che può richiedere qualche secondo. Attendete 5–10 secondi ed eseguite nuovamente Get Players. Se è ancora vuoto, verificate:

  1. La CCU TapHome raggiunge l’IP del diffusore sulla porta TCP 1255 (stessa LAN / subnet, nessun firewall intermedio).
  2. Il dispositivo HEOS è completamente online nell’app mobile HEOS — la CLI non è disponibile fino al completamento della configurazione Wi-Fi iniziale.
  3. L’indirizzo IP nel modulo corrisponde ancora al diffusore — i rinnovi DHCP possono modificarlo. Usate una prenotazione DHCP o un IP statico.
Tutti i comandi dei dispositivi restituiscono “ID Not Valid”

La variabile personalizzata PlayerId o mantiene ancora il default del template (-1857880384) oppure punta a un pid che non esiste più (ad esempio, dopo un factory reset del diffusore). Rieseguite Get Players seguito da Set Player Id con l’indice corretto.

L’azione Play URL non fa nulla o restituisce un errore

Lo script Play URL del template attuale presenta una particolarità nota: fa riferimento a playerId (minuscolo) invece che alla variabile personalizzata PlayerId. Se l’azione non ha effetto, aprite nell’app TapHome lo script del dispositivo Play URL e correggete il nome della variabile in PlayerId. Dopo questa correzione l’azione invia correttamente heos://browse/play_stream. Verificate inoltre che lo stream URL sia raggiungibile dal diffusore HEOS e utilizzi un formato audio supportato (MP3, AAC, WAV — gli stream HLS non sono accettati in modo affidabile).

Quick Select restituisce un errore

Quick Select funziona solo su prodotti AVR, amplificatori e soundbar HEOS-enabled. Sui diffusori HEOS wireless (HEOS 1, 3, 5, 7 e Denon Home senza funzioni soundbar) usate invece Play URL o gli stream preferiti.

Le modifiche fatte nell’app HEOS non sono visibili in TapHome

Il template interroga lo stato ogni 2,5 secondi per Volume, Mute e Play Mode. Lo stato transport (Play / Pause / Stop) non è interrogato — sono solo pulsanti. Se un controller esterno ha modificato la modalità di riproduzione o associato un nuovo account streaming, disconnettere e riconnettere il modulo TapHome al diffusore forza una nuova sessione CLI.

Più player HEOS — come controllarne più di uno

Un modulo TapHome controlla esattamente un player HEOS (un pid). Per controllare un secondo diffusore, importate una seconda istanza del template Denon HEOS. L’indirizzo IP può puntare allo stesso dispositivo HEOS — la CLI di un diffusore raggiunge ogni altro player HEOS della rete — e l’azione Set Player Id con un indice diverso collega il secondo modulo a un diffusore differente.

Dispositivi disponibili

Diffusore Denon HEOS Modulo
Attributi di servizio
PlayerArray JSON dei player HEOS raggiungibili in rete (nome, pid, modello, IP, versione). Popolato dall'azione Get Players; utilizzato per scegliere l'Index per Set Player Id.
Azioni di servizio
Ottieni playerIndividua tutti i player HEOS sulla rete inviando heos://player/get_players. La risposta viene memorizzata nell'attributo Player e deve essere eseguita prima di Set Player Id.
Imposta Player IdCollega questo modulo TapHome a un singolo player HEOS. Prende l'indice 0-based dalla lista Player e scrive il pid corrispondente nella variabile personalizzata PlayerId. Necessario dopo Get Players affinché i dispositivi figli funzionino.
Variabili personalizzate

Denon HEOS speaker

Scrittura (modulo)
# 1. Run Get Players action
					# 2. Save and go back
					# 3. Review the Players attribute in the top of page
					# 4. Run Set Player Id with index of your choice
Listener
VAR response := TOSTRING(RECEIVEDBYTES);
					VAR command := PARSEJSON(response, "heos.command", 1);
					VAR result := PARSEJSON(response, "heos.result", 1);
					VAR message := PARSEJSON(response, "heos.message", 1);

					IF (result = "fail" AND INDEXOF(message, "ID Not Valid") >= 0)
					ADDERROR("PlayerId is not set properly.");
					END

					IF (command = "player/get_players")
					IF (result = "fail")
					ADDERROR("Error: " + message);
					ELSE
					PlayersResponse := response;
					END
					END
Attributi di servizio
Players
PARSEJSON(PlayersResponse, "payload");
Azioni di servizio
Get Players
SENDDATA("heos://player/get_players");
Set Player Id
Parametri: Index (0–20 Index)
PlayerId := PARSEJSON(PlayersResponse,"payload[" + Index + "].pid");
Mute diffusore Interruttore

Disattiva o riattiva l'uscita audio sul player HEOS selezionato senza modificare il livello di volume sottostante.

boolean switch
Valori / Stati: Muted · Unmuted

Mute diffusore

Lettura stato interruttore
SENDDATA("heos://player/get_mute?pid=" + PlayerId);
Scrittura stato interruttore
VAR mute := SWITCH(St, 0, "off", 1, "on", "off");
							SENDDATA("heos://player/set_mute?pid=" + PlayerId + "&state=" + mute);
Listener
VAR responseJson := TOSTRING(RECEIVEDBYTES);

							IF(PARSEJSON(responseJson, "heos.command", 1) = "player/get_mute")
							VAR mute := PARSETEXT(responseJson, "state=");
							St := SWITCH(mute, "off", 0, "on", 1, 0);
							END
Prossima traccia Pulsante
button push

Prossima traccia

Scrittura stato pulsante
SENDDATA("heos://player/play_next?pid=" + PlayerId);
Pausa Pulsante
button push

Pausa

Scrittura stato pulsante
SENDDATA("heos://player/set_play_state?pid=" + PlayerId + "&state=pause")
Riproduci Pulsante
button push

Riproduci

Scrittura stato pulsante
SENDDATA("heos://player/set_play_state?pid=" + PlayerId + "&state=play");
Modalità di riproduzione Interruttore multivalore

Stato combinato di ripetizione e shuffle come enum a 6 valori — 0 nessuna ripetizione, 1 ripeti tutto, 2 ripeti uno, 3 shuffle, 4 shuffle + ripeti tutto, 5 shuffle + ripeti uno.

enum multi-value
Valori / Stati: No repeat · Repeat all · Repeat 1 · Shuffle, no repeat · Shuffle, repeat all · Shuffle, repeat one

Modalità di riproduzione

Lettura stato interruttore
SENDDATA("heos://player/get_play_mode?pid=" + PlayerId);
Scrittura stato interruttore
VAR repeat := SWITCH( IF(Mu > 2, Mu - 3, Mu), 0, "off", 1, "on_all", 2, "on_one", "off");
							VAR shuffle := IF(Mu > 2, "on", "off");
							SENDDATA("heos://player/set_play_mode?pid=" + PlayerId + "&repeat=" + repeat + "&shuffle=" + shuffle);
Listener
VAR responseJson := TOSTRING(RECEIVEDBYTES);
							VAR command := PARSEJSON(responseJson, "heos.command", 1);
							VAR result := PARSEJSON(responseJson, "heos.result", 1);

							IF (command = "player/get_play_mode")
							IF (result = "fail")
							VAR errorMessage := PARSEJSON(responseJson, "heos.message", 1);
							ADDERROR("Error: " + errorMessage);
							ELSE
							VAR repeat := PARSETEXT(responseJson, "repeat=", "&");
							VAR shuffle := PARSETEXT(responseJson, "shuffle=");
							Mu := SWITCH(repeat, "off", 0, "on_all", 1, "on_one", 2, 0) + SWITCH(shuffle, "off", 0, "on", 3, 0);
							END
							END
Riproduci URL Pulsante

Trasmette un URL audio HTTP(S) arbitrario al player HEOS (suoni di campanello, radio internet, annunci vocali). L'URL si configura per dispositivo tramite la variabile personalizzata URL.

button push
Variabile: URL

Riproduci URL

Scrittura stato pulsante
SENDDATA("heos://browse/play_stream?pid=" + playerId + "&url=" + URL);
Listener
VAR response := TOSTRING(RECEIVEDBYTES);
							VAR command := PARSEJSON(response, "heos.command", 1);
							VAR result := PARSEJSON(response, "heos.result", 1);
							VAR message := PARSEJSON(response, "heos.message", 1);

							IF (command = "browse/play_stream")
							IF (result = "fail")
							ADDERROR("Error: " + message);
							ELSE
							VAR success := response;
							END
							END
Traccia precedente Pulsante
button push

Traccia precedente

Scrittura stato pulsante
SENDDATA("heos://player/play_previous?pid=" + PlayerId);
Quick Select Interruttore multivalore

Attiva uno dei preset HEOS QuickSelect 1–9 memorizzati sul player. Solo AVR / HEOS Bar / HEOS Amp — non supportato sui diffusori HEOS wireless standalone.

enum multi-value

Quick Select

Scrittura stato interruttore
IF(Mu != 0)
							SENDDATA("heos://player/play_quickselect?pid=" + PlayerId + "&id=" + Mu);
							END

							# To make this work like a switch, create a following script.
							#
							# IF(Mu != 0)
							#   SLEEP(100);
							#   Mu := 0;
							# END
Stop Pulsante
button push

Stop

Scrittura stato pulsante
SENDDATA("heos://player/set_play_state?pid=" + PlayerId + "&state=stop")
Volume Dimmer

Controllo dimmer del volume del player HEOS. Il livello HEOS 0–100 è mappato sull'intervallo dimmer 0.0–1.0 e interrogato ogni 2,5 secondi.

numeric Unità: % dimmer

Volume

Lettura livello
SENDDATA("heos://player/get_volume?pid=" + PlayerId)
Scrittura livello
SENDDATA("heos://player/set_volume?pid=" + PlayerId + "&level=" + ROUND(Le*100))
Listener
VAR responseJson := TOSTRING(RECEIVEDBYTES);
							VAR command := PARSEJSON(responseJson, "heos.command", 1);
							VAR result := PARSEJSON(responseJson, "heos.result", 1);

							IF (command = "player/get_volume")
							IF (result = "fail")
							VAR errorMessage := PARSEJSON(responseJson, "heos.message", 1);
							ADDERROR("Error: " + errorMessage);
							ELSE
							Le := PARSETEXT(responseJson, "level=") / 100.0;
							END
							END
Riduci volume Pulsante

Riduce il volume del passo Step configurato (default 5, HEOS consente 1–10) tramite il comando heos://player/volume_down.

button push
Variabile: Step

Riduci volume

Scrittura stato pulsante
SENDDATA("heos://player/volume_down?pid=" + PlayerId + "&step=" + Step);
Aumenta volume Pulsante

Aumenta il volume del passo Step configurato (default 5, HEOS consente 1–10) tramite il comando heos://player/volume_up.

button push
Variabile: Step

Aumenta volume

Scrittura stato pulsante
SENDDATA("heos://player/volume_up?pid=" + PlayerId + "&step=" + Step);
Connessione: Packet Parser → TCP
Possibili miglioramenti (14)
  • Now Playing Metadata — Current track artist, album, title, artwork URL, media_id — would require string attributes and a listener to cache the response
  • Play State (read) — Reads play|pause|stop back from the player. Template only writes play state (Play/Pause/Stop buttons) without feedback
  • Toggle Mute — Single-command mute toggle without reading current state; could be a second push-button
  • Check Firmware Update — Trigger firmware update check — useful as maintenance action
  • Heart Beat / Connection Health — Periodic heart_beat command for connection liveness; could map to a module-level online/offline sensor
  • Reboot Speaker — Remote reboot of the HEOS device — natural service action
  • Play Queue — Full queue management (get, play item, remove, save as playlist, clear, move). Template has no queue exposure
  • Music Sources / Browse — Browse and search streaming services (TuneIn, local library, favorites, playlists). Not exposed in template
  • Favorites / Preset Stations — Play a favorite station by preset number 1–N; simpler than Play URL for saved stations
  • Input Source (AUX / Line-In) — Switch to a physical input (inputs/aux_in_1, inputs/line_in_1, etc.) — only applicable to AVR/Amp/Link models
  • Group / Multi-Room Control — Create/destroy groups, group volume, group mute — enables multi-room synchronized playback across HEOS speakers. Not exposed in template
  • Player Info (name, model, version, IP) — Static metadata about the player; useful for diagnostics
  • Change Events (unsolicited push) — Register for change events via system/register_for_change_events and receive push updates (volume, state, now playing, queue). Template relies on polling only
  • HEOS Account Sign In / Out — Required for access to paid streaming services and cloud favorites; no hooks in template

Fonti