SocksTank: Finds Your Socks with YOLO, NCNN, and a Raspberry Pi Robot Tank

SocksTank is a browser-controlled Raspberry Pi robot that finds socks with YOLO model inference, runs locally with NCNN, and can switch to a remote GPU server when needed.

What you can do with it:

• drive the robot from the web panel with live video and telemetry
• run fast on-device inference on RPi 5 with NCNN
• switch to remote GPU inference when you want more throughput
• deploy and update the robot from one CLI workflow

Why it stands out:

• runs on Raspberry Pi 5 with real benchmarked NCNN performance
• includes a web control panel with live video, motors, servos, LEDs, and telemetry
• supports both local inference and remote GPU inference
• deploys to Raspberry Pi from a single CLI entrypoint

Built on top of Freenove Tank Robot Kit (PCB Version V1.0, but V2.0 is also supported). If you've already assembled the Freenove Tank, it's time for the next step — train your own model and run it on a Raspberry Pi.

Quick start:

1. Set up the hardware: RPi 5 setup
2. Prepare a dataset: dataset guide
3. Train and export the model: training guide
4. Launch and deploy the stack: launch guide

Demo:

• Ready for a future GIF/video drop-in:

![SocksTank demo](assets/demo.gif)

• Until the camera build is complete, this stays as a placeholder.

Highlights:

• English docs index
• Russian docs index
• Run and deploy
• Web control panel and inference modes
• RPi benchmark results

Architecture

Browser UI (React/Vite)
        |
        v
FastAPI backend (REST + WebSocket + static frontend)
        |
        +--> Camera + telemetry + hardware control
        |
        +--> Inference router
                |
                +--> Local PyTorch / NCNN on the host
                |
                +--> Remote GPU inference server over HTTP

• Frontend: React + Vite web panel for live video, controls, sensors, and inference mode management
• Backend: FastAPI app that serves the API, WebSocket telemetry, and the built frontend
• Inference: routing logic that switches between local .pt, local NCNN, and remote GPU backends
• Hardware: RPi integration layer for motors, servos, LEDs, and sensors

Documentation

Recommended path

1. RPi 5 setup (recommended)
2. Dataset guide
3. Training and model export
4. Run and deploy
5. Web control panel and inference modes

Build your model

• Capturing photos
• Uploading to Roboflow and annotation
• Augmentation
• Exporting the dataset
• Training (GPU, Apple Silicon, CPU)
• Evaluating results
• Model export (NCNN for RPi)

Run and operate

• Running the project
• Web control panel
• Deploying to RPi
• Remote GPU inference
• Integration with tank controls

Reference

• RPi 4 setup (legacy)
• RPi 5 power supply
• Inference benchmarks
• Disk benchmarks
• Infrastructure
• UI E2E test plan

CI and Testing

• Tests GitHub Actions workflow runs backend tests on push and pull_request.
• UI E2E GitHub Actions workflow runs Playwright UI tests on pull_request, nightly, and manual dispatch.
• On UI failures, Playwright artifacts are retained (trace, screenshot, video).

---

SocksTank — робот-танк на базе Raspberry Pi, который находит носки с помощью YOLO-инференса, управляется из веб-панели в браузере и может выполнять инференс как локально через NCNN, так и удалённо на GPU-сервере.

Что с ним можно делать:

• управлять роботом из веб-панели с живым видео и телеметрией
• запускать быстрый локальный инференс на RPi 5 через NCNN
• переключаться на удалённый GPU-инференс, когда нужен больший throughput
• деплоить и обновлять робота через единый CLI-сценарий

Чем проект интересен:

• работает на Raspberry Pi 5 с реальными замерами производительности NCNN
• включает веб-панель управления с живым видео, моторами, сервоприводами, LED и телеметрией
• поддерживает как локальный инференс, так и удалённый GPU-инференс
• деплоится на Raspberry Pi через единый CLI entrypoint

Построен поверх Freenove Tank Robot Kit (PCB Version V1.0, но поддерживается и V2.0). Если вы уже собрали Freenove Tank, самое время перейти к следующему этапу — обучить собственную модель и запустить её на Raspberry Pi.

Быстрый старт:

1. Подготовить железо: настройка RPi 5
2. Подготовить датасет: гайд по датасету
3. Обучить и экспортировать модель: гайд по обучению
4. Запустить и задеплоить проект: гайд по запуску

Демо:

• Блок уже подготовлен под будущее demo video/GIF:

![SocksTank demo](assets/demo.gif)

• Пока сборка камеры не завершена, это placeholder.

Ключевые ссылки:

• Индекс английской доки
• Индекс русской доки
• Запуск и деплой
• Веб-панель и режимы инференса
• Замеры на RPi

Архитектура

Browser UI (React/Vite)
        |
        v
FastAPI backend (REST + WebSocket + built frontend)
        |
        +--> Camera + telemetry + hardware control
        |
        +--> Inference router
                |
                +--> Local PyTorch / NCNN on the host
                |
                +--> Remote GPU inference server over HTTP

• Frontend: React + Vite веб-панель для живого видео, управления, сенсоров и выбора режима инференса
• Backend: FastAPI-приложение, которое обслуживает API, WebSocket-телеметрию и собранный фронтенд
• Inference: маршрутизация инференса, которая переключает между локальным .pt, локальным NCNN и удалённым GPU backend
• Hardware: слой интеграции с RPi для моторов, сервоприводов, LED и сенсоров

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

Рекомендуемый путь

1. Настройка RPi 5 (рекомендуется)
2. Гайд по датасету
3. Тренировка и экспорт модели
4. Запуск и деплой
5. Веб-панель и режимы инференса

Подготовка модели

• Съёмка фотографий
• Загрузка в Roboflow и аннотирование
• Аугментация
• Экспорт датасета
• Тренировка (GPU, Apple Silicon, CPU)
• Оценка результатов
• Экспорт модели (NCNN для RPi)

Запуск и эксплуатация

• Запуск проекта
• Веб-панель управления
• Деплой на RPi
• Удалённый GPU-инференс
• Интеграция с управлением танком

Справка

• Настройка RPi 4 (legacy)
• Питание RPi 5
• Бенчмарки инференса
• Бенчмарки диска
• Инфраструктура

---

Co-authors

• Mikhail Andreev (adw0rd)
• Claude Code
• OpenAI Codex