🎮 Arcade Tracker v1.0

A comprehensive arcade management system for tracking games, play statistics, revenue, and maintenance with advanced work logging capabilities and real-time skeeball integration.

🌟 Features

Game Management

Game Inventory: Track arcade games with detailed information (manufacturer, year, genre)
Location Tracking: Monitor game locations (Floor, Warehouse, Shipped) with specific positions
Status Management: Track game status (Working, Being Fixed, Not Working, Retired)
Image Support: Upload and display cabinet photos
Revenue Analytics: Automatic play and revenue calculation from coin counts

🆕 Advanced Maintenance System

Work Order Management

Create Work Orders: Report issues with detailed descriptions
Status Tracking: Open, In Progress, Fixed, Deferred status management
Technician Assignment: Assign work orders to specific technicians

🔧 Timestamped Work Logging (New!)

Individual Work Entries: Each update creates a new timestamped work log entry
Detailed Work History: Complete audit trail of all work performed
Work Session Tracking:
- Work description with detailed notes
- Time spent per work session (hours)
- Parts/materials used per session
- Cost breakdown per work session
- Technician attribution per entry

Visual Work Timeline

Chronological Display: Work entries shown in timeline format with timestamps
Color-coded Information: Different colors for timestamps, technicians, time, and costs
Comprehensive Details: Full work descriptions, parts used, and session costs
Professional Layout: Clean, organized presentation of work history

Enhanced Reporting

Time-filtered Reports: View maintenance data for 7, 30, 90 days or full year
📋 PDF Reports with Work Logs: Professional reports including detailed work history
CSV Export: Export game data for external analysis
Performance Analytics: Top/worst performing games with charts and graphs

👥 User Roles & Permissions

Read Only (Level 1)

View game information and statistics
View maintenance reports
Basic dashboard access

Operator (Level 2)

All Read Only permissions
Log work entries in maintenance orders
View detailed work order history
Create maintenance requests

Manager (Level 3)

All Operator permissions
Update and manage work orders
Record play data and revenue
Add and edit games
Access complete work logging system
Generate and export reports

Admin (Level 4)

All Manager permissions
User management (create, disable users)
Database backups and restoration
Delete games and associated data

🔧 New Work Logging Workflow

For Technicians/Operators:

Access maintenance order via "👁️ View" or "✏️ Update" button
Fill out work performed during session:
- Work Description: Detailed notes of what was done
- Parts Used: Materials consumed during this session
- Time Spent: Hours worked (e.g., 2.5 hours)
- Session Cost: Cost incurred for this specific work
Click "📋 Log Work Entry"
New timestamped entry is created and added to work history

For Managers:

View complete work history via "👁️ View" button
See chronological timeline of all work performed
Track total time and costs across all work sessions
Export detailed reports with work summaries
Update overall order status and assignments

🚀 Quick Start

Run the application:
```
python app.py
```
Access the app:
- Open your web browser and go to: http://localhost:5000
- Complete initial admin setup
- The database will be created automatically on first run

Manual Setup (Alternative)

If you prefer to set up manually:

cd arcade-tracker
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
python app.py

🎳 Skeeball Integration

Arcade Tracker includes a complete Raspberry Pi-based skeeball scoring system with automatic scoring, real-time revenue tracking, and scalable multi-lane architecture.

🌟 Key Features

Automatic Scoring System

7-Sensor Configuration: Coin input + ball counter + 5 scoring holes
- Score 10: 5 switches (10 points each)
- Score 50: 2 switches (50 points each)
- Lane Track: Ball roll detection (50 points)
Infrared Sensors: Break-beam detection for accurate, reliable scoring
Debounce Logic: Prevents double-counting from sensor bounce (configurable)
Real-time Score Display: Instant feedback on each ball scored

Game Management

9-Ball Standard Games: Traditional skeeball format
Bonus Games: Automatic bonus game awards at configurable thresholds
Ball Timeout: Configurable timeout between balls (prevents stuck games)
Coin Integration: Start games via coin acceptor or manual trigger
Persistent State: Game state survives power loss and restarts
Revenue Reconciliation: Daily automated revenue sync with Arcade Tracker database

