Устранение неполадок

Сначала посмотрите operator guidance, а потом уже SSH

Прежде чем идти в shell и логи, проверьте встроенные operator-facing поверхности:

• health/status в шапке и переключатель checklist
• onboarding checklist для пропущенных шагов настройки
• recovery guidance для actionable runtime-проблем вроде disconnect, missing sink или released devices
• Diagnostics, если нужен более глубокий runtime view за этими подсказками

Эти поверхности опираются на те же данные, что и /api/diagnostics, /api/onboarding/assistant, /api/recovery/assistant и /api/operator/guidance.

После переподключения звук идёт только на одну колонку

После Bluetooth reconnect PulseAudio может увести активные потоки на sink по умолчанию. Bridge умеет исправлять это автоматически на следующем старте воспроизведения, но если проблема повторяется:

1. Проверьте логи на сообщения про sink routing.
2. Убедитесь, что нужный Bluetooth sink действительно существует.
3. Перезапустите воспроизведение после полного завершения reconnect.

Music Assistant не видит плеер

Проверьте:

1. В MA включён провайдер Sendspin.
2. SENDSPIN_SERVER указывает на правильный хост, либо разрешено auto discovery.
3. В логах bridge нет ошибок bind/startup.
4. Используемый sendspin port не занят другим процессом.

Если у устройства не задан явный listen_port, помните, что runtime использует BASE_LISTEN_PORT + индекс устройства. В multi-bridge setups проверьте, что эти диапазоны не пересекаются между контейнерами/экземплярами на одном хосте.

Путаница с WEB_PORT и HA Ingress

• В standalone-режиме используется прямой браузерный доступ через WEB_PORT (по умолчанию 8080).
• В HA addon mode ingress-порт назначается Home Assistant Supervisor динамически (в манифесте аддона стоит ingress_port: 0). Bridge читает реальный порт из /addons/self/info при старте. Старые «фиксированные» порты 8080 / 8081 / 8082 остались только как fallback на случай, если Supervisor API недоступен.
• WEB_PORT, заданный внутри аддона, игнорируется: параллельный прямой listener в текущей сборке не открывается. Открывайте UI через сайдбар Home Assistant или кнопку Open Web UI на странице аддона.

В standalone-режиме, если прямой порт не отвечает, проверьте, не занят ли он другим сервисом, и после изменения значения выполните Save & Restart.

Bluetooth недоступен на HA Supervised + Ubuntu

Если аддон не видит и не может управлять Bluetooth-адаптером на HA Supervised под Ubuntu 24.04+, host AppArmor блокирует raw HCI socket и D-Bus доступ.

Симптомы: адаптер показывается как выключенный, bluetoothctl внутри аддона не может ни перечислить, ни спарить устройства, в логах ошибки Bluetooth permissions.

Исправлено (v2.52.0+): обновите аддон — AppArmor профиль теперь включает правила dbus, и network raw,, нужные для строгих defaults Ubuntu 24.04.

Standalone Docker на Ubuntu: в docker-compose.yml уже есть security_opt: apparmor:unconfined, seccomp:unconfined. Если вы писали compose вручную — добавьте эти строки.

HAOS не затронута — минимальная политика безопасности не ограничивает Bluetooth.

Звук рассыпается и D-Bus подвисает на Raspberry Pi с USB BT-донглом

Симптомы. На Raspberry Pi 4 / 5 с внешним USB Bluetooth-донглом (например, ASUS USB-BT500, TP-Link UB500) воспроизведение стартует чисто, но через несколько минут начинает деградировать:

• появляется заикание или провалы звука на одной или нескольких колонках;
• btop и другие инструменты, обходящие системный D-Bus, застывают на несколько секунд;
• iwconfig wlan0 показывает быстрый рост счётчика Tx excessive retries (часто на тысячи единиц).

Вероятная причина. Сосуществование на 2.4 GHz между встроенным WiFi-адаптером Pi (BCM43455 на Pi 4 / Pi 5) и USB BT-донглом. Оба радио используют ISM-диапазон 2.4 GHz; когда WiFi-трафик и BT ACL-пакеты конкурируют за эфир, BT-контроллер начинает retransmissions, BlueZ блокируется на загруженном контроллере, и любой клиент, делающий синхронные D-Bus вызовы (демон моста, btop, bluetoothctl), застывает вместе с ним.

