Диагностика проблем¶

Начинайте с границы, на которой пропадают данные: устройство → ROS-топик → веб-просмотр → запись или модель. Если камера не публикует изображение, настройка нейросети не восстановит поток. Если изображение есть в ROS, но отсутствует в браузере, сначала проверяйте подписку и конфигурацию веб-сервера.

При запуске через CLI начните с smartcamera doctor и smartcamera logs --follow. При запуске без --detach оставляйте терминал открытым. В нём видны ошибки открытия камеры, применения YAML, запуска процессов и обработки запросов. Для обращения с проблемой сохраните сообщение целиком, команду запуска, тип камеры, выбранный режим и версию окружения. Не прикладывайте ключи S3 и другие credentials.

Не найден ROS-пакет или Python-модуль¶

Для локальной установки по прямой ссылке восстановите окружение в новом терминале:

cd "$HOME/.local/share/smartcamera/source"
source /opt/ros/jazzy/setup.bash
source .venv/bin/activate
source install/setup.bash
ros2 pkg prefix smart_camera_web
python - <<'PYTHON'
import sys
import rclpy
import cv2
import pydantic

print(sys.executable)
print(cv2.__version__, pydantic.__version__)
PYTHON

Если ros2 pkg prefix не находит пакет, workspace не собран либо подключён не тот install/setup.bash. Если Python не видит ROS, проверьте, что .venv создана через /usr/bin/python3 -m venv --system-site-packages, а не отдельным Python без системных библиотек. Ошибки импорта Pydantic обычно означают, что приложение использует версию 1 вместо 2.

Активация окружения не меняет Python в уже созданном ROS-скрипте. Проверьте первую строку установленного веб-сервера:

head -n 1 "$(ros2 pkg prefix smart_camera_web)/lib/smart_camera_web/web_server"

Если устанавливали из своего каталога, подставьте его путь. Для Docker повторите smartcamera docker-setup --yes после остановки контейнера; окружение хоста не изменяет образ.

Для восстановления зависимостей локальной установки остановите приложение и повторите подготовку выбранного профиля:

smartcamera stop

smartcamera local-setup --yes --profile cpu

smartcamera run

Если используете NVIDIA, укажите --profile cuda. Для обычной пересборки исходников достаточно smartcamera rebuild. Не устанавливайте opencv-python поверх системного OpenCV окружения ROS. Ошибка externally-managed-environment при pip --user не возникает в штатной установке CLI: он использует отдельные окружения Python.

Не собирается веб-интерфейс¶

Проверьте Node.js и локальные зависимости:

cd "$HOME/.local/share/smartcamera/source"
export PATH="$PWD/.local/node/bin:$PATH"

node --version
npm --version

cd src/smart_camera_web/frontend
npm ci
npm run build

Vite 8 требует Node ^20.19.0 || >=22.12.0; Node 18 не подходит. Ошибка об отсутствии frontend/node_modules означает, что bootstrap не выполнен. colcon запускает сборку интерфейса, но npm-зависимости не скачивает. После успешной отдельной сборки вернитесь в корень workspace и повторите сборку ROS-пакета.

Если браузер показывает старую версию страницы, убедитесь, что запущен сервер из нужного workspace, пересоберите smart_camera_web и перезапустите сервер. Само изменение React-файлов не обновляет установленный production frontend. Сообщения об отсутствующих frontend-файлах проверяйте отдельно от состояния камер.

Веб-страница не открывается¶

Сначала выполните на компьютере сервера:

curl --fail --verbose http://127.0.0.1:8000/api/v1/cameras
ss -ltnp | rg ':8000'

Connection refused означает, что по этому адресу и порту нет слушающего сервера. Посмотрите, не завершился ли web_server при старте из-за YAML, Python-зависимостей или занятого порта. HTTP-ответ с ошибкой — другая ситуация: сервер работает, и нужно читать код и текст ответа.

По умолчанию web_host равен 127.0.0.1: доступ возможен только с этого компьютера. Для доверенной локальной сети добавьте web_host:=0.0.0.0; на другом компьютере открывайте IP сервера, а не 127.0.0.1. Если локальная проверка проходит, проверьте сетевой маршрут и firewall. Аргумент web_port:=8001 позволяет использовать другой свободный порт.

USB-камера не открывается или пропадает¶

v4l2-ctl --list-devices
ls -l /dev/v4l/by-id/
v4l2-ctl --device=/dev/video0 --list-formats-ext
id
ls -l /dev/video0

Замените /dev/video0 узлом вашей камеры. Сверьте путь с YAML, права пользователя и поддерживаемые режимы. Если устройство доступно группе video, а пользователь в неё не входит, добавьте его через sudo usermod -aG video "$USER", затем полностью завершите пользовательский сеанс и войдите снова. Уже запущенные процессы новые группы не получают.