Multi-Lane Architecture

Single Lane Mode: Raspberry Pi 4 connected directly to one machine
Multi-Lane Mode: Unlimited scalability
- Pi 4 acts as coordinator running Arcade Tracker
- One Raspberry Pi Pico per skeeball lane
- USB serial communication between Pi 4 and Picos
- Independent lane operation (isolated failures)
- Simplified wiring per machine

Web Interface & APIs

Main Hub (/skeeball/): Overview, lane selection, and navigation
Control Panel (/skeeball/control): Real-time game monitoring with 0.5-second updates
- Live score tracking during active gameplay
- Ball counter showing remaining balls
- Game active status (playing/ready/offline)
- Instant feedback on coin insertions
Simulator (/skeeball/simulator): Full gameplay testing without GPIO hardware
Statistics (/skeeball/stats): Live revenue analytics with 1-second updates
- Total coins inserted (cumulative)
- Total games played
- Real-time revenue tracking
GPIO Testing (/skeeball/gpio-test): Real-time hardware diagnostics and sensor monitoring
RESTful API: Authenticated endpoints for programmatic control and monitoring

🛠️ Hardware Requirements

Minimum Setup (Single Lane)

Raspberry Pi (any model with GPIO - Pi 4 recommended)
MicroSD Card: 16GB+ recommended
Power Supply: Appropriate for Pi model (Pi 4: 5V 3A USB-C)
Coin Acceptor: Standard arcade coin mechanism or pushbutton
Ball Counter Sensor: Detects balls entering play area
Scoring Sensors: 7 infrared break-beam sensors
- 5 for 10-point holes
- 2 for 50-point holes
- 1 for lane track (roll-down)
Wiring: Breadboard, jumper wires, pull-up resistors (if not built into sensors)

Optional Components

TM1637 Display: 4-digit 7-segment display for on-machine score display
Raspberry Pi Pico: For multi-lane setups (one per lane)
USB Cables: For Pi Pico ↔ Pi 4 communication
Relay Modules: For solenoid control (ball release) and LED power management

Default GPIO Pin Assignments (BCM Numbering)

Coin Input:       GPIO 2
Ball Counter:     GPIO 3
Score 10 (5x):    GPIO 4, 5, 6, 7, 8
Score 50 (2x):    GPIO 9, 10
Lane Track:       GPIO 11
Solenoid Relay:   GPIO 10 (output)
LED Power Relay:  GPIO 26 (output)

🚀 Quick Start Guide

1. Installation

The skeeball system is integrated into Arcade Tracker. Dependencies are installed automatically:

source venv/bin/activate
pip install -r requirements.txt

2. Development Testing (No Hardware Required)

# Start Arcade Tracker
python app.py

# Navigate to simulator
open http://localhost:5000/skeeball/simulator

# Test game logic by clicking buttons:
# - Insert Coin → Start Game
# - Score buttons → Simulate scoring
# - Watch game state and revenue tracking

3. Hardware Setup

Wire sensors to GPIO pins (see pin assignments above)
Configure settings in /skeeball/control
Test sensors at /skeeball/gpio-test
- Monitor real-time pin states
- Trigger each sensor to verify connections
- Check debounce behavior
Launch games from /skeeball/control

4. Production Deployment

See DEPLOYMENT_CHECKLIST.md for comprehensive deployment instructions including:

Sensor wiring diagrams
Pi Pico firmware setup (multi-lane)
Production configuration
Troubleshooting guide

📊 Revenue Integration

Automatic Revenue Tracking

Per-Game Revenue: Each coin insertion tracked with timestamp
Daily Reconciliation: Automated daily sync at midnight
Database Integration: Revenue stored in Arcade Tracker's play_records table
Statistics Dashboard: Real-time revenue analytics per lane
CSV Export: Revenue data exportable with all other game data