Быстрая диагностика. Смотрите счётчик retries во время воспроизведения:

iwconfig wlan0 | grep -i "Tx excessive retries"

Если число растёт во время playback — подозрение на coexistence обоснованно.

Фикс, подтверждённый отчётом сообщества (#212). Перевести Pi на 5 GHz WiFi-сеть, если роутер это поддерживает:

nmcli connection modify "<имя-вашей-wifi>" wifi.band a
nmcli connection up "<имя-вашей-wifi>"

После переключения Tx excessive retries должны оставаться на 0 во время воспроизведения, а заикание звука и зависания btop — исчезнуть.

Если перевести хост на 5 GHz нельзя, рассмотрите подключение Pi через Ethernet, изменение физического размещения BT-донгла или примите, что воспроизведение на одну колонку — практический потолок для Pi на 2.4 GHz.

Bluetooth не подключается

1. Устройство действительно спарено на уровне хоста.
2. D-Bus доступен bridge.
3. Адаптер включён.
4. Попробуйте Re-pair из dashboard.

Если используется несколько адаптеров, отдельно проверьте, что в строке устройства указан правильный adapter ID или MAC.

Если bridge много раз подряд не может переподключить одну и ту же колонку, настроенный Auto-disable threshold может сохранить устройство как disabled. После устранения проблемы pairing/signal/adapter включите его снова в Configuration → Devices.

”No sink” или тишина при воспроизведении

No sink означает, что Bluetooth подключён, но аудио-sink ещё не привязался.

Причина	Что попробовать
Аудиосервер не работает	Проверить pactl info
Sink ещё не успел подняться	Подождать несколько секунд после BT connect
Неправильное соответствие user/socket	Проверить exposure аудио-сокета
Неверный профиль	Убедиться, что есть профиль A2DP sink

На медленных системах помогает увеличение PulseAudio latency (ms) и включение Prefer SBC codec.

Колонка спаривается, но аудио-sink не появляется (регрессия BlueZ 5.86)

Симптом. Колонка спаривается, bluetoothctl показывает Connected: yes, но в pactl list cards short нет bluez_card.<MAC> для неё, а в pactl list sinks short отсутствует bluez_sink.<MAC>.a2dp_sink / bluez_output.<MAC>.*. Через 30–40 секунд колонка сама разрывает связь, и последующие попытки reconnect не работают до выключения и включения питания колонки.

Корневая причина. Upstream-регрессия BlueZ, трекается в bluez/bluez#1922 (см. также bluez/bluez#1898): для dual-role устройств (колонки с A2DP source или HFP/HSP — двухсторонние спикерфоны, TWS-колонки, smart-колонки) BlueZ 5.86 не регистрирует A2DP Sink профиль во время Connect(). Bridge видит линк на D-Bus, но sink в PulseAudio не создаётся, потому что с её точки зрения ни одна карта с A2DP-sink не появилась.

Исправлено в upstream коммитом 066a164 (“a2dp: connect source profile after sink”), вошедшим в bluez 5.87 и back-portированным в 5.86-4.1 в части дистрибутивов.

Что bridge делает автоматически. С v2.60.2 bridge применяет два workaround’а на каждом connect:

1. После успешного generic Connect() вызывается явный Device1.ConnectProfile(A2DP_SINK_UUID), заставляя BlueZ предложить sink-профиль. На здоровом стеке это no-op.
2. Если после retry’ев поиска sink он так и не появился, выполняется одноразовый “танец” disconnect → пауза 2 с → reconnect, которого часто достаточно, чтобы второй Connect() зарегистрировал профиль корректно.

Если эти fallback’и не помогли — вы на подтверждённом 5.86-регрессированном стеке, нужен host-level фикс.

Host-level workaround: отключить HFP/HSP в BlueZ. Без HFP/HSP у BlueZ не остаётся выбора, кроме как согласовать A2DP. Отредактируйте на хосте /etc/bluetooth/main.conf:

[General]
DisablePlugins=hfp,hsp

Затем перезапустите BlueZ (systemctl restart bluetooth на обычном хосте). На HAOS этот файл лежит внутри host-слоя и не редактируется из аддона — нужна host-level SSH сессия, и изменения не переживут HAOS update.

Host-level workaround: сменить Bluetooth-адаптер. Некоторые встроенные контроллеры (особенно Intel AX200/AX210) страдают от регрессии 5.86 сильнее, чем простые USB-донглы. Перенос затронутой колонки на CSR8510 или Realtek-based USB-донгл (прокинутый в HAOS VM / LXC) часто обходит проблемный код. Стоит попробовать, если у вас нет возможности быстро обновить host BlueZ.

Правильный фикс. Обновите host OS до релиза с bluez ≥ 5.87 или патченым 5.86-4.1. На HAOS это происходит автоматически вместе с Supervisor/host update. После этого никаких bridge-side интервенций не нужно.

Reconnect-loop на Sony WH-1000XM4 / других A2DP-наушниках (AVDTP collision на старом BlueZ)

Симптом. После disconnect’а — выключения питания, рестарта контейнера или простого выхода из зоны действия — колонка/наушники впадают в шторм connect/disconnect: пейринг проходит, бридж пишет Using cached sink, Music Assistant начинает стримить, и через 1–2 секунды связь рвётся. Цикл повторяется, пока не исчерпан BT_MAX_RECONNECT_FAILS. Ручной Reclaim из веб-UI бриджа всегда срабатывает с первого раза — падает только автоматический reconnect. В журнале bluetoothd на каждой попытке видны AVDTP-collision сообщения: cancel_request() Start: Operation canceled, SEP in bad state for suspend, Transaction label doesn't match.

Корневая причина. Гонка в anti-pop sink-mute бриджа, исправлено в v2.70.0: если кешированное имя sink’а после Bluetooth reconnect ещё валидно, бридж шёл по fast-path и пропускал 3-секундную стабилизационную задержку A2DP. На некоторых peer’ах — в первую очередь Sony WH-1000XM4 — anti-pop mute гонялся с AVDTP-Suspend от самой колонки, давая описанный выше кластер ошибок. Трекалось в #269.

Требование к версии BlueZ. Фикс v2.70.0 решает, можно ли пропустить стабилизационную задержку, по чтению org.bluez.MediaTransport1.State. Это опирается на то, что BlueZ возвращает состояние transport’а корректно: idle — только когда transport действительно безопасно проходить по fast-path, а не пока он ещё настраивается. BlueZ 5.66 (Raspberry Pi OS Bookworm) возвращает idle преждевременно во время AVDTP setup’а, поэтому бридж всё равно идёт по fast-path и collision повторяется. BlueZ ≥ 5.79 (Debian Trixie / Ubuntu 24.10+ / свежий Raspberry Pi OS 12+ / HAOS 17.1+) сообщает состояние корректно, и фикс срабатывает как задумано.

Что делать.

• Рекомендуется: обновить host OS до версии с BlueZ ≥ 5.79. На Raspberry Pi — переезд с Bookworm на Trixie; на HAOS подтянется через Supervisor/host-обновление.
• Workaround на старом BlueZ: если апгрейд OS сейчас невозможен, нажатие Reclaim в веб-UI бриджа после ручного disconnect’а — надёжный путь восстановления. Пользователь естественным образом подождёт несколько секунд после клика, и AVDTP-transport успеет стабилизироваться до того, как бридж начнёт стримить.

Подтверждено community-тестированием: WH-1000XM4 на RPi 4 + Trixie (BlueZ 5.82, PipeWire 1.4.2) + bridge v2.70.1 reconnect’ятся стабильно с первой попытки; те же наушники на Bookworm (BlueZ 5.66) с v2.70.1 продолжают ловить collision-паттерн.

Scan видит BLE-устройства, но не видит аудио-колонок (конфликт с Bluetooth-интеграцией HA)

Симптом. На системе с одним адаптером — обычно Raspberry Pi 4 / 5 с встроенным BT-контроллером и аддоном, работающим против него же — Scan nearby находит BLE-устройства (контроллеры полива, сенсоры, маячки), но классические A2DP-колонки не появляются вообще. При этом та же колонка нормально спаривается с телефона или с другой ОС на этом же железе.

Причина. Встроенная Bluetooth-интеграция Home Assistant держит адаптер занятым BLE passive scan’ом. Когда тот же hci0 шарится с аддоном, BLE-объявления продолжают приходить через ядро — поэтому BLE-устройства в результатах сканирования аддона видны, — но BR/EDR inquiry, который нужен для обнаружения классических колонок, не может корректно отработать на контроллере, уже занятом в LE-scan-режиме.

Решение. Освободить адаптер у Home Assistant до пайринга колонок из бриджа:

1. Settings → Devices & services → Bluetooth → ⋮ → Disable (или Delete, если интеграция вообще не нужна).
2. В UI бриджа: Configuration → Bluetooth → Scan nearby.
3. Запарить колонку как обычно.

Если HA Bluetooth-интеграция нужна для других устройств (ESPHome BLE-прокси, room-presence сенсоры, счётчики), оптимальная схема — два адаптера: встроенный оставить за HA, а к бриджу подключить USB BT-донгл. Подробности — Bluetooth adapters.

Конфликт чаще всего проявляется на Raspberry Pi, потому что там встроенный BCM-контроллер обычно единственный — разнесение задач по разным адаптерам полностью устраняет проблему.

Scan ничего не находит

Если Scan не возвращает результатов:

1. Переведите колонку в pairing mode до запуска сканирования.
2. Дождитесь завершения полного фонового сканирования.
3. Посмотрите текст ошибки прямо в discovery card.
4. Повторяйте попытку только после окончания cooldown.
5. Используйте Already paired, если хост уже знает устройство.

Не проходит token-flow Music Assistant

Если Get token automatically или Get token не завершается успешно:

1. Убедитесь, что URL MA указан правильно и доступен.
2. Если bridge уже подключён, сначала нажмите Reconfigure в Configuration → Music Assistant, чтобы снова открыть auth-секцию.
3. В HA Ingress обновите страницу из Home Assistant, чтобы у браузера был актуальный HA session/token.
4. Помните, что Get token automatically доступен только в addon/Ingress flow. Вне него используйте прямой MA login или вставьте token вручную.
5. Разрешите popup-окна для страницы bridge — fallback HA auth flow открывает popup, когда silent auth недостаточно.
6. Если MA работает поверх HA и встроенный MA-login отклоняет credentials, повторите попытку и завершите шаг HA MFA, а не ожидайте чистый MA-password flow.
7. Помните, что bridge сохраняет long-lived MA token, но не сохраняет введённый пароль.

Empty state ведёт не туда

После редизайна empty-state действия должны работать так:

• Scan for devices → Configuration → Devices → Discovery & import.
• Add adapter → Configuration → Bluetooth с пустой строкой адаптера.

Если этого не происходит, проверьте, что веб-интерфейс обновлён до актуального релиза.

Проблемы аутентификации

Ошибка на MFA / TOTP шаге

Когда Home Assistant требует MFA, login page переключается на отдельный шаг с кодом. Если flow ломается:

1. Начните со свежей страницы входа, а не со старой закладки на MFA-step.
2. Убедитесь, что этот же пользователь может войти в Home Assistant вне bridge.
3. Проверьте, не слишком ли маленький Session timeout и не была ли страница слишком долго простаивающей между вводом пароля и TOTP.

Сработала блокировка локального входа

По умолчанию 5 неудачных попыток за 1 минуту дают 5 минут блокировки. Эти значения меняются в Configuration → Security.

Веб-интерфейс без auth

Если сверху виден жёлтый warning-banner, локальная auth-защита отключена. Используйте ссылку в баннере для быстрого перехода в Configuration → Security.

Для standalone-login важны и restart-applied параметры вроде включения auth и session timeout. Если вы меняли эти значения, используйте Save & Restart прежде чем делать вывод, что настройка не подхватилась.

Аппаратные кнопки колонки попадают не в ту колонку

Симптом. Когда на одном Bluetooth-адаптере подключено две или больше колонок, нажатие Next, Previous, Play или Pause на колонке A фактически переключает / запускает / ставит на паузу музыку на колонке B.

Причина. BlueZ пересылает каждое AVRCP-событие первому зарегистрированному media-плееру, не сообщая, на какой именно ACL-связи пришло нажатие. С точки зрения BlueZ есть только один MPRIS-плеер, поэтому все аппаратные кнопки сворачиваются на последнюю активную колонку.

Что делает bridge автоматически. Bridge запускает HCI source monitor (services/hci_avrcp_monitor.py), который открывает raw-сокет HCI_CHANNEL_MONITOR, парсит проходящие через контроллер AVRCP passthrough opcodes и сопоставляет каждое нажатие с фактическим ACL connection handle (а значит, MAC конкретной колонки). Диспетчер пересылает команду только в MPRIS-плеер этой колонки.

Когда срабатывает fallback. HCI monitor требует CAP_NET_RAW внутри контейнера. Если открыть monitor-сокет не удаётся — типично для урезанного Docker-окружения или жёстко confined LXC — bridge пишет warning при старте и направляет каждое AVRCP-нажатие в последнюю активную колонку этого адаптера. Для one-speaker-per-adapter этого достаточно, но при двух колонках на одном адаптере возникает описанный выше симптом.

Как проверить.

1. Откройте Diagnostics → Advanced → Subprocess and runtime info (или выполните docker logs sendspin-client | grep -i hci_avrcp).
2. Ищите hci_avrcp_monitor: started on hciN (норма) против hci_avrcp_monitor: missing CAP_NET_RAW, falling back to default-client routing (деградировано).
3. Если monitor не стартовал, добавьте недостающие capabilities:
   • Docker: убедитесь, что в docker-compose.yml присутствует cap_add: [NET_ADMIN, NET_RAW, SYS_ADMIN].
   • HA addon: addon-образ запрашивает эти caps по умолчанию; проверьте в Supervisor → Addons → Sendspin BT Bridge → Info.
   • LXC: убедитесь, что в конфиге контейнера не задано lxc.cap.drop: cap_net_raw.

Когда это не нужно. Multi-adapter раскладка (каждая колонка на своём hciN) полностью убирает причину неоднозначности — BlueZ видит по одной колонке на адаптер, и default-client fallback оказывается корректным. Маршрутизация аппаратных кнопок становится неоднозначной только когда две или больше колонок делят один адаптер.

Mute или volume не совпадают с Music Assistant

Проверьте вкладку Music Assistant:

• Route volume through MA синхронизирует bridge с ползунками MA.
• Route mute through MA синхронизирует состояние mute с MA.

Если эти тумблеры выключены, bridge использует direct PulseAudio control для более быстрого локального отклика, но MA может показывать другое состояние.

Save vs Save & Restart vs Cancel

Если изменение конфигурации ведёт себя непредсказуемо:

• Используйте Save для простого сохранения.
• Используйте Save & Restart, если runtime-компоненты должны переподключиться или переинициализироваться.
• Используйте Cancel, чтобы выбросить несохранённые изменения и восстановить последние сохранённые значения формы.

Прогресс перезапуска отображается в шапке и показывает шаги сохранения, остановки, reconnect и восстановления связи с Music Assistant.

Diagnostics и bug reports

Раздел Diagnostics стоит открыть, если нужно быстро понять:

• видит ли bridge адаптеры,
• правильно ли назначены sinks,
• жив ли Music Assistant,
• что происходит с каждым устройством,
• в каком состоянии subprocess и runtime окружение.

Кнопки Download diagnostics и Submit bug report помогают собрать актуальные данные перед созданием GitHub issue.

Bug-report dialog теперь заранее подставляет редактируемое suggested description из замаскированной диагностики. Перед отправкой дополните его точными шагами воспроизведения и ожидаемым/фактическим поведением.

В Home Assistant Supervisor нет интернета или не работают update checks на HAOS в Proxmox

В текущем HAOS-on-Proxmox окружении причина оказалась связана с MTU/path behavior, а не с настройкой TLS версии Supervisor. Установка MTU 1400 на сетевом интерфейсе VM восстановила Supervisor internet checks.

Если Supervisor пишет, что интернета нет, хотя в остальном сеть выглядит рабочей, сначала проверьте MTU VM/сети, а не TLS-параметры.

Нет звука на armv7l

Если Bluetooth подключается, UI показывает playback, но звука нет, обновитесь до релиза с PyAV compatibility patch. Старые сборки PyAV на armv7l не имеют layout-атрибута, который ожидает FLAC decoder.