mavxa/chvt-docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

init

Browse Source
This commit is contained in:
mavxa
2026-09-09 16:28:02 +03:00
commit f48465dfb1
36 changed files with 3580 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
setup/COMMANDS.md
+215
View File
@@ -0,0 +1,215 @@
# Команды установки
Краткая шпаргалка без пояснений. Подробности и ограничения: [`FROM_ZERO.md`](FROM_ZERO.md).
## 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
git --version
code --version
node --version
npm --version
wsl --install -d Ubuntu-24.04
```
## VS Code extensions
```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
code --install-extension ms-vscode-remote.remote-wsl
code --install-extension ms-vscode-remote.remote-ssh
```
## Ubuntu 24.04: база и VS Code
```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
sudo snap install --classic code
git --version
python3 --version
code --version
glxinfo -B
```
## Git и SSH
```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
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
git -C ~/scripts/mvch remote add gitea ssh://git@GITEA_HOST/USER/mvch.git
git -C ~/scripts/mvch push gitea --all
git -C ~/scripts/mvch push gitea --tags
git -C ~/scripts/mvch-docs remote add gitea ssh://git@GITEA_HOST/USER/mvch-docs.git
git -C ~/scripts/mvch-docs push gitea --all
git -C ~/scripts/mvch-docs push gitea --tags
```
## 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
sudo rosdep init
rosdep update
source /opt/ros/jazzy/setup.bash
export RMW_IMPLEMENTATION=rmw_fastrtps_cpp
```
## 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
```
## ROS-пакеты ЧВТ
```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
```
## Python/YOLO
```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
source /opt/ros/jazzy/setup.bash
source ~/ros2_ws/install/setup.bash
.venv/bin/python -c \
"import rclpy, cv_bridge, numpy, torch, ultralytics; print('Python/ROS/YOLO OK')"
```
## Bun, module4 и Node.js
```bash
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
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 (необязательно)
Ubuntu/Linux:
```bash
curl -fsSL https://opencode.ai/install | bash
source ~/.bashrc
opencode --version
```
Windows PowerShell:
```powershell
npm install -g opencode-ai
opencode --version
```
## Проверка окружения и топиков
```bash
cd ~/scripts/mvch-docs
./setup/check_environment.sh
source /opt/ros/jazzy/setup.bash
source ~/ros2_ws/install/setup.bash
export RMW_IMPLEMENTATION=rmw_fastrtps_cpp
ros2 node list
ros2 topic list | sort
ros2 topic echo /RMC1/odometry --once
ros2 topic echo /RMC2/odometry --once
ros2 topic echo /RMC2/scan_front --once
```
## 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
```
setup/FROM_ZERO.md
+327
View File
@@ -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 зависимостей.
setup/check_environment.sh
Executable
+87
View File
@@ -0,0 +1,87 @@
#!/usr/bin/env bash
set -u
warnings=0
check_command() {
if command -v "$1" >/dev/null 2>&1; then
printf '[OK] %s: %s\n' "$1" "$(command -v "$1")"
else
printf '[WARN] команда %s не найдена\n' "$1"
warnings=$((warnings + 1))
fi
}
if [[ -r /etc/os-release ]]; then
# shellcheck disable=SC1091
source /etc/os-release
printf '[INFO] OS: %s %s\n' "${NAME:-unknown}" "${VERSION_ID:-unknown}"
if [[ "${ID:-}" == ubuntu && "${VERSION_ID:-}" == 24.04 ]]; then
:
else
printf '[WARN] официальное окружение задания рассчитано на Ubuntu 24.04\n'
warnings=$((warnings + 1))
fi
fi
for command_name in git python3 code ros2 colcon webots bun; do
check_command "$command_name"
done
for optional_name in node npm opencode; do
if command -v "$optional_name" >/dev/null 2>&1; then
printf '[OK] необязательная команда %s: %s\n' "$optional_name" "$(command -v "$optional_name")"
else
printf '[INFO] необязательная команда %s не установлена\n' "$optional_name"
fi
done
printf '[INFO] RMW_IMPLEMENTATION=%s\n' "${RMW_IMPLEMENTATION:-не задано}"
printf '[INFO] ROS_DOMAIN_ID=%s\n' "${ROS_DOMAIN_ID:-не задано}"
if [[ -r /opt/ros/jazzy/setup.bash ]]; then
set +u
# shellcheck disable=SC1091
source /opt/ros/jazzy/setup.bash
set -u
printf '[OK] ROS 2 Jazzy setup найден\n'
else
printf '[WARN] /opt/ros/jazzy/setup.bash не найден\n'
warnings=$((warnings + 1))
fi
workspace_path="${ROS_WORKSPACE:-$HOME/ros2_ws}"
if [[ -r "$workspace_path/install/setup.bash" ]]; then
set +u
# shellcheck disable=SC1090
source "$workspace_path/install/setup.bash"
set -u
printf '[OK] workspace: %s\n' "$workspace_path"
else
printf '[WARN] workspace не собран: %s\n' "$workspace_path"
warnings=$((warnings + 1))
fi
if command -v ros2 >/dev/null 2>&1; then
for package_name in ar_webots_fms_ros2 ar_arm95_moveit_config ar_aruco_detect_ros2; do
if ros2 pkg prefix "$package_name" >/dev/null 2>&1; then
printf '[OK] ROS-пакет: %s\n' "$package_name"
else
printf '[WARN] ROS-пакет не найден: %s\n' "$package_name"
warnings=$((warnings + 1))
fi
done
fi
if python3 -c 'import rclpy, cv_bridge' >/dev/null 2>&1; then
printf '[OK] Python: rclpy и cv_bridge импортируются\n'
else
printf '[WARN] Python не импортирует rclpy/cv_bridge\n'
warnings=$((warnings + 1))
fi
if command -v glxinfo >/dev/null 2>&1; then
glxinfo -B 2>/dev/null | sed -n '/OpenGL vendor/p;/OpenGL renderer/p'
fi
printf '\nИтог: %d предупреждений. WARN не всегда означает поломку, но проверьте его до заезда.\n' "$warnings"