Закройте другую программу, которая захватывает ту же камеру. Проверьте USB-кабель, питание и порт. Для нескольких камер уменьшите разрешение/FPS либо выберите поддерживаемый MJPG; одинаковые высокие raw-потоки могут исчерпать пропускную способность общей USB-шины. Сначала добейтесь устойчивой работы одной камеры.

Если изменение настроек отклоняется, это может быть штатный откат: новый профиль не дал первый кадр. Не увеличивайте таймаут без проверки режима и доступности устройства. При успешном переподключении драйвер продолжает работу; постоянный цикл ошибок виден в /diagnostics и журнале.

ROS-топик есть, изображения нет¶

ros2 topic list -t
ros2 topic info /smart_camera/front/image_raw/compressed -v
ros2 topic hz /smart_camera/front/image_raw/compressed
ros2 topic echo /diagnostics --once

Подставьте фактический топик. Для аппаратного compressed-потока к topic добавляется /compressed; у внешнего interface: ros имя уже должно быть полным. Проверьте тип: Image и CompressedImage требуют разных подписок. Для изображений используется best-effort/volatile/depth 1; reliable-подписчик может оказаться несовместимым.

На разных компьютерах сравните ROS_DOMAIN_ID, DDS-настройки и сетевую доступность. ROS_LOCALHOST_ONLY=1 ограничивает обмен локальным компьютером. Сам факт присутствия имени топика ещё не подтверждает поступление кадров: смотрите частоту и время последних сообщений.

RealSense видна в USB, но не в приложении¶

Для L515 проверьте, с каким SDK собран драйвер и какую библиотеку получает процесс. Проект использует отдельный librealsense 2.50.0; установка современной системной библиотеки не заменяет этот шаг. При самостоятельном запуске вне общего launch нужно явно выбрать библиотеку:

L515_PREFIX="$HOME/.local/librealsense-l515-2.50.0"
export LD_LIBRARY_PATH="$L515_PREFIX/lib${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}"

Для общего launch есть realsense_sdk_prefix; переменная CMAKE_PREFIX_PATH выбирает SDK при сборке, а не только при запуске. После смены SDK пересоберите с чистым CMake-кэшем. Сверьте serial и RGB-D профиль с discovery. Проверенный профиль L515 — RGB и depth 640×480@30; это не обещание поддержки любого сочетания размеров. Настройки D400 Advanced Mode и аппаратной синхронизации не следует переносить на L500. См. установку и камеры.

YAML не сохраняется или возникает конфликт¶

configuration_conflict или HTTP 409 означает, что другой клиент уже изменил конфигурацию. Перечитайте её и повторите изменение с новой ревизией. HTTP 428 требует If-Match. Не подставляйте случайную ревизию и не повторяйте устаревший запрос бесконечно.

При config_not_writable проверьте фактический camera_config_path в /api/v1/settings, права файла и каталога. При symlink-install запись может идти в исходный YAML. invalid_camera_config часто связан с неизвестным полем, повтором ID/устройства/топика или недоступным calibration-файлом. Формат описан в справочнике конфигурации.

Не записывается материал или исчез архив¶

Проверьте свободное место (df -h), доступность каталога материалов и наличие FFmpeg (ffmpeg -version). Одновременно выполняется одна операция записи: фото, серия, MP4 или bag. Для группового фото все выбранные камеры должны предоставить свежие кадры с допустимым timestamp skew. Увеличение количества выбранных камер не создаёт аппаратную синхронизацию.

Если после смены каталога архив пуст, проверьте сохранённый recordings_directory: старые файлы автоматически не переносятся. Также сохранённый JSON настроек может переопределить стартовый каталог launch. После изменения каталога перезапустите приложение, чтобы калибровки, HandEye и inference использовали согласованные корни. Прерванная запись после восстановления может иметь статус interrupted; это отличается от успешного завершения.

Модель включена, результата нет¶

Проверьте обычный поток камеры, состояние запуска и поле ошибки. Веса загружаются при следующем кадре, поэтому ответ на команду включения подтверждает настройки, а не готовность модели. После рестарта сервера запуск нужно включить снова.

В разделе моделей используйте проверку среды и устройств: она показывает именно ML Python. Установка Ultralytics в .venv веб-сервера не помогает, если SMART_CAMERA_INFERENCE_PYTHON указывает на другое окружение. PyTorch с суффиксом +cpu не использует CUDA. Фоновые задания могут ждать освобождения устройства от live-запусков. Подробности — в руководстве моделей.

Если результат есть в браузере, но отсутствует в ROS, проверьте best-effort QoS подписчика и result_errors в /smart_camera/status. Слишком большой JSON или истёкший ресурс пропускается с объяснением. timeout команды ROS не доказывает отмену операции: проверьте состояние и повторяйте запрос с тем же request_id, как описано в ROS 2 API.