Troubleshooting

Troubleshooting

Answers to common questions about the Neumann KH (SSC) integration. Source marks [measured], [code], [manual]: see the legend on Home.

The speaker shows as "unavailable"

Usually this is normal. In standby, a speaker does not answer SSC at all, so standby looks exactly like a speaker that is switched off. [measured] (KH 120 II and KH 750 DSP) According to the manuals, standby switches off the network interface. [manual] Details: Device Behaviour.

Situation	What happens	Source
Speaker goes to standby while the entry is running	All entities become unavailable. Polling continues every 30 s, and the speaker is picked up again on the first cycle that succeeds.	[code] [measured]
Log while the speaker is offline	One info line when it drops out and one when it is back. No error is logged.	[code]
Speaker already offline when Home Assistant starts	Setup does not finish. Home Assistant retries it with a growing gap (its own retry timing). It does not give up.	[code]
Speaker moved to a new address	After every failed setup, the integration searches the network (mDNS) for the speaker by its stored serial number and stores the new address if it finds it. Entries without a stored serial are skipped.	[code]
Speaker answers, but rejects every value	Entities become unavailable and an error is logged. Standby does not cause this.	[code]
All connection slots of the speaker are in use	With the integration connected, 3 more connections per speaker were accepted and the next one timed out at connect, without a refusal [measured]. If other clients (Neumann software such as MA 1, scripts) hold the slots, the integration's reconnect times out and its entities become unavailable, logged like standby [code]. Close the other clients.	[measured] [code]
A different speaker answers at the stored address	Setup fails and is retried (no data from that device is shown). The log shows the expected and the answering serial, both masked. Only for entries that store a serial.	[code]

If entities stay unavailable while the speaker is awake, check the address and interface (see below) and enable debug logging.

How do I find the speaker's address?

• Automatic search (recommended): go to Add Integration → Neumann KH (SSC) → Search network automatically. The integration searches mDNS for _ssc._tcp.local. and lists model, address and serial for each speaker it finds. [code]
• To search again, pick the "Search again" entry in the list. If no speaker was found, the form shows only a submit button, and submitting it searches again. [code]
• Speakers that are not set up yet can also show up by themselves under Settings → Devices & Services as discovered devices. [code]
• When a speaker announces both a global and a link-local address, the search picks the link-local one, because a global prefix can change when the provider reconnects. [code]
• mDNS and link-local addresses are limited to one network segment (layer 2) by design, so Home Assistant has to share it with the speakers. With Docker this means network_mode: host or direct layer-2 access to the speakers' segment. Background: Identity and Discovery.

Link-local address: why do I need an interface?

A link-local address (fe80::/10) only works together with a scope ID, which is the network interface. [code]

Setup path	Interface
Automatic search	The address already includes the scope (e.g. fe80::1%3). Nothing to enter. [code]
Manual entry	Pick it from the interface dropdown. The dropdown lists the host's adapters with their addresses. A custom value can be typed in. [code]
Global (non-link-local) IPv6	Choose "none". [code]

The integration adds %<interface> to an unscoped link-local address. An address that already contains % is used as it is. [code]

To change the address, interface or port later, use Settings → Devices & Services → [device] → ⋮ → Reconfigure. Entity IDs and history are kept. A new address where a speaker with a different serial answers is refused. [code]

Enabling debug logs

All modules log under custom_components.neumann_kh. [code] You can turn on debug logging in two ways:

• On the integration page, use Enable debug logging. This is Home Assistant's standard feature.
• In configuration.yaml:

logger:
  logs:
    custom_components.neumann_kh: debug

At debug level the integration logs, among other things:

• paths the speaker does not support (skipped)
• discarded stale or invalid response lines
• failed mDNS resolution
• whether a KH 750 keeps output level and mute in audio/out5 instead of audio/out (reported for firmware 1.2.x; not tested on hardware)

[code]

What do the logs mask?

Data	Normal log (info/warning/error)	Source
Speaker address	Masked: everything after the last :: is replaced by xx plus its last two characters; the part before :: and the %scope are kept (e.g. fe80::xx5f%eth0)	[code]
Serial number	Masked: only the last 3 characters are visible	[code]
Debug-level lines	Can contain the full address. Debug logging is off by default.	[code]
Backup / discovery JSON exports	Serial masked to the last 3 characters	[code]

The address is masked because a link-local address is derived from the device's MAC address. Before you share a log, check debug output for full addresses. [code]

"The speaker refuses changes from the network"