🔄 Real-Time State Synchronization

Live Game State Tracking: Control panel displays current score, balls remaining, and active game status
File-Based State Sharing: Raspberry Pi writes game state to JSON file every second
Stats API Server: Flask API on Pi (port 5002) serves real-time data to main application
Fast Polling: Control panel updates every 0.5 seconds, statistics every 1 second
Seamless Integration: Works with existing skeeball_main.py without GPIO conflicts

Data Flow:

Hardware (GPIO sensors) → skeeball_main.py → skeeball_state.json
  → state_sync.py (watches file) → realtime_state.json
  → stats_api_server.py (HTTP API) → Flask app → Web UI

Revenue Workflow

Player inserts coin → Revenue logged to lane controller
Game completes → Final score and revenue stored
Daily scheduler (midnight) → Sync all lane revenue to database
Arcade Tracker reports → Include skeeball revenue in analytics

🔧 Configuration

All configuration is done via Python config files:

config.py: GPIO pin assignments, point values, game parameters
.env.skeeball: Environment-specific settings (production vs development)
Web Interface: Runtime configuration via control panel

📚 Documentation

Comprehensive documentation included:

SKEEBALL_INTEGRATION_SUMMARY.md: Integration overview and verification
DEPLOYMENT_CHECKLIST.md: Step-by-step production deployment
FLASK_INTEGRATION.md: Technical integration details
MULTI_LANE_ARCHITECTURE.md: Multi-lane system architecture
GPIO_TESTING_README.md: Hardware testing and troubleshooting
SKEEBALL_TROUBLESHOOTING.md: Common issues and solutions

🔐 Security

All skeeball features protected by:

Flask-Login: Authentication required for all endpoints
CSRF Protection: All forms secured via Flask-WTF
Role-Based Access: Same permission model as main Arcade Tracker
API Authentication: All API endpoints require valid session

🎯 Use Cases

Arcade Operators: Automated revenue tracking without manual coin counting
Family Entertainment Centers: Multi-lane management from single interface
Developers: Test game logic with simulator before hardware deployment
Technicians: Hardware diagnostics and sensor testing tools
Managers: Real-time performance analytics and revenue reports

Usage

Adding Games

Click "Add Game" in the navigation
Fill in the game details (only name is required)
Set the status: Active, Maintenance, or Storage

Recording Plays

From the dashboard or games list, click "Record Plays" for any game
Enter the number of plays you read from the machine
Set the date (defaults to today)
Add any notes if needed

Viewing Reports

Click "Reports" to see:
- Top 10 games by total plays
- Daily play counts for the last 30 days
- Summary statistics

Database

The app uses SQLite database stored in arcade.db. Your data is stored locally and persists between sessions.

Customization Ideas

This basic version can be extended with:

Revenue tracking: Add coin/revenue data per play session
Maintenance logs: Track repairs and maintenance activities
Photo uploads: Add images of games
Export data: CSV/Excel export functionality
User accounts: Multi-user support with different access levels
Mobile app: Responsive design or native mobile app
Backup system: Automated data backups
Advanced reports: Charts, graphs, and trend analysis

🎉 Version 1.0 Release

Core Features

✅ Complete game inventory management with location tracking
✅ Revenue and play tracking with automatic calculations
✅ Advanced maintenance system with timestamped work logs
✅ Inventory management with low stock alerts
✅ Role-based access control (readonly, operator, manager, admin)
✅ Professional PDF reports and CSV exports
✅ Database backup and restore with encryption
✅ Automated daily backups with cron job setup
✅ Real-time skeeball integration with live scoring
✅ Responsive cyberpunk-themed UI

Daily Automated Backups

New in 1.0! Set up automated daily backups at 2 AM:

./scripts/setup_daily_backup.sh

Backs up database automatically every day
Removes backups older than 30 days
Logs all activity to logs/backup.log

Real-Time Skeeball Integration

New in 1.0! Live game state updates:

