Yamaha Receiver Binding

This binding connects openHAB with Yamaha Receivers of product line CX-A5000, RX-A30xx, RX-A20xx, RX-A10xx, RX-Vxxx, RX-Z7, DSP-Z7, RX-S600, RX-S601D, HTR-xxxx.

If your hardware is on the list but still does not work, please fill a bug report!

Supported Things

yamahaAVBridgeYamaha Receiver hardware
zoneThingZones of your receiver


Just use the auto discovery feature to detect your hardware. Initially a thing for the main zone will be created. This will trigger a zone detection internally and all available additional zones will appear as new things.

Thing Configuration

To manually add a receiver and its zones a things/yamahareceiver.things file could look like this:

Bridge yamahareceiver:yamahaAV:ReceiverID "Yamaha Receiver Bridge Name" [host="a.b.c.d", refreshInterval=20] {
    Thing zone ZoneID1 "Main Zone Thing Name" @ "location" [zone="Main_Zone", volumeDbMin=-81, volumeDbMax=12]
    Thing zone ZoneID2 "Zone 2 Thing Name" @ "location" [zone="Zone_2"]
    Thing zone ZoneID3 "Zone 3 Thing Name" @ "location" [zone="Zone_3"]
    Thing zone ZoneID4 "Zone 4 Thing Name" @ "location" [zone="Zone_4"]

Configuration parameters for Bridge yamahaAV:

hostyesN/AThe IP address of the AVR to control
portno80The API port of the AVR to control
refreshIntervalno60Refresh interval in seconds
albumUrlnoembedded image URLWhen the album image is not provided by the Yamaha input source, you can specify the default image URL to apply
inputMappingno"" (empty string)Some Yamaha models return different input values on status update than required in the change input commands. See below for details

Configruation parameters for Thing zone:

zoneyes/The zone can be Main_Zone, Zone_2, Zone_3, Zone_4 depending on your device
volumeRelativeChangeFactorno2Relative volume change in percent
volumeDbMinno-80Lowest volume in dB
volumeDbMaxno12Highest volume in dB


The implemented channels for the yamahaAV bridge are:

ChannelopenHAB TypeComment
powerSwitchSwitches the AVR ON or OFF. Your receiver has to be in network standby for this to work.
party_modeSwitchSwitches the party mode. May not be supported on all models.
party_mode_muteSwitchSwitches the mute ON or OFF when in party mode. Write only (state updates are not available). Applicable only when party mode is on. May not be supported on all models.
party_mode_volumeDimmerIncrease or decrease volume when in party mode. Write only (state updates are not available). INCREASE / DECREASE commands only. Applicable only when party mode is on. May not be supported on all models.

The implemented channels for a zone thing are grouped in three groups. These are the zones supported: Main_Zone, Zone_2, Zone_3, Zone_4.

Zone control channels are:

ChannelopenHAB TypeComment
zone_channels#powerSwitchSwitches the zone ON or OFF. Your receiver has to be in network standby for this to work.
zone_channels#muteSwitchMute or Unmute the receiver.
zone_channels#volumeDimmerSet's the receivers volume as percentage.
zone_channels#volumeDBNumberSet's the receivers volume in dB.
zone_channels#inputStringSet's the input selection, depends on your receiver's real inputs. Examples: HDMI1, HDMI2, AV4, TUNER, NET RADIO, etc.
zone_channels#surroundProgramStringSet's the surround mode. Examples: 2ch Stereo, 7ch Stereo, Hall in Munic, Straight, Surround Decoder.
zone_channels#sceneStringSets the scene. Examples: Scene 1, Scene 2, Scene 3, Scene 4. Write only (state updates are not available). May not be supported on all models (e.g. RX-V3900).
zone_channels#dialogueLevelNumberSet's the receivers dialogue level. May not be supported on all models.
playback_channels#presetNumberSet a preset. Not supported by Spotify input. For NET RADIO input there is no way to get current preset (tested on RX-S601D, RX-V3900), so the preset is write only. For RX-V3900 the presets are alphanumeric A1,A2,B1,B2 thus you need to use numbers grater than 100 that represent these presets as follows: 101, 102, 201, 202.
playback_channels#playbackStringSet a play mode or get the current play mode. Values supported: Previous, Play, Pause, Stop, Next. Applies for inputs which support playback (Spotify, SERVER, NET RADIO, Bluetooth). Note that some values may not be supported on certain input type and AVR model combination. For Spotify and Bluetooth all values work, but for NET RADIO input only Play and Stop are supported (tested on RX-S601D).
playback_channels#playback_stationStringGet the current played station (radio). Applies to TUNER and NET RADIO inputs only.
playback_channels#playback_artistStringGet the current played artist.
playback_channels#playback_albumStringGet the current played album.
playback_channels#playback_songStringGet the current played song.
playback_channels#playback_song_image_urlStringGet the current played song image URL. Applies to Spotify and NET RADIO inputs only.
playback_channels#tuner_bandStringSet the band (FM or DAB) for tuner input when device supports DAB+ (e.g. RX-S601D). Values supported: FM, DAB. Applies to TUNER input only.
navigation_channels#navigation_menuStringSelect or display the full or relative path to an item.
navigation_channels#navigation_current_itemNumberGet the current item of the current menu.
navigation_channels#navigation_total_itemsNumberGet the total count items in the current menu.
navigation_channels#navigation_levelNumberGet the current menu level.
navigation_channels#navigation_updownMove the cursor up or down.
navigation_channels#navigation_leftrightMove the cursor to the left or right.
navigation_channels#navigation_selectSelect the current item.
navigation_channels#navigation_backNavigate to the parent menu.
navigation_channels#navigation_backtorootNavigate back to the root menu.

Navigation is not supported by Spotify input.


Basic Setup

For auto linking with Paper UI

Link the items to the channels of your preferred zone (here Main_Zone) in PaperUI after you've saved your items file.


Switch      Yamaha_Power           "Power [%s]"                <switch>
Dimmer      Yamaha_Volume          "Volume [%.1f %%]"          <soundvolume>
Switch      Yamaha_Mute            "Mute [%s]"                 <soundvolume_mute>
String      Yamaha_Input           "Input [%s]"                <video>
String      Yamaha_Surround        "Surround [%s]"             <video>
String      Yamaha_Scene           "Scene []"                  <video>
Number      Yamaha_Dialogue_Level  "Dialogue Level [%d]"       <soundvolume>
For manually linking

Replace the UPNP UDN (here: 96a40ba9) with the real UDN provided by your UPNP discovery. Also replace the zone name with your preferred zone (here Main_Zone).


Switch      Yamaha_Power           "Power [%s]"                <switch>             { channel="yamahareceiver:zone:96a40ba9:Main_Zone:zone_channels#power" }
Dimmer      Yamaha_Volume          "Volume [%.1f %%]"          <soundvolume>        { channel="yamahareceiver:zone:96a40ba9:Main_Zone:zone_channels#volume" }
Switch      Yamaha_Mute            "Mute [%s]"                 <soundvolume_mute>   { channel="yamahareceiver:zone:96a40ba9:Main_Zone:zone_channels#mute" }
String      Yamaha_Input           "Input [%s]"                <video>              { channel="yamahareceiver:zone:96a40ba9:Main_Zone:zone_channels#input" }
String      Yamaha_Surround        "Surround [%s]"             <video>              { channel="yamahareceiver:zone:96a40ba9:Main_Zone:zone_channels#surroundProgram" }
String      Yamaha_Scene           "Scene []"                  <video>              { channel="yamahareceiver:zone:96a40ba9:Main_Zone:zone_channels#scene" }
Switch      Yamaha_Dialogue_Level  "Dialogue Level [%d]"       <soundvolume>        { channel="yamahareceiver:zone:96a40ba9:Main_Zone:zone_channels#dialogueLevel" }

Switch      Yamaha_PartyMode       "Party mode [%s]"           <switch>             { channel="yamahareceiver:yamahaAV:96a40ba9:party_mode" }
Switch      Yamaha_PartyModeMute   "Party mode mute [%s]"      <soundvolume_mute>   { channel="yamahareceiver:yamahaAV:96a40ba9:party_mode_mute" }
Dimmer      Yamaha_PartyModeVolume "Party mode volume []"      <soundvolume>        { channel="yamahareceiver:yamahaAV:96a40ba9:party_mode_volume" }


Switch      item=Yamaha_Power
Switch      item=Yamaha_Mute
Slider      item=Yamaha_Volume
Selection   item=Yamaha_Input            mappings=[HDMI1="Kodi",HDMI2="PC",AUDIO1="TV",TUNER="Tuner",Spotify="Spotify",Bluetooth="Bluetooth","NET RADIO"="NetRadio",SERVER="Server",Straight="Straight"]
Selection   item=Yamaha_Surround         mappings=["2ch Stereo"="2ch Stereo","5ch Stereo"="5ch Stereo","Chamber"="Chamber","Sci-Fi"="Sci-Fi","Adventure"="Adventure"]
Switch      item=Yamaha_Scene            mappings=["Scene 1"="Kodi","Scene 2"="TV","Scene 3"="NET","Scene 4"="Radio"]
Setpoint    item=Yamaha_Dialogue_Level   minValue=0 maxValue=2 step=1

Switch      item=Yamaha_PartyMode
Switch      item=Yamaha_PartyModeMute
Switch      item=Yamaha_PartyModeVolume  mappings=[DECREASE="-", INCREASE="+"]

Note: Some input values for Yamaha_Input might not be supported on your model. Make sure to adjust these values.



String      Yamaha_Playback                 "[]"                    <video>              { channel="yamahareceiver:zone:96a40ba9:Main_Zone:playback_channels#playback" }
String      Yamaha_Playback_Station         "Station [%s]"          <video>              { channel="yamahareceiver:zone:96a40ba9:Main_Zone:playback_channels#playback_station" }
String      Yamaha_Playback_Artist          "Artist [%s]"           <video>              { channel="yamahareceiver:zone:96a40ba9:Main_Zone:playback_channels#playback_artist" }
String      Yamaha_Playback_Album           "Album [%s]"            <video>              { channel="yamahareceiver:zone:96a40ba9:Main_Zone:playback_channels#playback_album" }
String      Yamaha_Playback_Song            "Song [%s]"             <video>              { channel="yamahareceiver:zone:96a40ba9:Main_Zone:playback_channels#playback_song" }
String      Yamaha_Playback_Song_Image      "[]"                    <video>              { channel="yamahareceiver:zone:96a40ba9:Main_Zone:playback_channels#playback_song_image_url" }


Switch      item=Yamaha_Playback            mappings=["Previous"="⏮", "Play"="►", "Pause"="⏸", "Stop"="⏹", "Next"="⏭"]    visibility=[Yamaha_Input=="Spotify", Yamaha_Input=="NET RADIO", Yamaha_Input=="Bluetooth"]
Text        item=Yamaha_Playback_Station    visibility=[Yamaha_Input=="TUNER", Yamaha_Input=="NET RADIO"]
Text        item=Yamaha_Playback_Artist
Text        item=Yamaha_Playback_Album
Text        item=Yamaha_Playback_Song
Image       item=Yamaha_Playback_Song_Image visibility=[Yamaha_Input=="Spotify", Yamaha_Input=="NET RADIO", Yamaha_Input=="Bluetooth"]

Note the visiblility rules - you may need to adjust to your particular AVR model supported inputs and features.

DAB Tuner (dual band)


Number      Yamaha_Preset               "Preset [%d]"               <video>              { channel="yamahareceiver:zone:96a40ba9:Main_Zone:playback_channels#preset"}
String      Yamaha_Tuner_Band           "Band [%s]"                 <video>              { channel="yamahareceiver:zone:96a40ba9:Main_Zone:playback_channels#tuner_band" }
String      Yamaha_Input_Ex

The synthetic Yamaha_Input_Ex will be calculated by a rule (see below) and will drive sitemap visibility (see below).


rule "Yamaha_Input_Ex"
	Item Yamaha_Input changed or
	Item Yamaha_Tuner_Band changed	
	var String input = "" + Yamaha_Input.state
	if (Yamaha_Input.state == "TUNER" && Yamaha_Tuner_Band.state !== NULL) {
		input = input + "_" + Yamaha_Tuner_Band.state

When the input is TUNER the Yamaha_Input_Ex item will have a value of either TUNER_FM or TUNER_DAB depending on the chosen tuner band, otherwise it will be the same as input (Yamaha_Input).


Selection   item=Yamaha_Tuner_Band    mappings=[FM="FM",DAB="DAB+"]          visibility=[Yamaha_Input=="TUNER"]
Selection   item=Yamaha_Preset        mappings=[2="Radio Krakow",3="PR Trojka",5="RadioZet",8="Radio Chillizet",12="RMF Classic",13="RMF MAXXX"]     visibility=[Yamaha_Input_Ex=="TUNER_FM"]
Selection   item=Yamaha_Preset        mappings=[1="FM-1",2="FM-2",3="FM-3"]  visibility=[Yamaha_Input_Ex=="TUNER_DAB"]

Notice how we have two preset mappings that each is meant for FM and DAB+ bands respectively. This enables to have different channel names per band.

Debugging and troubleshooting

Enabling detailed logging may help troubleshoot your configuration (or trace bugs in the binding itself).

Add the following lines to the logger configuration file (userdata\etc\org.ops4j.pax.logging.cfg):

log4j2.logger.yamaha.name = org.openhab.binding.yamahareceiver
log4j2.logger.yamaha.level = TRACE

Depending on the desired details choose from levels: TRACE, DEBUG, INFO.

The openhab.log will contain internal workings of the binding:

2017-10-08 12:11:36.848 [TRACE] [al.protocol.xml.DeviceInformationXML] - Found feature Main_Zone
2017-10-08 12:11:36.853 [TRACE] [al.protocol.xml.DeviceInformationXML] - Adding zone: Main_Zone
2017-10-08 12:11:36.857 [TRACE] [al.protocol.xml.DeviceInformationXML] - Found feature Zone_2
2017-10-08 12:11:36.862 [TRACE] [al.protocol.xml.DeviceInformationXML] - Adding zone: Zone_2
2017-10-08 12:11:36.867 [TRACE] [al.protocol.xml.DeviceInformationXML] - Found feature DAB
2017-10-08 12:11:36.873 [TRACE] [al.protocol.xml.DeviceInformationXML] - Found feature Spotify
2017-10-08 12:11:36.974 [TRACE] [internal.protocol.xml.ZoneControlXML] - Zone Main_Zone state - power: true, input: AUDIO1, mute: false, surroundProgram: 5ch Stereo, volume: 45.652172

Model specific behavior

Input values

Certain AVR models in the XML protocol require different values for the input (i.e. HDMI1 vs HDMI_1). On top of that some AVR models during status updates report different value than sent in the command (i.e. return HDMI_1 for HDMI1 command).

To account for all variations a Yamaha thing setting got introduced: Input mapping. This allows to map the input value reported by the AVR after status update to the desired canonical value.

Use the PaperUI to customize the setting for your particular AVR: PaperUI > Configuration > Things > Edit > Yamaha Receiver XXX > Input mapping. For example, if your AVR returns HDMI_1 for command HDMI1 you can create such mapping list:


If you unsure what mapping to apply, enable trace logging (see section earlier) and you should see what is going on:

2017-12-28 20:43:40.933 [TRACE] [rnal.protocol.xml.XMLProtocolService] - Zone Main_Zone - inputs: InputDto{param='Spotify', writable=true}, InputDto{param='JUKE', writable=true}, InputDto{param='AirPlay', writable=true}, InputDto{param='MusicCast Link', writable=true}, InputDto{param='SERVER', writable=true}, InputDto{param='NET RADIO', writable=true}, InputDto{param='Bluetooth', writable=true}, InputDto{param='USB', writable=true}, InputDto{param='iPod (USB)', writable=false}, InputDto{param='TUNER', writable=true}, InputDto{param='HDMI1', writable=true}, InputDto{param='HDMI2', writable=true}, InputDto{param='HDMI3', writable=true}, InputDto{param='HDMI4', writable=true}, InputDto{param='HDMI5', writable=true}, InputDto{param='HDMI6', writable=true}, InputDto{param='AV1', writable=true}, InputDto{param='AV2', writable=true}, InputDto{param='AV3', writable=true}, InputDto{param='AUDIO1', writable=true}, InputDto{param='AUDIO2', writable=true}, InputDto{param='AUDIO3', writable=true}, InputDto{param='AUX', writable=true}
2017-12-28 20:43:40.935 [TRACE] [ernal.protocol.xml.InputConverterXML] - Converting from state name Spotify to Spotify - as per no conversion rule
2017-12-28 20:43:40.937 [TRACE] [ernal.protocol.xml.InputConverterXML] - Converting from state name JUKE to JUKE - as per legacy mapping
2017-12-28 20:43:40.939 [TRACE] [ernal.protocol.xml.InputConverterXML] - Converting from state name AirPlay to AIRPLAY - as per legacy mapping
2017-12-28 20:43:40.941 [TRACE] [ernal.protocol.xml.InputConverterXML] - Converting from state name MusicCast Link to MUSICCAST_LINK - as per legacy mapping
2017-12-28 20:43:40.943 [TRACE] [ernal.protocol.xml.InputConverterXML] - Converting from state name SERVER to SERVER - as per legacy mapping
2017-12-28 20:43:40.944 [TRACE] [ernal.protocol.xml.InputConverterXML] - Converting from state name NET RADIO to NET RADIO - as per no conversion rule
2017-12-28 20:43:40.946 [TRACE] [ernal.protocol.xml.InputConverterXML] - Converting from state name Bluetooth to Bluetooth - as per no conversion rule
2017-12-28 20:43:40.950 [TRACE] [ernal.protocol.xml.InputConverterXML] - Converting from state name Spotify to Spotify - as per no conversion rule
2017-12-28 20:43:40.951 [TRACE] [ernal.protocol.xml.InputConverterXML] - Converting from state name USB to USB - as per legacy mapping
2017-12-28 20:43:40.953 [TRACE] [ernal.protocol.xml.InputConverterXML] - Converting from state name TUNER to TUNER - as per legacy mapping
2017-12-28 20:43:40.953 [TRACE] [internal.protocol.xml.ZoneControlXML] - Zone Main_Zone state - power: true, input: Spotify, mute: false, surroundProgram: 5ch Stereo, volume: 35.869564
2017-12-28 20:43:40.954 [TRACE] [ernal.protocol.xml.InputConverterXML] - Converting from state name HDMI1 to HDMI1 - as per user defined mapping
2017-12-28 20:43:40.956 [TRACE] [ernal.protocol.xml.InputConverterXML] - Converting from state name HDMI2 to HDMI2 - as per user defined mapping
2017-12-28 20:43:40.958 [TRACE] [ernal.protocol.xml.InputConverterXML] - Converting from state name HDMI3 to HDMI3 - as per user defined mapping
2017-12-28 20:43:40.960 [TRACE] [ernal.protocol.xml.InputConverterXML] - Converting from state name HDMI4 to HDMI4 - as per user defined mapping
2017-12-28 20:43:40.962 [TRACE] [ernal.protocol.xml.InputConverterXML] - Converting from state name HDMI5 to HDMI5 - as per user defined mapping
2017-12-28 20:43:40.964 [TRACE] [ernal.protocol.xml.InputConverterXML] - Converting from state name HDMI6 to HDMI6 - as per user defined mapping
2017-12-28 20:43:40.965 [TRACE] [ernal.protocol.xml.InputConverterXML] - Converting from state name AV1 to AV1 - as per legacy mapping
2017-12-28 20:43:40.967 [TRACE] [ernal.protocol.xml.InputConverterXML] - Converting from state name AV2 to AV2 - as per legacy mapping
2017-12-28 20:43:40.975 [TRACE] [ernal.protocol.xml.InputConverterXML] - Converting from state name AV3 to AV3 - as per legacy mapping
2017-12-28 20:43:40.977 [TRACE] [ernal.protocol.xml.InputConverterXML] - Converting from state name AUDIO1 to AUDIO1 - as per no conversion rule
2017-12-28 20:43:40.979 [TRACE] [ernal.protocol.xml.InputConverterXML] - Converting from state name AUDIO2 to AUDIO2 - as per no conversion rule
2017-12-28 20:43:40.981 [TRACE] [ernal.protocol.xml.InputConverterXML] - Converting from state name AUDIO3 to AUDIO3 - as per no conversion rule
2017-12-28 20:43:40.983 [TRACE] [ernal.protocol.xml.InputConverterXML] - Converting from state name AUX to AUX - as per legacy mapping
2017-12-28 20:43:40.986 [TRACE] [.protocol.xml.ZoneAvailableInputsXML] - Zone Main_Zone - available inputs: AIRPLAY, AUDIO1, AUDIO2, AUDIO3, AUX, AV1, AV2, AV3, Bluetooth, HDMI1, HDMI2, HDMI3, HDMI4, HDMI5, HDMI6, JUKE, MUSICCAST_LINK, NET RADIO, SERVER, Spotify, TUNER, USB

Note: User defined mappings have as per user defined mapping and the rest comes is the existing addon mapping logic.

After switching to HDMI1 you should see this:

2017-12-28 21:08:51.683 [TRACE] [ernal.protocol.xml.InputConverterXML] - Converting from HDMI1 to command name HDMI1
2017-12-28 21:08:51.820 [TRACE] [ernal.protocol.xml.InputConverterXML] - Converting from state name HDMI1 to HDMI1 - as per user defined mapping
2017-12-28 21:08:51.821 [TRACE] [internal.protocol.xml.ZoneControlXML] - Zone Main_Zone state - power: true, input: HDMI1, mute: false, surroundProgram: 5ch Stereo, volume: 35.869564
2017-12-28 21:08:51.826 [DEBUG] [eiver.handler.YamahaZoneThingHandler] - Input changed to HDMI1

Zone_B support as Zone_2 (HTR-4069, RX-V583)

The Yamaha HTR-4069 handles Zone_2 in a different way from the other models. Specifically only selected functionality like power, mute and volume can be controlled. Also internally the Zone_2 is emulated via Zone_B XML elements available on Main_Zone.

Special handling has been added to emulate Zone_2 via the Zone_B feature.