Document X4 USB power limits from root hub diagnostics

apps/node-agent/packaging/diagnose_x4_profile.py

@@ -65,7 +65,52 @@ def report():
     )
 
 
-def launch():
+def usb_report():
+    """Read xHCI root-hub capabilities; never open the attached camera or switch ports.
+
+    This is an engineering observation, not an installation prerequisite.
+    usbutils must already exist: this reader never installs or repairs anything.
+    The same versioned file is executed in the owner terminal and retained with
+    its report. A hub's advertised switching capability is not a VBUS measurement.
+    """
+    if os.geteuid() != 0:
+        raise ValueError("Use the owner terminal")
+    roots = []
+    for root in sorted(Path("/sys/bus/usb/devices").glob("usb[0-9]*")):
+        if not re.fullmatch(r"usb[0-9]+", root.name):
+            continue
+        device = root.resolve(strict=True)
+        if (device.parent / "driver").resolve().name != "xhci_hcd":
+            continue
+        if (root / "idVendor").read_text().strip() != "1d6b":
+            continue
+        if (root / "idProduct").read_text().strip() not in {"0002", "0003"}:
+            continue
+        bus = int((root / "busnum").read_text())
+        address = int((root / "devnum").read_text())
+        if not 1 <= bus <= 999 or address != 1:
+            raise ValueError("Unexpected root-hub address")
+        before = {"utc": datetime.now(UTC).isoformat(), "monotonic": time.monotonic()}
+        result = subprocess.run(
+            ["/usr/bin/lsusb", "-v", "-s", f"{bus}:1"],
+            capture_output=True, text=True, timeout=10,
+            env={"PATH": "/usr/bin:/bin", "LC_ALL": "C"},
+        )
+        roots.append({
+            "root": str(device), "before": before,
+            "returncode": result.returncode,
+            "stdout": result.stdout, "stderr": result.stderr,
+        })
+    if not roots:
+        raise ValueError("No admitted Linux xHCI root hubs")
+    print(json.dumps({
+        "schema": "missioncore.node.x4-usb-power-diagnostic/v1",
+        "utc": datetime.now(UTC).isoformat(), "monotonic": time.monotonic(),
+        "roots": roots, "port_writes": False, "electrical_measurement": False,
+    }), flush=True)
+
+
+def launch(usb=False):
     if os.geteuid() == 0:
         raise ValueError("Launch as the desktop owner")
     source = Path(__file__).resolve()
@@ -76,18 +121,22 @@ def launch():
         raise ValueError("Diagnostic artifact changed")
     os.umask(0o077)
     folder = source.with_suffix("")
+    if usb:
+        folder = folder.with_name(folder.name + "-usb")
     folder.mkdir(mode=0o700, exist_ok=True)
     info = folder.lstat()
     if folder.is_symlink() or info.st_uid != os.getuid() or info.st_mode & 0o077:
         raise ValueError("Diagnostic directory must be private")
     script = folder / "read-report"