Control panel updates every 0.5 seconds showing current score, balls remaining, game status
Statistics page updates every 1 second with cumulative totals and best scores
State synchronization from Raspberry Pi hardware to web interface
No page refresh needed - see scores update as you play!

📈 Recent Updates (v1.0)

🎯 Monthly Performance Tracking

Monthly Top 5/Top 10 Rankings: Automatic monthly updates on the 1st of each month
Historical Performance Counters: Track how many times games rank in top 5 and top 10
Previous Month Revenue: Rankings based on prior month's total revenue
Smart Update Logic: Updates at most once per calendar month, preventing double-counting

📊 Executive Summary Dashboard

Revenue Overview: Total 30-day revenue with Top 5 and Bottom 3 games at a glance
Inventory Status: Real-time low stock alerts and pending request tracking
Maintenance Dashboard: Active work orders with priority and status indicators
Actionable Insights: Quick links to games, orders, and inventory items

🔧 Technical Improvements

Multi-Photo Upload Fix: Resolved duplicate file input causing upload issues
30-Day Login Persistence: Fixed "Remember Me" functionality for extended sessions
Clean Interface: Removed all emoji characters for consistent cross-platform rendering
Database Migration: Added last_ranking_update field for tracking monthly updates

🔧 Work Logging System

New WorkLog Database Table: Stores individual work entries with timestamps
Enhanced Update Process: Each update creates new work entry instead of overwriting
Complete Audit Trail: Full history of who did what work and when
Visual Timeline Interface: Professional timeline view of all work performed

🎨 UI/UX Improvements

Consistent Button Styling: Maintenance tables now match games table formatting
Smaller, Organized Buttons: Professional compact button layout
Enhanced Visual Hierarchy: Better organization of information

📋 Reporting Enhancements

PDF Format Fixes: Eliminated text cutoff issues with proper column sizing
Work History Integration: Reports now include actual work performed
Professional Layout: Improved fonts, spacing, and organization

🔒 Security & Performance

CSRF Protection: All forms now properly secured
Database Optimization: Efficient queries and relationships
User Role Management: Hierarchical permission system

🛠️ Technical Architecture

Database Schema

games: Game inventory and statistics
play_records: Revenue and play tracking
maintenance_records: Work order management
work_logs: 🆕 Individual work entries with timestamps
users: User management and authentication

Key Technologies

Backend: Flask, SQLAlchemy, Flask-Login
Frontend: Jinja2 templates with custom CSS
Security: Flask-WTF with CSRF protection
Reports: ReportLab for PDF generation
Charts: Chart.js for analytics visualization

File Structure

arcade-tracker/
├── app.py              # Main application
├── requirements.txt    # Python dependencies
├── run.sh             # Startup script
├── arcade.db          # SQLite database (created on first run)
├── templates/         # HTML templates
│   ├── base.html
│   ├── index.html
│   ├── games.html
│   ├── add_game.html
│   ├── game_detail.html
│   ├── record_plays.html
│   └── reports.html
└── README.md          # This file

🎯 Use Cases

Arcade Operators

Track which games make the most money
Monitor maintenance costs and frequency
Document detailed repair work with timestamps
Generate reports for business decisions

Maintenance Technicians

Log detailed work entries with time tracking
Record parts used and costs per work session
Build comprehensive work history for each machine
Track repair trends and recurring issues

Business Management

View complete maintenance audit trails
Analyze repair costs and technician productivity
Export professional reports with work details
Make data-driven decisions about game lifecycle

🔧 Database Migration

If upgrading from an older version, run:

python create_work_log_table.py

This will add the new WorkLog table for timestamped work entries.

🚀 Getting Started

First Time Setup: Navigate to the setup page to create your admin account
Add Games: Start by adding your arcade games to the inventory
Create Users: Set up accounts for technicians and operators
Start Tracking: Begin logging plays and maintenance work!

📋 Key Features Summary

