GEM driver for Yamaha AV receivers that speak the YNCA (Yamaha Network Control Architecture) TCP protocol on port 50000. Covers the RX-V, RX-A (Aventage), and many CX / NX preamp models from roughly 2011 through 2019. Supports up to four named zones (MAIN, ZONE2, ZONE3, ZONE4) with per-zone power, volume, mute, and input.
For newer Yamaha receivers (RX-V6A, RX-A2A, RX-V4A and later) that ship MusicCast only and no longer expose YNCA, use the yamaha_musiccast driver instead.
Prerequisites
- A Yamaha receiver with YNCA-compatible firmware. Most RX-V / Aventage models from model year 2011 onwards expose YNCA on port 50000. If a
telnet <receiver_ip> 50000 connects and stays open, you're good.
- Network Standby enabled. Setup → Network → Network Standby = On. Without this, the receiver's Ethernet stack drops the moment it goes into standby and the driver loses control after the first
power_off.
- A static IP or DHCP reservation for the receiver. YNCA does not handle IP changes gracefully.
- No competing TCP session. The receiver accepts only one TCP client at a time — close the Yamaha AV Controller / MusicCast Controller apps on phones and tablets before troubleshooting.
Setup steps
Open Devices
- Enable Network Standby on the receiver. Menu → Setup → Network → Network Standby → On.
- Pin the receiver's IP. Either set a static IP from the receiver menu or create a DHCP reservation on the router.
- Add the device in GEM. Go to System → Devices → Add Device, pick driver
yamaha_ynca, and enter the receiver IP. Leave Port on 50000.
- Verify protocol. Open the device's Script Console and run:
await gem.command({device_id: <device_id>, command: 'get_status', args: {address: 'MAIN'}})
- Wire up zones. This driver does not create zones automatically — add one GEM zone per receiver zone you want to control. Set the zone's Subsystem to AV (the AV subsystem ships with every install and is pre-selected for this driver) and set Address to the literal subunit name:
MAIN, ZONE2, ZONE3, or ZONE4. State only flows to a zone once it is bound to this device and carries one of those addresses — a zone with a blank address receives no receiver state. Most receivers physically only have MAIN + ZONE2; consult the model spec before configuring ZONE3 / ZONE4.
- Optional — expose inputs as AV sources. Create AV Sources keyed to the receiver's input codes (
HDMI1, NET RADIO, etc.) so the UI can switch inputs by name, and bind an AV Zone to the receiver zone if you want on-screen volume and source selection.
Attributes
Device — required
| Name | Type | Description |
|---|
ip | string | LAN IP or hostname of the receiver. |
Device — optional
| Name | Type | Default | Description |
|---|
port | int | 50000 | YNCA TCP port. Almost always the factory default. |
status_interval | int (ms) | 30000 | How often to re-query PWR / VOL / MUTE / INP on every configured zone (MAIN is always polled, even if no MAIN zone exists). YNCA also pushes unsolicited updates on user changes, so this is a backstop. A value that is not a positive number of milliseconds within the timer range falls back to 30000, and a new round never starts while the previous one is still running. |
command_throttle | int (ms) | 100 | Minimum gap between outbound commands. Older firmware drops commands stacked tighter than ~100 ms. A non-numeric or out-of-range value falls back to 100. |
min_volume_db | float | -80.5 | Lower bound used when mapping GEM 0-100 volume to YNCA dB. |
max_volume_db | float | +16.5 | Upper bound used when mapping GEM 0-100 volume to YNCA dB. Lower this on shared installs where guests can run a control UI. |
Zone — address
| Field | Description |
|---|
address | Subunit name as a literal string. Accepts MAIN, ZONE2, ZONE3, ZONE4 (with or without underscore / space). Plain integers 1-4 are also accepted as aliases. |
Commands
| Name | Args | Description |
|---|
on | address | Power on (PWR=On). |
off | address | Power off / standby (PWR=Standby). |
power_on / power_off | address | Aliases. |
set_volume | address, level | Set volume on the GEM 0-100 scale; linearly mapped to YNCA dB. |
set_volume_db | address, db | Set absolute YNCA dB (-80.5 to +16.5, 0.5 dB steps). |
volume_up / volume_down | address | Step by 0.5 dB. |
mute_on / mute_off | address | Mute / unmute. |
mute_toggle | address | Toggle. YNCA has no native toggle, so the driver sends MUTE=On / MUTE=Off based on the last mute state the receiver reported for that subunit (an attenuating mute such as Att -20 dB counts as muted). Before the receiver has reported one, it falls back to the zone's mute_state; the zone is found by its subunit, so an address of 2, zone2 or blank still toggles the right zone. |
set_input | address, input | Switch input by YNCA input code (HDMI1, NET RADIO, SPOTIFY, etc.). The command runner and macro editor offer the common codes as a dropdown. Line breaks in the value are stripped. |
get_status | address | Query PWR / VOL / MUTE / INP for one zone. Returns an error if the queries could not be sent (for example, the receiver is not connected). |
get_zones | — | Connectivity probe. Sends a power query to MAIN / ZONE2 / ZONE3 / ZONE4 in turn and returns all four as candidates — it does not filter to the zones the receiver physically has (absent subunits answer @UNDEFINED on the wire, which the driver ignores). Configure GEM zones only for the subunits your model actually supports. Returns an error instead of a list when the receiver is not connected. |
HDMI1–HDMI7, AV1–AV7, AUDIO1–AUDIO5, AUX, PHONO, TUNER, USB, SERVER, NET RADIO, SPOTIFY, AIRPLAY, BLUETOOTH, MUSIC CAST LINK. The exact list depends on the model — set_input to an unsupported code returns @RESTRICTED on the wire.
Zone state attributes
| Attribute | Values |
|---|
state | on / off (mapped from PWR=On / PWR=Standby) |
volume | 0-100, mapped from the YNCA dB report |
mute_state | on / off (Att -20 dB / Att -40 dB attenuating mute reads as on) |
input | YNCA input code as a string |
Known limitations
- One TCP client. The receiver allows only one YNCA session. If Yamaha's own app is open on a phone, the GEM driver is silently kicked.
- Volume mapping is linear in dB. YNCA's perceptual response is not linear — small changes near the top of the scale are loud, small changes near the bottom are subtle. Most installs prefer a lower
max_volume_db so that the GEM 0-100 slider reaches a comfortable max well before clipping.
- Power, volume, mute, and input only. DSP / surround modes (
SOUNDPRG, STRAIGHT, PUREDIRECT), tuner / NetRadio metadata (@TUN:FREQ=…, @NETRADIO:META=…), and HDMI control / video routing are not exposed as GEM commands or zone attributes, even though the YNCA protocol carries them.
Troubleshooting
- Connection refused on port 50000. Confirm Network Standby is enabled and that no other Yamaha controller app is connected. On newer-than-2020 receivers YNCA may simply not be exposed — switch to the
yamaha_musiccast driver.
- Commands send but state never updates.
response_terminator defaults to \r\n. If the receiver is wired through a serial-over-IP gateway that strips the LF, set response_terminator to \r on the device row.
@RESTRICTED on every command. Either the receiver is powered off and the addressed zone is asleep (PWR=On will wake it), or the input/value sent is not supported on the model. Check the receiver's "Network" menu in the OSD to confirm YNCA is enabled.@UNDEFINED after probing ZONE3 / ZONE4. Normal — the receiver responds @UNDEFINED to commands targeting subunits it doesn't have. Only configure zones for subunits the receiver physically supports.- Volume slider scale wrong. Check
min_volume_db / max_volume_db on the device. The driver maps 0-100 linearly into that range; if your install caps the receiver below +16.5 dB physically, lower max_volume_db so the slider tracks reality.
- Zones — create one zone per receiver subunit (address
MAIN / ZONE2 / …).
- Subsystems — receiver zones belong under the AV subsystem.
- AV Zones and AV Sources — expose the receiver in AV routing and switch inputs by name.
- Commands — test power / volume / mute / input from the command runner.
yamaha_musiccast — for newer MusicCast-only receivers that no longer expose YNCA.