+    title = "чтение возможностей USB-портов" if usb else "чтение ошибки подготовки X4"
+    mode = "--read-usb" if usb else "--read"
     script.write_text(
         "#!/bin/bash\nset -uo pipefail\numask 077\nprintf '%s\\n' "
-        "'Mission Core: чтение ошибки подготовки X4' "
+        "'Mission Core: " + title + "' "
         "'Изменений системы и команд камеры не будет. Введите пароль Ubuntu.'\n"
         "/usr/bin/sudo /usr/bin/python3 -I '"
         + str(source)
-        + "' --read 2>&1 | /usr/bin/tee '"
+        + "' " + mode + " 2>&1 | /usr/bin/tee '"
         + str(folder / "report.json")
         + "'\nmc_x4_result=${PIPESTATUS[0]}\nprintf "
         "'\\nКод завершения: %s\\nНажмите Enter, чтобы закрыть.\\n' "
@@ -134,5 +183,9 @@ if __name__ == "__main__":
         report()
     elif sys.argv[1:] == ["--launch"]:
         launch()
+    elif sys.argv[1:] == ["--read-usb"]:
+        usb_report()
+    elif sys.argv[1:] == ["--launch-usb"]:
+        launch(usb=True)
     else:
-        sys.exit("Use --launch or --read")
+        sys.exit("Use --launch, --read, --launch-usb or --read-usb")

docs/node/07_INSTA360_X4_INSTALLATION_LEDGER.md

@@ -742,3 +742,61 @@ Mac monotonic446251.627551791→446492.403596291,239 USB samples,exit0,stderr em
 официальный tasker_get_agent_instructions вернул timeout60s; никаких Ops mutations
 этим вызовом не было. Результат и очередь сохранены здесь; синхронизация
 MISSIONCOR-77 остаётся следующему успешному обращению MCP.
+
+
+## PORT01 — измерения порта и смена следующего контроля,10.09.2026
+
+По прямому указанию владельца другой кабель исключён из ближайшего gate;
+нужны измерения Ubuntu и программный/аппаратный обход. Причина ещё открыта.
+Read-only SSH07:48:51.510684 UTC,Ubuntu monotonic324839.391772184:
+USB2/USB3 peer-пара X4 active,disable0,not attached,over_current_count0; xHCI
+D0,control on,runtime PM forbidden. Power_supply пуст; hwmon показывает только
+CPU, датчиков VBUS/USB current нет. Extra07:55:04.082038 UTC,monotonic325211.963130727:
+обе early_stop=no,USB3 LPM permitted u1_u2. Это не electrical qualification.
+
+Private0600 readonly.jsonl SHA-256
+cc5f8c1b2a2e771a3bdc1a2fdfbcd64d6003d644b63f2d7cd1edf950e46fb3a1;
+extra.jsonl SHA-256 b93a68508bddbd8f8d025472ca042ad67b7eed3173b7f7fc74e0f814a33ec91f.
+В kernel обнаружено отдельное окно после завершённого REPLUG03:
+07:40:38–40 USB2 -71/attempt power cycle;07:40:42.968 Mass Storage070a:4026;
+07:40:59.096 disconnect. Внешний триггер этого цикла не установлен.
+Sudo -n lsusb root-hub reader вернул password required, никаких USB changes.
+
+Следующий reader входит в versioned engineering artifact
+apps/node-agent/packaging/diagnose_x4_profile.py (--launch-usb/--read-usb),
+SHA-256 711fdbc2dd56305443c72fac6ab4c69e1afc8d68500a6b0c31cb203ed3c478d5.
+Python syntax проверен. Владелец авторизует только чтение xHCI root descriptors
+через локальный sudo TTY; две команды lsusb ограничены10s каждая. Использует
+уже установленный usbutils, ничего не устанавливает. Read-only engineering
+не является prerequisite запуска X4 и не меняет installed model0.1.3-3/Node0.8.19.
+Стейджинг — приватный файл /var/tmp с именем по SHA, отчёт0600, никакого
+изменения systemd/udev/прав/портов. Повторное чтение не имеет device effects.
+Rollback не требуется; перед любым будущим переключением портов сначала
+изменяется и квалифицируется shipped installer/versioned preparation.
+Результат root reader ещё не получен; аппаратный VBUS и recovery не приняты.
+
+
+PORT01 root reader complete07:59:04.582247 UTC,Ubuntu monotonic325452.463335022.
+Обе команды lsusb returncode0,stderr empty; root-hubs.json0600 SHA-256
+b521133ccd252abb45bdc9e7a21595797461713deeb1156fd7df91e5e5917616.
+Оба xHCI root hubs USB2/USB3: wHubCharacteristic0x000a,No power switching,
+Per-port overcurrent protection. USB2 port2 power/no connect; USB3 port2
+power/Rx.Detect/no connect. Стандартное VBUS switching на встроенном Mini не
+предоставлено. Это не измерение фактического напряжения/тока и не доказательство
+причины firmware/USB сбоя. Агент не отправлял port reset/disable/PM writes.
+
+Дальше программный recovery имеет смысл после правильной enumeration; полный
+power recovery требует проверенного внешнего индивидуального VBUS switching
+и отдельно доказанной схемы выключения X4 с/без батареи. Повторная установка
+SDK отсутствие камеры на USB не исправляет. В планах10/11 больше нет ожидания
+замены кабеля от владельца. Ops MCP восстановился: инструкции/проект/context
+считаны, MISSIONCOR-77 обновлён штатным update_structured_blocks08:01:54 UTC,
+включая REPLUG03; автономность/питание не отмечены выполненными.
+
+PORT01 handoff08:03:28.643589 UTC,Mac monotonic447888.607800625:
+Core8000 operational,Node online,D455 online/streaming,X4 offline/idle.
+Private0600 handoff.json SHA-256
+104a204df2f5daea6f0828623c6506bbe7ae1de7d8b65bc5c711ac5747f33557.
+Канонический Core оставлен работающим. Никаких новых viewer/worker/observer
+процессов не запускалось; root descriptor reader завершился. Локальное
+диагностическое окно после результата ждёт Enter, не выполняет работу.

docs/node/09_INSTA360_X4_IMPLEMENTATION_STATUS.md

@@ -94,4 +94,14 @@ REPLUG02/LIVE07 восстановление: после выполненног
 
 OWNER03: владелец подтвердил автоматический Android mode после camera off/on→USB in и просмотр изображений X4 и D455 при переходах между их карточками в Core. Текущий Node snapshot обеих камер online/streaming; одновременное отображение,30 минут потока и FPS/latency ещё не измерены. Следующий hardware control — idle replug, затем active replug; установленные службы в этом уточнении не менялись.
 
-REPLUG03: idle USB replug также failed. Preview STOP и fresh idle/recording0 подтверждены до извлечения; после возврата кабеля до конца239-sample observer X4 не перечислилась на USB. Активная трансляция непосредственно при отключении не является необходимым условием отказа; предыдущий SDK lifecycle и физические причины ещё не разделены. Следующий control — другой data cable без camera restart и без смены порта; наличие кабеля ожидается от владельца. Ops write отложен: официальный instructions read получил timeout60s.
+REPLUG03: idle USB replug также failed. Preview STOP и fresh idle/recording0 подтверждены до извлечения; после возврата кабеля до конца239-sample observer X4 не перечислилась на USB. Активная трансляция непосредственно при отключении не является необходимым условием отказа; предыдущий SDK lifecycle и физические причины ещё не разделены. Владелец затем отклонил замену кабеля как ближайший gate; PORT01 переносит приоритет на адресную диагностику и программное восстановление порта. Ops write отложен: официальный instructions read получил timeout60s.
+
+PORT01: read-only sysfs обеих половин разъёма X4: active, disable0, not attached, early_stop=no, over_current_count0; xHCI D0/control on/runtime PM forbidden. Признаков текущего усыпления нет; VBUS/ток не измерены (датчики не доступны). После REPLUG03 observer kernel записал новый краткий Mass Storage attach07:40:42–59, без SDK mode. Подготовлен versioned read-only root-hub reader diagnose_x4_profile.py --launch-usb; аппаратное power switching и USB recovery пока не проверены. Подробности и private hashes в ledger/плане11.
+
+PORT01 root reader завершён07:59:04 UTC: обе команды lsusb code0, USB2/USB3
+wHubCharacteristic0x000a, No power switching. USB3-порт X4 power/Rx.Detect/no connect.
+Стандартного адресного VBUS off/on встроенный контроллер Mini не предоставляет.
+USB writes не выполнялись. Следующий аппаратный путь — отдельный управляемый
+хаб с доказанным VBUS switching и отдельной проверкой полного выключения X4
+при выбранной схеме батареи/питания. Ops MISSIONCOR-77 обновлён, включая ранее
+отложенный REPLUG03; power/replug/recovery checker остаются открытыми.

docs/node/10_INSTA360_X4_NEXT_STEPS.md

@@ -12,7 +12,7 @@ B11/P09,09.09: эта реализация готова и прошла38 Ubuntu
 
 Предварительное условие NET01 закрыто NET02/NET03,10.09: Core–Node восстановили канал через Tailscale с прежними trust/identity. В Core подтверждены несколько свежих mTLS heartbeat, endpoint revision1. После восстановления заново читать актуальное состояние камеры перед любыми preview/model операциями; прежний stale inventory не подтверждает её текущее состояние.
 
-P10/PREP05 complete: Node0.8.19 и X4 model0.1.3-3 установлены штатно. LIVE06 подтвердил первый и повторный START, active verify и viewer reopen:1083 декодированных кадра1280×640, без SD записи. REPLUG01 выявил отказ active USB replug; REPLUG02/LIVE07 восстановили камеру после camera off/on. OWNER03 подтвердил автоматический Android mode после этого включения. REPLUG03 подтвердил такой же отказ при fresh idle/preview0. Теперь первый контроль — другой data cable при том же порту/включённой камере, затем раздельная диагностика порта/питания и boot сценарии. Задержка NET03 recovery и длительная video stability остаются открытыми.
+P10/PREP05 complete: Node0.8.19 и X4 model0.1.3-3 установлены штатно. LIVE06 подтвердил первый и повторный START, active verify и viewer reopen:1083 декодированных кадра1280×640, без SD записи. REPLUG01 выявил отказ active USB replug; REPLUG02/LIVE07 восстановили камеру после camera off/on. OWNER03 подтвердил автоматический Android mode после этого включения. REPLUG03 подтвердил такой же отказ при fresh idle/preview0. Владелец исключил замену кабеля из ближайшего gate. PORT01: порты/контроллер активны, early_stop=no, перегрузок0; измерителей VBUS/тока нет. Root reader подтвердил No power switching у обоих xHCI root hubs: штатно снимать VBUS встроенного порта нельзя. Следующая аппаратная ветка — управляемый хаб, с отдельной квалификацией питания/полного выключения X4; программный recovery SDK/preview — после возврата USB. Задержка NET03 recovery и длительная video stability остаются открытыми.
 
 OWNER03: владелец видит изображение X4 и D455 через Core при переходах между карточками. Read-only Node snapshot обеих камер online/streaming. Длительная одновременная работа и измерения ещё не приняты.
 
@@ -30,7 +30,7 @@ camera settings/file download. Конкретная матрица, доказа
 |---|---|---|
 | Завершено, P5 | Общие состояния loading в DG: pending инициирующей кнопки, центр content region, отсутствие бесконечной загрузки после ошибки. Shared frontend для Core и Node, каталог и правила. | UI01/N09 установлен в Core8000 и Node0.8.18. Сборки/819 Core tests, DG tests/catalog и Node checks прошли. Browser geometry, normal/expanded/Escape, light/dark и error lifecycle проверены. Native Node visual QA ещё открыта. |
 | B11 ограниченно принят, P3/P4 | Исправлено очищение feed при повторном START и проверка активного потока через новый decoder. PREP05/LIVE06: repeat START, live verify, viewer reopen complete. |1083 кадра1280×640; долгий capture и все возможные причины stale отдельно не приняты. |
-| Первый следующий, P3/P4 | Локализация failed idle и active replug: другой data cable при том же порту/включённой камере; затем раздельные port/power/boot controls. После возврата USB — SDK recovery/preview intent по плану11. | Возврат того же экземпляра без переустановки и ручного режима, восстановление изображения; VBUS доказан отдельным физическим тестом. |
+| Первый следующий, P3/P4 | PORT01: штатное VBUS switching встроенного Mini не поддерживается. Для power recovery нужен проверенный управляемый хаб и раздельные battery/power/boot controls; изменения сначала входят в packaged preparation. Замену кабеля владелец не выбрал. После возврата USB — SDK recovery/preview intent по плану11. | Возврат того же экземпляра без переустановки и ручного режима, восстановление изображения; VBUS доказан отдельным физическим тестом. |
 | Следующий, P4 + P5 | Совместимый локальный просмотр в установленном Node/WebKit. Исходный план предусматривает HTTP/fMP4 carrier от той же медиа-сессии; переиспользуются общие media lifecycle/lease части K1, без импорта K1 protocol или второго SDK владельца X4. | На Ubuntu в приложении Node есть движущееся изображение; одновременно открыт удалённый Core. Закрытие одного зрителя сохраняет другого, не меняет SD recording. Все runtime dependencies входят в .deb/profile. |
 | Затем, P4C | Матрица поддержанных действий по фактическим SDK headers и capabilities: camera settings, normal photo/video, ISO/exposure/WB/resolution, отдельные SD start/stop и фото. Проверять readback, mode dependencies и отображение результата. | Явные адресные команды из обеих UI, реальные результаты на камере, неизвестный outcome не переигрывается автоматически. Не обещать все режимы SDK до их проверки; shutter/EV setters и неподдержанные поля перечисляются отдельно. |
 | P4C + общий source-record workflow | Получение содержимого выбранного файла на Node и в Core, bounded transfer, прерывание/продолжение, длина/hash и происхождение. Каталог уже есть, download ещё нет. | Пользователь получает существующий файл без shell; повторы/обрыв связи не меняют оригинал на SD. Незавершённый записываемый файл обрабатывается явно. |

docs/node/11_INSTA360_X4_AUTONOMY_AND_USB_POWER.md

@@ -86,10 +86,55 @@ X4 offline,Node и D455 online. Worker остановлен штатно, superv
 этого отказа. Прежний preview/SDK lifecycle, кабель, контакт, host port, питание
 и firmware ещё не разделены. Автоматический SDK retry не может восстановить
 устройство, пока его нет на USB. Повторять тот же active replug следующим шагом
-недостаточно для локализации. Следующий control — другой data cable при том же
-порту и той же включённой X4; наличие кабеля запрошено, тест ещё не выполнен.
-При недоступности другого кабеля выбирается отдельный hardware control,
-не допускающий reset всего контроллера или нарушения работы D455.
+недостаточно для локализации. Предлагался другой data cable; тест не выполнен.
+Последующее указание владельца: замену кабеля не использовать как ближайший
+gate, исследовать программный обход и измерения на Ubuntu. Это смена приоритета,
+а не доказательство локализации причины в firmware.
+
+## PORT01 — чтение портов и контроллера, 10.09.2026
+
+07:48:51 UTC: Macmini6,2, Intel xHCI8086:1e31, Linux7.0.0-31-generic.
+Обе логические половины точного разъёма X4 связаны через sysfs peer. Каждая
+имеет disable0, state not attached, runtime active, over_current_count0.
+Контроллер D0, power/control on, runtime PM forbidden. В07:55:04 обе early_stop
+имеют no; USB3 usb3_lpm_permit=u1_u2. Текущего усыпления/блокировки после ошибки
+не обнаружено. Разрешённый LPM не доказывает, что он вызвал прошлый disconnect.
+Счётчик перегрузок0 не является измерением напряжения или доказательством
+достаточного питания. Доступные power_supply/hwmon не показывают VBUS/ток порта.
+
+После завершения окна REPLUG03 kernel дополнительно зарегистрировал USB2
+descriptor errors -71 и собственный attempt power cycle07:40:38–40;07:40:42.968
+X4 появилась как Mass Storage070a:4026, затем disconnect07:40:59.096.
+Внешнее действие, вызвавшее этот дополнительный цикл, не установлено. Это новые
+события после observer, а не исправление его239-sample результата.
+
+Выполнен read-only шаг — описание возможностей питания обоих xHCI root hubs
+через уже установленный lsusb, в versioned diagnose_x4_profile.py --launch-usb.
+Нужен root для чтения дескрипторов; после sudo -n password required reader
+запущен через локальный owner terminal и завершился07:59:04 UTC.
+Диагностический читатель не является runtime prerequisite: он не устанавливает
+пакеты, не переключает порты и не открывает камеру. Любое последующее изменение
+USB сначала входит в shipped installer/versioned preparation. По
+[Linux ABI](https://raw.githubusercontent.com/torvalds/linux/master/Documentation/ABI/testing/sysfs-bus-usb)
+наличие disable само по себе не подтверждает аппаратное снятие VBUS. Действие
+разрешается проектировать только для проверенной USB2/USB3 пары, с возвратом
+обоих портов во включённое состояние; глобальный reset затронет D455 и HID.
+
+Root reader07:59:04.582247 UTC,monotonic325452.463335022: обе lsusb команды
+returncode0,stderr empty. USB2 и USB3 root hubs имеют wHubCharacteristic0x000a:
+**No power switching**, Per-port overcurrent protection. USB2 port2: power,
+без connect; USB3 port2: power,Rx.Detect,без connect. Это аппаратно заявленные
+возможности и логический статус, не физическое измерение5V. Стандартного
+переключения VBUS этот контроллер не предоставляет; попытка sysfs disable
+не рассматривается как доказанный power cycle. Root/port writes не выполнялись.
+
+Следующий путь полного автономного восстановления требует отдельно проверить
+хаб с индивидуальным VBUS switching и достаточным внешним питанием. Само
+отключение VBUS при батарее не перезапускает гарантированно X4; режим без
+батареи и USB power-on требуют отдельной аппаратной приёмки. До её появления
+подтверждённый способ возврата — camera off/on, затем USB in (REPLUG02).
+Никакая новая покупка/схема питания здесь не выполнялась. Программный recovery
+SDK/preview остаётся отдельным инкрементом после возврата правильного USB mode.
 
 ## Поведение текущего приложения
 
@@ -148,7 +193,7 @@ disconnect для части прошивок; текущий bridge его не
 | 2. Повторное подключение | Контролируемое USB disconnect/reconnect при открытом наблюдении: offline камеры при online Node, прежний device_id, новая session_id, отсутствие повторной установки и ручного выбора Android. Замерить время SDK-ready/первого кадра. |
 | 3. Холодный запуск | Отдельно camera power cycle и reboot Ubuntu, с фиксацией battery presence, USB mode retention, wake-on-power, порядка запуска служб. Не объединять результаты этих сценариев. |
 | 4. Автовосстановление | По выявленным отказам добавить bounded SDK reopen/backoff/watchdog per instance. Для включённого профиля автопросмотра хранить намерение preview отдельно от SDK-сессии и восстанавливать его после подтверждения той же камеры; UI пересоздаёт WebRTC на новой сессии. SD-запись/фото не повторяются. |
-| 5. Питание разъёма | Включить адресную диагностику/действие в versioned preparation artifact. Прочитать hub capability, сопоставить USB2/USB3 пару, проверить физический VBUS off/on и сохранность остальных портов. Только после доказанного питания — сценарий без батареи и измерение потребления при запуске/preview. |
+| 5. Питание разъёма | Включить адресную диагностику/действие в versioned preparation artifact. Прочитать hub capability, сопоставить USB2/USB3 пару, проверить физический VBUS off/on и сохранность остальных портов. PORT01: встроенный контроллер сообщает No power switching. Следующая аппаратная ветка — отдельный управляемый хаб; только после доказанного питания — сценарий без батареи и измерение потребления при запуске/preview. |
 | 6. Приёмка | Несколько успешных replug/cold-start циклов,30 минут выбранного потока, измерение задержки и восстановления; все зависимости/права/правила/откаты входят в installer, чистый OS image остаётся отдельной проверкой. |
 
 Целевой профиль: после однократной подготовки включение борта приводит к