vixy-vision/server

vixy-vision Server

Camera snapshot server with motion detection for Raspberry Pi.

Quick Start (Single Camera)

cp env.example .env
nano .env  # Configure settings
./setup.sh
sudo systemctl start vixy-vision-<your-camera-id>

Multi-Camera Deployment (Same Pi)

For running multiple cameras on one Pi, clone the repo into separate directories:

# Camera 1: desk
git clone http://gateway.local:3001/vixy/vixy-vision.git ~/vixy-vision-desk
cd ~/vixy-vision-desk/server
cp env.example .env
# Edit .env:
#   SERVICE_NAME=vixy-vision-desk
#   CAMERA_ID=desk
#   CAMERA_INDEX=0
#   PORT=8443
./setup.sh

# Camera 2: basement
git clone http://gateway.local:3001/vixy/vixy-vision.git ~/vixy-vision-basement
cd ~/vixy-vision-basement/server
cp env.example .env
# Edit .env:
#   SERVICE_NAME=vixy-vision-basement
#   CAMERA_ID=basement
#   CAMERA_INDEX=2
#   PORT=8444
./setup.sh

Each instance gets its own:

• Install directory: ~/vixy-vision-<service-name>/
• Systemd service: vixy-vision-<service-name>.service
• Port: as configured in .env

Features

• 📷 USB camera snapshots via HTTPS API
• 🔐 API key authentication
• 🔍 Motion detection with frame differencing
• 📤 Event reporting to central collector
• 🔄 Auto-reconnect on camera failure
• 🔢 Multi-instance support via SERVICE_NAME and PORT

Configuration

Copy env.example to .env and customize:

Variable	Description	Default
API_KEY	Auth key for API	(generated)
SERVICE_NAME	Systemd service name	vixy-vision
PORT	HTTPS port	8443
CAMERA_ID	Identifier for this camera	camera
CAMERA_INDEX	/dev/videoN index	0
MOTION_ENABLED	Enable motion detection	true
MOTION_THRESHOLD	Sensitivity (lower = more)	25
MOTION_COOLDOWN	Seconds between events	5.0
COLLECTOR_URL	Where to POST events	(optional)

API Endpoints

Endpoint	Auth	Description
GET /	No	Service info
GET /health	No	Health check
GET /snapshot	Yes	JPEG snapshot
GET /motion/stats	Yes	Detection stats
POST /motion/enable	Yes	Start detection
POST /motion/disable	Yes	Stop detection

Motion Events

When motion is detected, the server POSTs to COLLECTOR_URL:

{
  "event": {
    "timestamp": "2024-12-16T14:23:01Z",
    "camera_id": "basement",
    "event_type": "motion",
    "confidence": 0.75,
    "area_percent": 7.5
  },
  "snapshot": "<base64 JPEG>"
}

Service Management

sudo systemctl start vixy-vision-<id>
sudo systemctl stop vixy-vision-<id>
sudo systemctl status vixy-vision-<id>
sudo journalctl -u vixy-vision-<id> -f