Cop-Droid

Python · FastAPI · React · TypeScript · YOLOv8 · ESP32 · WebSocket · Docker

Description

An intelligent surveillance robot that combines ultrasonic sonar navigation with YOLOv8-based person detection. When a person is detected, configurable responses are triggered: signaling laser, siren alarm, or Telegram notification. Includes a real-time web dashboard for remote supervision.

Architecture

┌─────────────────────┐      WebSocket (JPEG frames)      ┌──────────────────┐
│   ESP32-CAM         │ ──────────────────────────────▶   │                  │
│   (Camera / WiFi)   │                                   │   CORE AI        │
│   firmware/cam/     │ ◀──────────────────────────────   │   (FastAPI)      │
└─────────────────────┘       "ok" acknowledgment         │   port 8000      │
                                                          │                  │
┌─────────────────────┐      WebSocket (keepalive)        │   • YOLOv8       │
│   ESP32 Engine      │ ──────────────────────────────▶   │   • MJPEG stream │
│   (Navigation)      │                                   │   • Laser ctrl   │
│   firmware/engine/  │ ◀──────────────────────────────   │   • Telegram bot │
└─────────────────────┘    "LASER_ON" / "LASER_OFF"       │   • Siren alarm  │
                                                          └────────┬─────────┘
                                                                   │
                                                    REST /devices   │   MJPEG /video/{id}
                                                                   │
                                                          ┌────────▼─────────┐
                                                          │   DASHBOARD      │
                                                          │   (React + Vite) │
                                                          │   port 5173      │
                                                          └──────────────────┘

Tech Stack

  • Backend: Python 3.12+, FastAPI, Uvicorn, YOLOv8 (Ultralytics), OpenCV
  • Frontend: React 18, TypeScript, Vite, Tailwind CSS v4
  • Firmware: C++ (Arduino Core), PlatformIO, ESP32-CAM (OV2640), HC-SR04, L298N
  • Infra: Docker, WebSockets, Telegram Bot API

Key Features

  • Autonomous Navigation — ultrasonic obstacle avoidance with configurable thresholds
  • Real-Time Detection — YOLOv8 inference on server-side from ESP32-CAM video feed
  • Active Responses — laser activation, siren alarm, Telegram notifications on person detection
  • Web Dashboard — live MJPEG stream, radar view, laser control, event log, device status

Operation Flow

ESP32-CAM sends JPEG frames via WebSocket to Core AI, which runs YOLOv8 inference. On person detection, it triggers configured actions and streams annotated frames. The ESP32 Engine runs an obstacle avoidance state machine while listening for laser commands. The dashboard polls device state and displays live video and event history.