✅ Complete Game Inventory Management ✅ Revenue & Play Tracking with Analytics ✅ Professional Work Order System ✅ Timestamped Work Logging with Audit Trail ✅ Visual Work Timeline Interface ✅ Role-based User Management ✅ Professional PDF Reports ✅ Secure CSRF-Protected Forms ✅ Database Backup & Restore

🎮 Keep your arcade running smoothly with comprehensive tracking and professional work documentation! 🔧

Name		Name	Last commit message	Last commit date
Latest commit History 80 Commits
.github		.github
app		app
arcade-tracker		arcade-tracker
arcade-tracker.wiki		arcade-tracker.wiki
migrations		migrations
rpi_skeeball		rpi_skeeball
scripts		scripts
skeeball		skeeball
static		static
templates		templates
venv		venv
.dockerignore		.dockerignore
.env.example		.env.example
.env.skeeball		.env.skeeball
.gitignore		.gitignore
.nextcloudsync.log		.nextcloudsync.log
.sync_f9470274f8a5.db-shm		.sync_f9470274f8a5.db-shm
.sync_f9470274f8a5.db-wal		.sync_f9470274f8a5.db-wal
ARCADE_TRACKER_DOCS.md		ARCADE_TRACKER_DOCS.md
ARCADE_TRACKER_DOCUMENTATION.pdf		ARCADE_TRACKER_DOCUMENTATION.pdf
AUTHENTICATION.md		AUTHENTICATION.md
Arcade_Tracker_Documentation.pdf		Arcade_Tracker_Documentation.pdf
BACKUP_SYSTEM.md		BACKUP_SYSTEM.md
BRANCHES.md		BRANCHES.md
CHANGELOG.md		CHANGELOG.md
CHANGES_SUMMARY.md		CHANGES_SUMMARY.md
CLOUD_SETUP.md		CLOUD_SETUP.md
DEPLOYMENT.md		DEPLOYMENT.md
DEPLOYMENT_CHECKLIST.md		DEPLOYMENT_CHECKLIST.md
Dockerfile		Dockerfile
FLASK_INTEGRATION.md		FLASK_INTEGRATION.md
FLASK_READY.md		FLASK_READY.md
GPIO_TESTING_README.md		GPIO_TESTING_README.md
MOCK_GPIO_SETUP_COMPLETE.md		MOCK_GPIO_SETUP_COMPLETE.md
MULTI_LANE_ARCHITECTURE.md		MULTI_LANE_ARCHITECTURE.md
QUICKSTART_REMOTE_GPIO.md		QUICKSTART_REMOTE_GPIO.md
README.md		README.md
SKEEBALL_CONTROLS.md		SKEEBALL_CONTROLS.md
SKEEBALL_DISPLAY_FIX.md		SKEEBALL_DISPLAY_FIX.md
SKEEBALL_FINAL_FIX.md		SKEEBALL_FINAL_FIX.md
SKEEBALL_FIXES_APPLIED.md		SKEEBALL_FIXES_APPLIED.md
SKEEBALL_INTEGRATION_SUMMARY.md		SKEEBALL_INTEGRATION_SUMMARY.md
SKEEBALL_REMOTE_CONTROL.md		SKEEBALL_REMOTE_CONTROL.md
SKEEBALL_REVENUE_INTEGRATION.md		SKEEBALL_REVENUE_INTEGRATION.md
SKEEBALL_STATS_TESTING.md		SKEEBALL_STATS_TESTING.md
SKEEBALL_TROUBLESHOOTING.md		SKEEBALL_TROUBLESHOOTING.md
START_TESTING_SKEEBALL.md		START_TESTING_SKEEBALL.md
TRACKING_SETUP.md		TRACKING_SETUP.md
VERSION_1.0_RELEASE_NOTES.md		VERSION_1.0_RELEASE_NOTES.md
WARP.md		WARP.md
app.py		app.py
arcade-tracker-ngrok.service		arcade-tracker-ngrok.service
arcade-tracker.service		arcade-tracker.service
check_all_schemas.py		check_all_schemas.py
check_db_schema.py		check_db_schema.py
config.py		config.py
create_admin.py		create_admin.py
create_docs_pdf.py		create_docs_pdf.py
create_inventory_requests_table.py		create_inventory_requests_table.py
create_iso_backup.py		create_iso_backup.py
create_manager.py		create_manager.py
create_request_history_table.py		create_request_history_table.py
create_tables.py		create_tables.py
create_work_log_table.py		create_work_log_table.py
deploy-to-proxmox.sh		deploy-to-proxmox.sh
deploy_stats_api.sh		deploy_stats_api.sh
deploy_to_pi.sh		deploy_to_pi.sh
docker-compose.yml		docker-compose.yml
game_logic.py		game_logic.py
generate_documentation.py		generate_documentation.py
generate_icons.py		generate_icons.py
gpio_init.py		gpio_init.py
init_db.py		init_db.py
input_manager.py		input_manager.py
lane_controller.py		lane_controller.py
lane_manager.py		lane_manager.py
list_users.py		list_users.py
load_env.py		load_env.py
migrate_all_missing.py		migrate_all_missing.py
migrate_db.py		migrate_db.py
register_skeeball_lanes.py		register_skeeball_lanes.py
remove_emojis.py		remove_emojis.py
requirements.txt		requirements.txt
requirements_cloud.txt		requirements_cloud.txt
reset_ranking_counters.py		reset_ranking_counters.py
revenue_scheduler.py		revenue_scheduler.py
run.py		run.py
run.sh		run.sh
run_app.sh		run_app.sh
security_config.py		security_config.py
security_middleware.py		security_middleware.py
security_utils.py		security_utils.py
serial_bridge.py		serial_bridge.py
skeeball_routes.py		skeeball_routes.py
start.app.sh		start.app.sh
test_auth.py		test_auth.py
test_features.py		test_features.py
test_security_utils.py		test_security_utils.py
test_skeeball_revenue.py		test_skeeball_revenue.py

