Built for Raspberry Pi 5 — Zero Cloud, Zero Internet, Fully Autonomous
Features · Architecture · Quick Start · Hardware · API · Docs (PDF)
Employee walks in. Camera sees face. AI matches identity. Attendance logged. LED confirms.
All in under 50 milliseconds. All on a $80 computer. All without internet.
| Traditional Systems | PiFace360 |
|---|---|
| Need constant internet connectivity | 100% offline — runs on local hardware |
| Cost $5,000–$50,000 per location | ~$165 total — runs on a Raspberry Pi 5 |
| Require badges, fingerprints, or PINs | Contactless — walk past the camera |
| Send biometric data to the cloud | Privacy-first — data never leaves the device |
| Need IT infrastructure and maintenance | Self-contained — creates its own WiFi network |
| Take weeks to deploy | 15 minutes — one script, zero configuration |
| ~$165 | <50ms | >97% | 100% | 15 min |
|---|---|---|---|---|
| Total Hardware | Detection Latency | Recognition Accuracy | Offline Operation | Deploy Time |
- Real-time detection at ~15 FPS using InsightFace (ArcFace + SCRFD)
- 512-dimensional embeddings with cosine similarity matching
- Dual camera system — dedicated IN (entrance) and OUT (exit) cameras
- Multi-face tracking via Hungarian algorithm — handles crowds
- Unknown visitor detection — flags, stores, and allows later enrollment
- Configurable threshold — adjust sensitivity from the dashboard (default: 0.6)
- Automatic IN/OUT logging with timestamps and confidence scores
- Daily summaries — hours worked, breaks, overtime, late arrivals, early departures
- Manual corrections — admin can adjust entries when needed
- Historical search — filter by date, department, employee, event type
- Sortable columns — ascending/descending on any field
- Face enrollment via live webcam capture
- Department & role assignment with full CRUD operations
- Re-enrollment support — update face data without losing history
- Bulk seed data — 20-employee demo dataset for testing
- Leave types: Sick, Casual, Annual, Personal
- Calendar view with employee tags and reason notes on each day
- Holiday calendar — define company holidays, auto-mark as non-working
- Approval workflow with admin oversight
- Excel & PDF generation for daily and monthly reports
- Metrics include: attendance rate, hours worked, overtime, late count
- One-click download from the dashboard
- Real-time stats — present, absent, late, on-leave counts
- Dual camera feeds — side-by-side IN/OUT MJPEG streams
- Today's timeline — chronological event log with snapshots
- Attendance charts — visual breakdown via Recharts
- WiFi hotspot — Pi creates its own network, no router needed
- Captive portal — connected devices auto-redirect to dashboard
- LED indicators — green (entry confirmed), red (exit confirmed)
- GPIO-driven via gpiozero + lgpio (Pi 5 native)
- JWT authentication with configurable expiry
- CSRF protection — double-submit cookie pattern
- bcrypt password hashing with salted rounds
- Rate limiting on authentication endpoints
- HTTPS with self-signed TLS certificate
- iptables firewall — only ports 22, 80, 443 exposed
- Organized sections: General, Security, System, Danger Zone
- Company configuration — name, working hours, weekend days
- Face recognition tuning — confidence threshold, min face size
- Backup & restore — full database backup with one click
- Factory reset with password confirmation
- System status — CPU, memory, disk, temperature monitoring
┌─────────────────────────────────────────────┐
│ RASPBERRY PI 5 (8GB) │
│ │
│ ┌─────────────┐ ┌───────────────────┐ │
[USB Camera IN] ──┼──>│ │ │ FastAPI + React │ │
│ │ Face │ │ Backend + SPA │──┼──> HTTPS :443
[USB Camera OUT]──┼──>│ Engine │───>│ (Uvicorn) │ │ ──> Browser
│ │ │ │ │ │
│ │ InsightFace │ └────────┬───────────┘ │
│ │ ArcFace │ │ │
│ │ SCRFD │ ┌────┴────┐ │
│ └──────┬──────┘ │ SQLite │ │
│ │ │ (WAL) │ │
│ ┌──────┴──────┐ └─────────┘ │
[GPIO LEDs] ─┼──>│ LED │ │
│ │ Controller │ ┌───────────────────┐ │
│ └─────────────┘ │ Nginx + hostapd │ │
│ │ WiFi AP + Reverse │ │
│ │ Proxy + Captive │ │
│ └───────────────────┘ │
└─────────────────────────────────────────────┘
| Service | CPU Cores | Memory | Priority | Role |
|---|---|---|---|---|
piface-engine |
0–1 | 3 GB | -5 (highest) | Face recognition AI loop |
piface-web |
2 | 1 GB | -2 | Web server + API |
piface-leds |
3 | 512 MB | -2 | GPIO LED controller |
All three auto-start on boot and auto-restart on failure. CPU cores are pinned for performance isolation.
| Layer | Technology |
|---|---|
| AI | InsightFace 0.7.3 (ArcFace + SCRFD) + ONNX Runtime |
| Backend | Python 3.11, FastAPI, SQLAlchemy 2.0, SQLite WAL |
| Frontend | React 18, Vite 5, TailwindCSS 3, TanStack Query 5, Recharts |
| Streaming | MJPEG over HTTP, Server-Sent Events (SSE) |
| Hardware | gpiozero 2.0 + lgpio (Pi 5 native GPIO) |
| Camera | picamera2 (CSI) / OpenCV (USB) |
| Networking | hostapd + dnsmasq + Nginx |
| Security | JWT + CSRF + bcrypt + TLS + iptables |
| Process | systemd with CPU affinity and memory limits |
| Component | Specification | Cost |
|---|---|---|
| Raspberry Pi 5 | 8GB RAM | $80 |
| microSD Card | 64GB+ Class 10 / A2 | $12 |
| USB-C Power Supply | 27W (5.1V / 5A) official | $12 |
| USB Camera x2 | 1080p, USB 2.0/3.0 | $50 |
| LEDs + Resistors | Green, Red, 330ohm x2 | $2 |
| Case | Official Pi 5 case or 3D printed | $10 |
| Total | ~$165 |
GPIO 17 (Pin 11) ──── 330Ω ──── Green LED (+) ──── GND (Pin 9) ← Entry confirmed
GPIO 27 (Pin 13) ──── 330Ω ──── Red LED (+) ──── GND (Pin 14) ← Exit confirmed
┌──────────┐
Entrance ─────>│ Camera 1 │──── USB ────┐
└──────────┘ │
┌────┴────┐
│ RPi 5 │
└────┬────┘
┌──────────┐ │
Exit ─────────>│ Camera 2 │──── USB ────┘
└──────────┘
Cameras are assigned to IN/OUT roles via the web dashboard — no config files to edit.
Step 1 — Flash SD Card
Raspberry Pi Imager → Raspberry Pi OS (64-bit, Bookworm)
Enable SSH → Set username: pi → Set password
Step 2 — Install
ssh pi@raspberrypi.local
git clone https://github.com/SKULLFIRE07/PiFace360.git
cd PiFace360
sudo bash piface/setup/install.sh # ~15 minutes, fully automatedStep 3 — Use
1. Connect to WiFi: "AttendanceSystem"
2. Browser auto-opens (captive portal)
3. Login: admin / admin123
4. Setup wizard: company name → working hours → done
5. Cameras tab: assign IN and OUT cameras
6. Employees tab: enroll faces via webcam
7. Attendance is now automatic
# Backend
python3.11 -m venv venv && source venv/bin/activate
pip install -r piface/requirements.txt
python seed_data.py # 20 employees, 14 days of data
python -m uvicorn piface.backend.main:app --host 0.0.0.0 --port 8001 --reload
# Frontend (separate terminal)
cd piface/frontend && npm install
npx vite --port 5173 # proxies /api → :8001Open http://localhost:5173 → login: admin / admin123
┌──────────────┐ ┌────────────────────┐
│ Phone / │ WiFi 192.168.4.0/24 │ Raspberry Pi 5 │
│ Laptop / │◄────────────────────────────►│ 192.168.4.1 │
│ Tablet │ SSID: AttendanceSystem │ │
└──────────────┘ │ :443 HTTPS │
│ :80 → redirect │
Captive portal auto-redirects │ :22 SSH │
to https://192.168.4.1 └────────────────────┘
No router. No internet. No cloud. The Pi is the network.
All endpoints return a unified response envelope:
{ "success": true, "data": { ... }, "error": null }| Method | Endpoint | Description |
|---|---|---|
POST |
/api/auth/login |
Authenticate → JWT token |
POST |
/api/auth/logout |
Invalidate session |
GET |
/api/employees |
List employees (paginated) |
POST |
/api/employees |
Create + enroll face |
PUT |
/api/employees/{id} |
Update employee |
DELETE |
/api/employees/{id} |
Deactivate employee |
GET |
/api/attendance/events |
Query events (sort, filter) |
GET |
/api/attendance/today |
Today's summary |
POST |
/api/attendance/manual |
Manual entry/exit |
GET |
/api/unknowns |
Unknown face detections |
POST |
/api/unknowns/{id}/identify |
Assign unknown → employee |
GET |
/api/leave |
Leave records |
POST |
/api/leave |
Submit leave request |
GET |
/api/holidays |
Holiday calendar |
GET |
/api/reports/daily |
Generate daily report |
GET |
/api/reports/monthly |
Monthly report (Excel/PDF) |
GET |
/api/cameras |
Camera assignments |
GET |
/api/cameras/detect |
Scan connected cameras |
POST |
/api/cameras/assign |
Assign IN/OUT role |
GET |
/api/video?camera=in |
MJPEG live stream |
GET |
/api/settings |
System configuration |
PUT |
/api/settings |
Update settings |
GET |
/api/system/status |
Health (CPU, disk, temp) |
POST |
/api/system/backup |
Database backup |
Engine: SQLite 3 with WAL mode for concurrent read/write access.
| Table | Key Columns | Purpose |
|---|---|---|
Person |
name, employee_id, department, face_embedding (512-d), face_image | Employee records + biometric data |
AttendanceEvent |
person_id, event_type (IN/OUT), timestamp, confidence, snapshot | Individual attendance entries |
DailySummary |
person_id, date, first_in, last_out, hours_worked, status | Aggregated daily records |
LeaveRecord |
person_id, date, leave_type, note, approved_by | Leave management |
Holiday |
date, name | Company holidays |
AuthUser |
username, password_hash, role | Admin authentication |
SystemSetting |
key, value (JSON) | Configuration storage |
AuditLog |
user_id, action, entity_type, timestamp | Admin activity tracking |
PiFace360/
│
├── piface/
│ ├── backend/ # FastAPI REST API
│ │ ├── main.py # Application factory + middleware
│ │ ├── models.py # SQLAlchemy ORM (8 tables)
│ │ ├── schemas.py # Pydantic request/response models
│ │ ├── database.py # SQLite WAL engine + sessions
│ │ ├── security.py # JWT + CSRF + bcrypt + rate limiting
│ │ └── routes/ # 13 endpoint modules
│ │ ├── auth.py attendance.py employees.py
│ │ ├── leave.py holidays.py reports.py
│ │ ├── settings.py system.py backup.py
│ │ ├── stream.py unknowns.py calibration.py
│ │ └── setup.py
│ │
│ ├── frontend/ # React 18 SPA
│ │ └── src/
│ │ ├── pages/ # 10 lazy-loaded pages
│ │ ├── components/ # Reusable UI (Layout, LiveFeed, Dialogs)
│ │ ├── hooks/ # useAuth, useSSE
│ │ └── api/ # Axios client + response interceptor
│ │
│ ├── core/ # AI + Hardware Control
│ │ ├── face_engine.py # Recognition loop (InsightFace)
│ │ ├── camera.py # Capture (picamera2 / OpenCV)
│ │ ├── tracker.py # Multi-face tracking (Hungarian)
│ │ ├── preprocessing.py # Image processing pipeline
│ │ ├── led_controller.py # GPIO control (gpiozero + lgpio)
│ │ └── event_bus.py # IPC via Unix socket
│ │
│ ├── setup/ # Deployment Configuration
│ │ ├── install.sh # 20-step automated installer
│ │ ├── nginx.conf # Reverse proxy + captive portal
│ │ ├── hostapd.conf # WiFi access point
│ │ ├── dnsmasq.conf # DHCP server
│ │ ├── piface-engine.service # AI service (systemd)
│ │ ├── piface-web.service # Web service (systemd)
│ │ └── piface-leds.service # LED service (systemd)
│ │
│ └── requirements.txt # Python dependencies
│
├── seed_data.py # Demo data (20 employees, 14 days)
├── generate_pdf.py # Documentation PDF generator
├── PiFace360_Documentation.pdf # 18-page technical documentation
└── README.md
| Metric | Value |
|---|---|
| Face detection latency | ~50ms per frame |
| Recognition accuracy | >97% (buffalo_l model) |
| Processing throughput | ~15 FPS (full pipeline) |
| Embedding dimensions | 512 (float32, 2KB per face) |
| Max simultaneous faces | 20 (tracked concurrently) |
| Concurrent dashboard users | 10+ |
| Database capacity | 100K+ attendance events |
| Boot to operational | ~15 seconds |
| Idle power consumption | ~5W |
Full 18-page technical documentation available as PDF:
PiFace360_Documentation.pdf — Covers architecture, tech stack, hardware, features, database schema, API reference, AI engine, deployment, network topology, and security.
| Symptom | Fix |
|---|---|
| Camera not detected | ls /dev/video* — ensure USB camera is plugged in |
| Face not recognized | Lower similarity threshold in Settings (default 0.6) |
| WiFi hotspot not visible | sudo systemctl status hostapd |
| Dashboard not loading | sudo systemctl status piface-web |
| High CPU temperature | Check ventilation, vcgencmd measure_temp |
| Database locked error | sudo systemctl restart piface-web |
The install.sh script automates all 20 steps:
- System packages & updates
- WiFi hotspot (hostapd + dnsmasq)
- Static IP (192.168.4.1)
- Python venv + dependencies
- TLS certificate generation
- JWT secret generation
- Nginx reverse proxy + captive portal
- 3 systemd services installed & enabled
- iptables firewall configured
- Log rotation configured
- Boot optimizations (CPU governor, USB current, RTC)
- Filesystem optimization (noatime)
PiFace360 by 360