arc/docs/wifi-adb.md

ADB через Wi-Fi (TCP/IP)

ARC умеет работать с устройствами не только по USB-кабелю, но и по Wi-Fi (ADB-over-TCP). Включается автоматически, без участия пользователя: USB остаётся основным транспортом, Wi-Fi — горячий резерв, который подхватывается при отключении кабеля.

Поведение

1. Пользователь, как и раньше, подключает телефон по USB.
2. Фоновый DeviceScreener, обнаружив простаивающее USB-устройство без живого Wi-Fi-эндпоинта, автоматически:
   • читает IP телефона в сети Wi-Fi (wlan0) и его MAC;
   • переводит adbd в TCP-режим (adb tcpip <port>);
   • подключается по сети (adb connect ip:port);
   • сохраняет эндпоинт в settings (ключ wifi_endpoints, JSON { android_id: { "endpoint": "ip:port", "mac": "aa:bb:.." } }; старый формат — значение-строка "ip:port" — читается прозрачно).
3. После этого кабель можно отключить — устройство остаётся онлайн (статус привязан к android_id, а не к ADB-serial; меняется только adbSerial на ip:port).
4. При старте ARC и периодически воркер переподключает сохранённые эндпоинты (adb connect), так что устройство, у которого кабель уже отключён, само появляется онлайн.
5. Если беспроводной эндпоинт «завис», воркер чинит его пересозданием TCP (adb disconnect → adb connect): голый повторный connect вернул бы already connected и ничего бы не починил. disconnect ещё и расклинивает это «залипшее» состояние — после него последующие connect (в т.ч. из периодического reconnect) становятся реальными попытками. Срабатывает по двум сигналам:
   • эндпоинт виден в adb devices со статусом offline;
   • устройство ушло в debounced-offline (30 c не отвечает), хотя adb devices всё ещё держит его как device — частый реальный случай «полумёртвого» соединения при слабом Wi-Fi / уходе телефона в doze, когда команды виснут, а статус не меняется (принудительный disconnect→connect, «kick», на переходе в debounced-offline). Починка пропускается для устройств с активной/ожидающей задачей (см. инварианты).
6. Если connect по сохранённому IP не удался (адрес сменился по DHCP), воркер ищет устройство в сети по сохранённому MAC (ARP-таблица ОС, при включённой опции — с прогревом через ping-скан /24) и переподключается на новый IP, обновляя эндпоинт.

Инварианты

• USB приоритетнее. Если один android_id виден одновременно по USB-serial и по ip:port, каноническим adbSerial (по нему ходят банк-скрипты) выбирается USB. Wi-Fi-эндпоинт остаётся резервом и используется только когда USB пропадёт.
• Разрывающие операции — только на простаивающих устройствах. adb tcpip перезапускает adbd, а принудительный disconnect→connect (kick) рвёт текущее соединение — поэтому ни bootstrap, ни kick не выполняются, если на устройстве есть активная/ожидающая задача (тот же сигнал занятости EventDAO::getDevicesWithPendingEvents(), по которому EventHandler не назначает задачи). Иначе разрыв оборвал бы выполняющийся bank-скрипт.
• Бесшовное отключение кабеля. К моменту отключения USB Wi-Fi-эндпоинт уже поднят и виден в adb devices, поэтому перехода в офлайн не происходит.

Конфигурация (config.ini, секция [wifi])

Ключ	Назначение	Дефолт
enabled	Полностью вкл/выкл функционал	true
port	TCP-порт adbd для tcpip-режима	5555
reconnectIntervalSecs	Как часто переподключать сохранённые эндпоинты	30
bootstrapRetryIntervalSecs	Мин. интервал между попытками bootstrap одного устройства	120
macRediscoverEnabled	Искать устройство по MAC при смене IP (DHCP)	true
macRediscoverIntervalSecs	Мин. интервал между попытками поиска по MAC	300
subnetSweepEnabled	Прогрев ARP ping-сканом /24 (медленно/шумно)	false

Ограничения