Folders and files

Latest commit

History

Repository files navigation

🎮 Arcade Tracker v1.0

🌟 Features

Game Management

🆕 Advanced Maintenance System

Work Order Management

🔧 Timestamped Work Logging (New!)

Visual Work Timeline

Enhanced Reporting

👥 User Roles & Permissions

Read Only (Level 1)

Operator (Level 2)

Manager (Level 3)

Admin (Level 4)

🔧 New Work Logging Workflow

For Technicians/Operators:

For Managers:

🚀 Quick Start

Manual Setup (Alternative)

🎳 Skeeball Integration

🌟 Key Features

Automatic Scoring System

Game Management

Multi-Lane Architecture

Web Interface & APIs

🛠️ Hardware Requirements

Minimum Setup (Single Lane)

Optional Components

Default GPIO Pin Assignments (BCM Numbering)

🚀 Quick Start Guide

1. Installation

2. Development Testing (No Hardware Required)

3. Hardware Setup

4. Production Deployment

📊 Revenue Integration

Automatic Revenue Tracking

🔄 Real-Time State Synchronization

Revenue Workflow

🔧 Configuration

📚 Documentation

🔐 Security

🎯 Use Cases

Usage

Adding Games

Recording Plays

Viewing Reports

Database

Customization Ideas

🎉 Version 1.0 Release

Core Features

Daily Automated Backups

Real-Time Skeeball Integration

📈 Recent Updates (v1.0)

🎯 Monthly Performance Tracking

📊 Executive Summary Dashboard

🔧 Technical Improvements

🔧 Work Logging System

🎨 UI/UX Improvements

📋 Reporting Enhancements

🔒 Security & Performance

🛠️ Technical Architecture

Database Schema

Key Technologies

File Structure

🎯 Use Cases

Arcade Operators

Maintenance Technicians

Business Management

🔧 Database Migration

🚀 Getting Started

📋 Key Features Summary

About

Resources

Uh oh!

Stars

Watchers

Forks

Packages