README.md

SocksTank

🇬🇧 English version

SocksTank — робот-танк на базе Raspberry Pi 5 (ранее RPi 4B, legacy), который ищет носки по квартире с помощью компьютерного зрения (YOLO) и собирает их клешнёй. Включает веб-панель управления с живым видео и телеметрией.

Построен поверх Freenove Tank Robot Kit (PCB Version V1.0, но поддерживается и V2.0).

Что нужно для старта

Железо

• Raspberry Pi 5 (рекомендуется) или RPi 4B (legacy), с блоком питания и SD-картой (32 ГБ+)
• Freenove Tank Robot Kit (GitHub), PCB Version V1.0
  
• Камера ov5647 (OmniVision, входит в комплект Freenove)
• GPU-сервер для тренировки модели (NVIDIA, или Apple Silicon, или облако)

Софт

• Python 3.10+
• ultralytics (YOLOv8/v11)
• Roboflow — для разметки датасета (бесплатный тариф)

Quick Start

1. Собрать танк — Freenove Tank Robot Kit (инструкция в комплекте)
2. Настроить Raspberry Pi — RPi 4 (легаси) или RPi 5 (рекомендуется)
3. Собрать датасет — dataset.md
4. Обучить модель — training.md
5. Запустить и задеплоить проект — launch.md
6. Запустить детекцию и веб-управление — inference.md

Структура проекта

main.py              # CLI точка входа (typer): train, bench, detect, shot, serve
server/              # FastAPI backend (веб-панель управления)
frontend/            # Vite + React + TypeScript (веб-панель)
models/              # Обученные модели YOLO
├── yolo11_best_ncnn_model/  # YOLOv11n NCNN FP32 (RPi продакшен, 14.9 FPS)
├── yolo11_best.pt           # YOLOv11n PyTorch (GPU, разработка)
└── yolo8_best.pt            # YOLOv8n PyTorch (старая модель)
legacy/              # Старые скрипты (bench, camera_detect, camera_shot, train)
data.yaml            # Конфиг датасета (1 класс: sock, Roboflow v2, 961 изображение)
dataset/             # Приватный датасет (train/valid/test) [.gitignore]
pyproject.toml       # Зависимости проекта (uv/pip)
docs/
├── ru/              # Документация (на русском)
└── en/              # Documentation (English)
assets/              # Изображения проекта

CLI-команды (main.py)

# Веб-панель управления (macOS, mock-режим)
./main.py serve --mock

# Веб-панель управления (RPi, реальное железо)
sudo -E python3 main.py serve --model models/yolo11_best_ncnn_model --conf 0.5

# Тренировка модели (на GPU-сервере или dev-машине)
./main.py train --device 0 --epochs 100

# Бенчмарк модели
./main.py bench

# Детекция носков с камеры RPi (legacy)
sudo -E python3 main.py detect --model models/yolo11_best_ncnn_model --conf 0.5

# Сбор фото для датасета
sudo -E python3 main.py shot --count 200 --output-dir images

Установка

# Dev-машина (macOS / Linux)
uv venv && uv pip install -e .
cd frontend && npm install && npm run build

# Raspberry Pi
sudo pip install . --break-system-packages

Документация

• Запуск проекта — сборка фронтенда, запуск бэкенда, деплой на RPi
• Настройка Raspberry Pi
  • Настройка RPi 4 (legacy)
  • Настройка RPi 5 (рекомендуется)
  • Питание RPi 5
• Подготовка датасета
  • Съёмка фотографий
  • Загрузка в Roboflow и аннотирование
  • Аугментация
  • Экспорт датасета
• Тренировка модели
  • Тренировка (GPU, Apple Silicon, CPU)
  • Оценка результатов
  • Экспорт модели (ncnn для RPi)
• Инференс и веб-панель
  • Веб-панель управления
  • Деплой на RPi
  • Удалённый GPU-инференс
  • Интеграция с управлением танком
• Бенчмарки
  • Бенчмарки инференса
  • Бенчмарки диска
• Тестирование и качество
  • План UI E2E тестов и покрытие
  • GitHub Actions workflow: Tests (backend) и UI E2E (Playwright)
• Инфраструктура

---

← Предыдущая	README	Следующая →
—	Вернуться к README	Инфраструктура