init

2026-09-09 16:28:02 +03:00
commit f48465dfb1
36 changed files with 3580 additions and 0 deletions
@@ -0,0 +1,327 @@
+# Подготовка рабочего места с нуля
+
+Цель — за день настройки получить воспроизводимое рабочее место для физических РМК и Webots. Основная среда проекта: **Ubuntu 24.04 x86-64, ROS 2 Jazzy, Webots, Fast DDS, Python 3 и Git**.
+
+Все команды без объяснений продублированы в [`COMMANDS.md`](COMMANDS.md).
+
+## Сначала уточнить у эксперта
+
+До установки и обновлений зафиксируйте:
+
+1. Какая ОС и что уже установлено.
+2. Нужно ли использовать готовый образ организаторов.
+3. Какую версию Webots требует выданный пакет.
+4. Адреса GitLab/локального Git, логин и доступ к интернету.
+5. `ROS_DOMAIN_ID`, RMW и схему сети физических РМК.
+6. Разрешённые программы, сайты и LLM.
+
+Не обновляйте целиком уже работающее окружение непосредственно перед попыткой.
+
+## Если выдали Windows
+
+Windows используем как хост для редактора, Git и резервного доступа. Конкурсный ROS-стек из материалов рассчитан на Ubuntu 24.04. Нативную сборку всех пакетов под Windows нельзя считать равноценной без подтверждения организаторов.
+
+Откройте PowerShell от администратора:
+
+```powershell
+winget install --id Microsoft.WindowsTerminal -e
+winget install --id Microsoft.PowerShell -e
+winget install --id Git.Git -e
+winget install --id Microsoft.VisualStudioCode -e
+winget install --id OpenJS.NodeJS.LTS -e
+```
+
+После установки закройте и снова откройте терминал:
+
+```powershell
+git --version
+code --version
+node --version
+npm --version
+```
+
+Для вспомогательной Linux-среды можно установить Ubuntu 24.04 в WSL:
+
+```powershell
+wsl --install -d Ubuntu-24.04
+```
+
+После команды требуется перезапуск Windows. WSL подходит для Git, Python, Bun и редактирования, но DDS discovery, multicast, USB-камера и графический Webots могут отличаться от обычного Ubuntu. Для физического заезда предпочтительны нативный Ubuntu либо выданная Ubuntu VM с bridged-сетью и проверенным OpenGL.
+
+Если используется Ubuntu VM, выделите не менее 4 CPU, 8 ГБ RAM и 50 ГБ диска. Включайте 3D-ускорение только после проверки стабильности конкретного гипервизора.
+
+## Если выдали Ubuntu 24.04
+
+### Базовые программы
+
+```bash
+sudo apt update
+sudo apt install -y \
+  git curl wget unzip ca-certificates gnupg locales software-properties-common \
+  build-essential python3 python3-pip python3-venv python3-dev \
+  mesa-utils libxcb-cursor0 libxcb-xinerama0
+```
+
+Проверка GPU:
+
+```bash
+glxinfo -B
+```
+
+В `OpenGL renderer` не должно быть `llvmpipe`, если Webots должен работать с аппаратным ускорением.
+
+### Visual Studio Code
+
+Короткий официальный вариант для Ubuntu:
+
+```bash
+sudo snap install --classic code
+code --version
+```
+
+Snap здесь используется только для VS Code. Webots устанавливайте через `.deb`/APT: Snap-версия Webots уже создавала проблемы с ROS и Qt.
+
+Минимальные расширения:
+
+```bash
+code --install-extension ms-python.python
+code --install-extension ms-python.vscode-pylance
+code --install-extension ms-iot.vscode-ros
+code --install-extension ms-vscode.cpptools
+code --install-extension ms-vscode.cmake-tools
+code --install-extension redhat.vscode-yaml
+code --install-extension bradlc.vscode-tailwindcss
+code --install-extension dbaeumer.vscode-eslint
+code --install-extension esbenp.prettier-vscode
+```
+
+Для Windows/WSL дополнительно:
+
+```powershell
+code --install-extension ms-vscode-remote.remote-wsl
+code --install-extension ms-vscode-remote.remote-ssh
+```
+
+### Git и доступ к репозиториям
+
+```bash
+git config --global user.name "Nikita Shilov"
+git config --global user.email "YOUR_EMAIL"
+git config --global init.defaultBranch main
+
+ssh-keygen -t ed25519 -C "chvt-2026"
+eval "$(ssh-agent -s)"
+ssh-add ~/.ssh/id_ed25519
+cat ~/.ssh/id_ed25519.pub
+```
+
+Добавьте **публичный** ключ в GitHub/Gitea. Приватный `~/.ssh/id_ed25519` никуда не отправляйте и не коммитьте.
+
+```bash
+mkdir -p ~/scripts
+git clone git@github.com:mavxa/mvch.git ~/scripts/mvch
+git clone git@github.com:mavxa/mvch-docs.git ~/scripts/mvch-docs
+```
+
+Если GitHub недоступен, замените URL на зеркало Gitea. После клонирования код полностью локален; интернет для `git status`, веток и коммитов не нужен.
+
+Добавление зеркала к уже клонированному репозиторию:
+
+```bash
+git remote add gitea ssh://git@GITEA_HOST/USER/mvch.git
+git push gitea --all
+git push gitea --tags
+```
+
+Для `mvch-docs` повторите команды в его каталоге с URL репозитория `mvch-docs`.
+
+### ROS 2 Jazzy
+
+```bash
+sudo locale-gen en_US en_US.UTF-8
+sudo update-locale LC_ALL=en_US.UTF-8 LANG=en_US.UTF-8
+export LANG=en_US.UTF-8
+
+sudo add-apt-repository universe
+sudo apt update
+
+export ROS_APT_SOURCE_VERSION="$(curl -s https://api.github.com/repos/ros-infrastructure/ros-apt-source/releases/latest | grep -F 'tag_name' | awk -F\" '{print $4}')"
+curl -L -o /tmp/ros2-apt-source.deb \
+  "https://github.com/ros-infrastructure/ros-apt-source/releases/download/${ROS_APT_SOURCE_VERSION}/ros2-apt-source_${ROS_APT_SOURCE_VERSION}.$(. /etc/os-release && echo ${UBUNTU_CODENAME:-${VERSION_CODENAME}})_all.deb"
+sudo dpkg -i /tmp/ros2-apt-source.deb
+
+sudo apt update
+sudo apt install -y ros-jazzy-desktop ros-dev-tools \
+  ros-jazzy-rmw-fastrtps-cpp python3-colcon-common-extensions python3-rosdep
+```
+
+Инициализация `rosdep` выполняется один раз:
+
+```bash
+sudo rosdep init
+rosdep update
+```
+
+Если `rosdep init` пишет, что файл источников уже существует, повторять команду не нужно.
+
+```bash
+source /opt/ros/jazzy/setup.bash
+export RMW_IMPLEMENTATION=rmw_fastrtps_cpp
+ros2 --help
+```
+
+### Webots
+
+```bash
+sudo mkdir -p /etc/apt/keyrings
+sudo wget -q https://cyberbotics.com/Cyberbotics.asc \
+  -O /etc/apt/keyrings/Cyberbotics.asc
+echo "deb [arch=amd64 signed-by=/etc/apt/keyrings/Cyberbotics.asc] https://cyberbotics.com/debian binary-amd64/" \
+  | sudo tee /etc/apt/sources.list.d/Cyberbotics.list
+sudo apt update
+sudo apt install -y webots
+
+which webots
+readlink -f "$(command -v webots)"
+webots --version
+```
+
+Не задавайте `WEBOTS_HOME=/snap/webots/...` для APT-версии. Сначала проверьте реальный путь.
+
+### Пакеты симулятора и управления
+
+```bash
+mkdir -p ~/ros2_ws/src
+cd ~/ros2_ws/src
+
+git clone https://gitlab.mobird.dev/fms_group/ar_webots_fms_ros2.git
+git clone https://gitlab.mobird.dev/fms_group/ar_arm95_moveit_config.git
+git clone https://gitlab.mobird.dev/fms_group/ar_aruco_detect_ros2.git
+git clone https://gitlab.mobird.dev/fms_group/ar_dual_lidar_merge_ros2.git
+git clone https://gitlab.mobird.dev/fms_group/ar_nav_ros2.git
+
+cd ~/ros2_ws
+source /opt/ros/jazzy/setup.bash
+rosdep install --from-paths src -y --ignore-src --rosdistro jazzy
+colcon build --symlink-install
+source ~/ros2_ws/install/setup.bash
+```
+
+Если закрытый GitLab не открывается, это вопрос доступа организаторов. Не подменяйте пакеты случайными форками.
+
+Добавить окружение в Bash можно после успешной ручной проверки:
+
+```bash
+printf '%s\n' \
+  'source /opt/ros/jazzy/setup.bash' \
+  'source ~/ros2_ws/install/setup.bash' \
+  'export RMW_IMPLEMENTATION=rmw_fastrtps_cpp' \
+  >> ~/.bashrc
+```
+
+### Python, YOLO и ROS
+
+```bash
+cd ~/scripts/mvch/module3
+python3 -m venv --system-site-packages .venv
+.venv/bin/python -m pip install -U pip
+.venv/bin/pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu
+.venv/bin/pip install -r requirements.txt tqdm ultralytics-thop
+.venv/bin/pip install --force-reinstall \
+  "numpy<2" "opencv-python<4.12" lark transforms3d
+```
+
+Проверка:
+
+```bash
+source /opt/ros/jazzy/setup.bash
+source ~/ros2_ws/install/setup.bash
+~/scripts/mvch/module3/.venv/bin/python -c \
+  "import rclpy, cv_bridge, numpy, torch, ultralytics; print('Python/ROS/YOLO OK')"
+```
+
+CPU-сборки достаточно для запуска и короткой проверки. CUDA/ROCm устанавливайте только под фактическую видеокарту по официальному селектору PyTorch.
+
+### Bun и Node.js
+
+Для `module4` нужен Bun:
+
+```bash
+sudo apt install -y unzip
+curl -fsSL https://bun.com/install | bash
+export BUN_INSTALL="$HOME/.bun"
+export PATH="$BUN_INSTALL/bin:$PATH"
+bun --version
+
+cd ~/scripts/mvch/module4
+bun install
+bun run check
+bun run build
+```
+
+Node.js для этого проекта не обязателен, но полезен как запасной runtime и для npm-инструментов:
+
+```bash
+curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.7/install.sh | bash
+export NVM_DIR="$HOME/.nvm"
+[ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"
+nvm install --lts
+node --version
+npm --version
+```
+
+### OpenCode — только если разрешён и нужен
+
+Linux/Ubuntu:
+
+```bash
+curl -fsSL https://opencode.ai/install | bash
+opencode --version
+```
+
+Windows после установки Node.js:
+
+```powershell
+npm install -g opencode-ai
+opencode --version
+```
+
+Не записывайте API-ключи в репозитории, README или историю терминала. Способ авторизации выбирайте по правилам площадки.
+
+## День настройки физического оборудования
+
+Делайте проверки по слоям:
+
+1. `ip addr`, `ip route`, доступность адресов РМК.
+2. `ROS_DOMAIN_ID` и `RMW_IMPLEMENTATION` по данным эксперта.
+3. `ros2 topic list | sort` и `ros2 node list`.
+4. Отдельно проверить `/RMC1/odometry`, `/RMC2/odometry`, лидары, камеры и TF.
+5. На вывешенных колёсах кратко подать малую скорость и немедленно STOP.
+6. Проверить лифт RMC2 без стеллажа.
+7. Проверить ARM95 сначала без детали и на безопасной высоте.
+8. Собрать датасет только выданной/разрешённой камерой и сделать dry-run детектора.
+9. Зафиксировать реальные топики, фреймы, размеры, точки и параметры в отдельном локальном коммите.
+10. Сделать контрольный прогон и офлайн-бэкап.
+
+Не начинайте с полного модуля Д: сначала независимо подтвердите каждую платформу, лифт, камеру, детектор и манипулятор.
+
+## Защита от блокировки GitHub
+
+Основной вариант — зеркало на доступной Gitea. Дополнительно сделайте Git bundle обоих репозиториев:
+
+```bash
+mkdir -p ~/chvt-backup
+git -C ~/scripts/mvch bundle create ~/chvt-backup/mvch.bundle --all
+git -C ~/scripts/mvch-docs bundle create ~/chvt-backup/mvch-docs.bundle --all
+git bundle verify ~/chvt-backup/mvch.bundle
+git bundle verify ~/chvt-backup/mvch-docs.bundle
+```
+
+Проверка восстановления:
+
+```bash
+git clone ~/chvt-backup/mvch.bundle /tmp/mvch-restore-test
+git -C /tmp/mvch-restore-test log -1 --oneline
+```
+
+Bundle содержит историю Git и отслеживаемые веса модели, но не содержит `.venv`, `node_modules`, системные пакеты и секреты. На флешку отдельно сохраните установщик/образ Ubuntu, нужную версию Webots, экспорт датасета и при необходимости wheel/cache зависимостей.