If the CONTROL / CONTROL MODE switch on the back is on LOCAL, the speaker refuses every change (401 authorisation needed) while readings keep updating [measured, both models]. Home Assistant then says the speaker refuses changes from the network and asks you to set the switch to NETWORK; a backup restore stops at that point and reports how many values it wrote. The diagnostic sensor Control mode shows the switch position. [code]

"The speaker rejected ..." messages

When a speaker refuses a change, the error message ("The speaker rejected this change ...") ends with the speaker's own error text [code]. Since 1.19.1 that text is read from the speaker's nested error format; earlier versions showed the raw error structure instead [code]. Texts seen on the tested models [measured]:

Text	Code	Typical cause	Source
address not found	404	The path does not exist on this model or firmware (e.g. audio/out/dimm)	[measured]
method not allowed	405	Write to a field that is read-only on the device, e.g. a field that follows a switch on the back (see Limits and Untested)	[measured]
not acceptable	406	Value of the wrong type, or out of range on some paths (e.g. ui/logo/brightness)	[measured]

A path the speaker does not have is skipped during polling and logged at debug level only [code].

"Run device discovery" takes long or the schema part is incomplete

The diagnostic button Run device discovery reads every known path and then walks the speaker's command tree via osc/schema and osc/limits, which both tested firmwares answer [measured]. The schema walk has a 30 s limit and keeps what it has read when the limit is hit [code]. Result: a JSON file in <config>/neumann_kh/ [code].

Version	Schema walk	Source
1.19.1 and later	Complete in a few seconds: 3.4 s on a KH 120 II, 7.4 s on a KH 750	[measured]
Before 1.19.1	Stopped at the 30 s limit after 50 paths: about three quarters of a KH 120 II's tree (64 paths), about a third of a KH 750's (143). Update the integration and run it again	[measured]

Entities "no longer provided" after an update

Home Assistant does not remove entities that the integration no longer creates. You have to delete them yourself.

Cause	Affected entities	Source
KH 750 EQ layout corrected (1.19.0)	The "EQ Crossover Output 1/2" switches and reset buttons. They read audio/out1/eq1/<leaf> and audio/out2/eq1/<leaf>, which answer 404 (firmware 2_1_2) – the crossover keeps its values one level deeper, under eq1/in1 and eq1/in2 – so these entities never had a value (see EQ).	[measured] [code]
Model corrected at setup (1.19.0 and later)	Model and firmware are read again at every setup. An entry that was created while the speaker did not report its model corrects itself, and entities of the model it assumed before become orphaned.	[code]

To delete: go to Settings → Devices & Services → [device] → Entities, select the entity marked as no longer provided, and delete it.

Backup and restore

Topic	Behaviour	Source
Create backup	Runs only when you press the button. Saves all known values except live measurements, including the full EQ. Also writes a JSON file to <config>/neumann_kh/.	[code]
Restore backup	Disabled by default. Needs two presses.	[code]
Two-step confirmation	The first press only arms it and shows a notification. A second press between 2 s and 30 s later carries it out. A press that comes too early or too late arms it again.	[code]
Refused restore	Nothing is written if no backup exists, if the backup is from another model, if it belongs to a different speaker (masked serial), or if it was taken while the speaker was on LOCAL (earlier versions could store such a backup).	[code]
Speaker on LOCAL	The restore stops at the first refused write and reports how many values it wrote.	[code]

Button entities cannot show a confirmation dialog in Home Assistant, which is why the second press is used. [code]

Factory reset

From Home Assistant: use the button Restore factory defaults (device/restore). It is disabled by default and uses the same two-press confirmation (second press 2 s to 30 s after the first). The button writes FACTORY_DEFAULTS to this path [code], which the speaker's own osc/limits lists as an option of this path (besides an empty string) [measured]. Triggering it was not tested on hardware.

On the speaker itself (switch sequence during boot, per Neumann's documentation; not tested on hardware with this integration). More detail on the KH 120 II and KH 750 DSP: Device Behaviour.

Model	Procedure	Source
KH 120 II / KH 150	While booting (logo red), toggle the CONTROL switch repeatedly until the logo is white for a few seconds.	[manual]
KH 750 DSP	While booting (power LED red), toggle the AUTO STANDBY switch repeatedly until the LED is green for a few seconds. It then flashes red while the defaults are applied and finally turns green.	[manual]
KH 80 DSP	While the logo is red during boot, toggle the SETTINGS switch repeatedly until shortly after the logo turns white.	[manual]

The "reset to flat" buttons for the EQ are not a factory reset. They set gain and boost of all bands in a container to 0 dB. Frequency, Q, type and on/off are left unchanged. [code] See Integration-Behaviour.

See also: Integration-Behaviour · Entities-and-Polling · Neumann KH SSC Reference