• Перезагрузка телефона сбрасывает tcpip-режим (adbd возвращается в USB-only). Wi-Fi-резерв поднимется заново при следующем подключении кабеля.
• Смена IP (новый адрес по DHCP) обрабатывается поиском по MAC: при неуспешном adb connect воркер находит устройство в ARP-таблице по сохранённому MAC и переподключается на новый IP. Если устройства нет в ARP, помогает либо включённый subnetSweepEnabled (ping-скан /24 — медленно, шумно), либо повторный bootstrap по USB. Поиск по MAC требует, чтобы ARC и устройство были в одной L2-подсети (ARP не маршрутизируется), и работает только когда MAC был снят при bootstrap.
• Требуется, чтобы телефон и десктоп были в одной сети Wi-Fi (маршрутизируемой до ip:port устройства).
• Чтение MAC идёт через ip addr show wlan0 (та же команда, что и для IP), фолбэк — cmd wifi status. Оба проходят без root, включая MIUI/HyperOS (где cat /sys/... и ip link show отдают Permission denied). Обычно это рандомизированный per-SSID MAC, но он стабилен для сети и совпадает с тем, что видит ARP-таблица ПК. Если MAC снять не удалось — эндпоинт хранится без него: теряется только восстановление при смене IP, остальное (bootstrap, reconnect, kick) работает.
• Скриншоты по Wi-Fi медленнее. Основной путь захвата — http через APK arc-shot (байты идут мимо adb, см. [screenshot] в config.ini); при его недоступности — fallback на exec-out screencap, который отдаёт полноразмерный PNG через adb и по сети тяжелее USB. Для wireless-serial таймаут fallback-захвата поднят (12 c против 10 c по USB). Интервал превью задаётся [screenshot] (previewIntervalHttpSecs для http, previewIntervalSecs для exec-out) и от транспорта Wi-Fi не зависит напрямую. На детект online/offline не влияет; на слабом линке отдельные кадры всё равно могут не успевать.
• Залипшее соединение vs. статус offline. На практике мёртвый Wi-Fi часто остаётся в adb devices как device (команды виснут), а не переходит в offline — поэтому основной триггер починки именно debounced-offline, а не статус offline (см. Поведение).

Требования к сети

Не требуют доработок ARC — это настройки сети/развёртывания.

Обязательно (иначе Wi-Fi-ADB не работает):

• ПК с ARC и устройства — в одной L2-подсети (или маршрутизируемой до ip:5555).
• На роутере отключить AP isolation (изоляцию клиентов Wi-Fi) — иначе порт 5555 между узлами недоступен.
• Единый adb (бандл tools/adb/...), один adb-сервер — чтобы списки устройств у ARC и фоновых операций не расходились.

Опционально (предсказуемый адрес устройства — снижает число переподключений): смену IP по DHCP ARC и так переживает поиском по MAC (см. Ограничения), поэтому ниже — не требования, а способы сделать адрес стабильным:

Способ	Где настраивать	Работает на Android <11
DHCP-резервация по MAC	роутер	да
Статический IP на самом устройстве	каждое устройство	да
mDNS-имя (adb connect <имя>.local)	устройство + сеть	нет (только 11+; в ARC не используется)
Поиск по MAC силами ARC (macRediscoverEnabled)	— (уже в ARC)	да

Безопасность

adb tcpip открывает порт 5555 на самом телефоне (на его Wi-Fi-IP), а не на ПК. Парк из N устройств = N эндпоинтов ip:5555, различаются по IP. Это отладочный доступ к устройству, достижимый для любого узла той же L2-подсети. Доступ всё ещё проходит RSA-авторизацию adb (чужой ключ упрётся в запрос «Allow debugging?» на экране), но сама открытая поверхность + контекст (это банковские приложения) требуют сетевой гигиены. На уровне приложения порт закрыть нельзя — на нерутованном устройстве это свойство adbd, поэтому безопасность здесь почти целиком инфраструктурная:

• Выделенная/изолированная Wi-Fi-сеть для фермы — без выхода в недоверенный сегмент. На роутере отключить AP isolation (иначе узлы не видят порт 5555 друг друга — это и про работоспособность), но саму сеть держать сегментированной (VLAN/гостевую-наоборот).
• Защита adbkey управляющего ПК. RSA-ключ этой машины — фактический «пароль» ко всему парку (особенно при «всегда разрешать с этого компьютера»). Хранить только на ней, доступ к машине ограничить.
• Ограничение на уровне роутера/файрвола — сузить, кто вообще достаёт до :5555 устройств (по возможности — только управляющий ПК).
• Поиск по MAC / subnetSweepEnabled сканируют подсеть — ещё одна причина держать ферму в выделённой сети (в чужой/общей сети скан нежелателен).

Главный практический долг по безопасности — организационный: выделенная сеть, AP isolation off + сегментация, защита adbkey. В коде ARC тут рычагов нет.

Где в коде

• android/adb/AdbUtils — низкоуровневые обёртки (isWirelessSerial, getDeviceWifiIp, getDeviceMac, enableTcpip, connectWireless, disconnectWireless).
• android/adb/WifiAdbManager — авто-bootstrap (tryBootstrap), переподключение (reconnectKnown: починка offline-эндпоинтов через disconnect→connect и поиск по MAC при смене IP), принудительный kick залипшего эндпоинта (kickEndpoint), хранение эндпоинтов (loadEndpoints/forget).
• services/DeviceScreener — интеграция в цикл опроса (reconnect c починкой stale → dedup USB/Wi-Fi → kick на debounced-offline (с guard по занятости) → bootstrap простаивающих; увеличенный таймаут/интервал screencap для wireless).
• views/device/DeviceWidget — пассивный бейдж «Wi-Fi» на карточке устройства; показывается только когда устройство онлайн по Wi-Fi (у офлайн-карточки не горит, чтобы не вводить оператора в заблуждение).