doombox

shmegl’s DoomBox

frag4ink

An interactive promo kiosk built on Radxa Zero that displays a QR code for user registration, launches DOOM with custom player names, tracks high scores, and awards prizes to top players.

Key Features

Hardware Requirements

Software Stack

📁 Project Structure

The project has been reorganized for better maintainability:

doombox/
├── src/                     # Main application source code
│   ├── kiosk-manager.py    # Main kiosk application  
│   ├── game-launcher.py    # Game launching logic
│   ├── controller-input.py # Controller management
│   └── mqtt-client.py      # MQTT integration
├── scripts/                 # Utility scripts by category
│   ├── mqtt/               # MQTT setup and testing
│   ├── video/              # Video optimization
│   └── system/             # System monitoring
├── tests/                   # All tests organized by function
│   ├── mqtt/               # MQTT testing
│   └── integration/        # Integration testing  
├── tools/                   # Standalone utilities
│   ├── mqtt_commands.py    # Command line MQTT client
│   └── webhook.py          # Webhook bridge
├── config/                  # Configuration files
└── Makefile                # Simple command shortcuts

Using the Makefile

make help          # Show available commands
make setup         # Run full setup
make start         # Start the kiosk
make test          # Run all tests
make test-mqtt     # Test MQTT only
make clean         # Clean logs and temp files

Quick Setup

1. Clone the Repository on Your Radxa Zero

# Clone the repository
git clone https://github.com/your-username/doombox.git
cd doombox

# Verify you have the organized structure
ls -la
# Should show: src/, scripts/, tests/, tools/, config/, setup.sh, etc.

2. Run the Setup Script as Root

sudo bash setup.sh

The setup script will:

3. Start the Display Server

# Start X11 for testing
/opt/doombox/start_x_display.sh

4. Test Components

# Test dsda-doom directly
/opt/doombox/test_dsda_doom.sh

# Test via lzdoom compatibility wrapper
/opt/doombox/test_doom.sh

# Test the full kiosk application
/opt/doombox/test_kiosk.sh

5. Pair Your DualShock 4 Controller

# Use the new consolidated controller management script
./scripts/controller-manager.sh scan
./scripts/controller-manager.sh pair MAC_ADDRESS
./scripts/controller-manager.sh auto-connect

6. Configure Your Web Form URL

Edit the QR code URL in /opt/doombox/src/kiosk-manager.py:

self.form_url = "https://your-username.github.io/doombox-form/"

Or update the configuration in /opt/doombox/config/config.py:

GITHUB_FORM_URL = "https://your-username.github.io/doombox-form/"

7. Start the Kiosk Service

# Enable and start the service
/opt/doombox/start_kiosk_service.sh

# Or manually:
sudo systemctl enable doombox.service
sudo systemctl start doombox.service

Features

🎮 Game Integration

🎯 Controller Support

📊 Score Tracking

🔗 Remote Integration

Controller Management

Overview

The DoomBox uses a DualShock 4 controller with advanced pairing and connection management. The system supports both Bluetooth and wired connections with automatic reconnection.

Quick Controller Setup

# Scan for controllers
./scripts/controller-manager.sh scan

# Pair a specific controller
./scripts/controller-manager.sh pair MAC_ADDRESS

# Auto-connect to saved controller
./scripts/controller-manager.sh auto-connect

# Check controller status
./scripts/controller-manager.sh status

# Test controller input
./scripts/controller-manager.sh test

Controller Features

Troubleshooting Controllers

  1. Controller not found during scan:
    • Ensure controller is in pairing mode (hold PS + Share for 3-5 seconds)
    • Controller light should flash white
    • Try resetting controller (small button on back)
  2. Controller found but won’t pair:
    • Run ./scripts/controller-manager.sh setup to install dependencies
    • Try different pairing methods (script tries multiple approaches automatically)
    • Check Bluetooth service: systemctl status bluetooth
  3. Controller disconnects frequently:
    • Check battery level
    • Ensure controller is “trusted”: the pairing script handles this automatically
    • Try wired connection for debugging

Supported Controllers

File Structure

doombox/
├── README.md                    # This file
├── setup.sh                    # Main installation script
├── uninstall.sh                # Clean removal script
├── requirements.txt            # Python dependencies
├── src/                        # Core application files
│   ├── kiosk-manager.py        # Main kiosk controller
│   ├── controller-input.py     # DualShock 4 input handling
│   └── webhook.py              # API/webhook listener
├── config/                     # Configuration files
│   └── config.py               # Main configuration
├── scripts/                    # System scripts
│   ├── controller-manager.sh   # Controller management
│   └── test-suite.sh          # Comprehensive tests
├── web/                        # Web interface
│   └── index.html             # Form page
├── assets/                     # Static assets
│   ├── fonts/                 # Font files
│   ├── icons/                 # Icon library
│   └── vid/                   # Demo videos
├── logs/                       # Application logs
└── .github/                    # GitHub configuration
    └── instructions/           # Development guidelines

Development Log

2025-07-06: Codebase Consolidation & Cleanup

2025-07-06: Advanced Controller Pairing System

2025-07-06: DietPi AutoStart Configuration

2025-07-06: Fixed X11 Timeout and Game Launcher Issues

2025-07-06 - Initial Kiosk Deployment SUCCESS ✅

System: Radxa Zero (ARM64) running DietPi/Debian + minimal X server
Target: Physical kiosk deployment with minimal X server (no full desktop)

Deployment Steps Completed:

  1. Fixed DietPi detection - Corrected hardware model file path
  2. Resolved dependencies - Added /usr/games to PATH for doom executables
  3. Created minimal X server setup - start-x-kiosk.sh for physical display
  4. Updated systemd service - Proper service configuration with X server startup
  5. SDL configuration - Changed from fbcon to x11 for proper display support

Final System Configuration:

Service Status:

● doombox-kiosk.service - DoomBox Kiosk Application
     Loaded: loaded (/etc/systemd/system/doombox-kiosk.service; enabled)
     Active: active (running)

Key Log Entries:

2025-07-06 13:37:09 - INFO - DoomBox Kiosk initialized successfully!
2025-07-06 13:37:09 - INFO - Starting DoomBox kiosk main loop

Result: ✅ Kiosk is fully operational and ready for players!

Development Log

2025-07-06 - Kiosk Manager Icon & Font Enhancement

2025-07-06 - Kiosk Manager Restoration

Status: ✅ Kiosk display now fully functional with Doom 2016 fonts, proper icons, and video backgrounds

2025-07-06 - Visual Design Improvements

2025-07-06 - Header Styling & Layout Improvements

2025-07-06 - Fixed Header Text Shadow Rendering

2025-07-06 - Video Optimization & Hardware Acceleration ⚡

Problem: Video background playback was choppy and consuming excessive CPU on the Radxa Zero, with one core consistently at high usage.

Solution: Implemented multi-tier video optimization system with hardware acceleration support:

🎯 Performance Optimizations

🛠 New Components

📊 Performance Improvements

🔧 Usage

# Optimize existing videos for better performance
./scripts/optimize-videos.sh

# Test system capabilities and performance
./scripts/test-video-optimization.sh

# Monitor real-time performance
python3 scripts/performance-monitor.py --interval 5

# Run optimized kiosk
./start-kiosk.sh

🎮 Kiosk Integration

Status: ✅ Video playback now runs smoothly with minimal CPU usage, utilizing hardware acceleration when available

MQTT Setup & Remote Control

Overview

The DoomBox uses MQTT for remote communication between your development host and the Radxa Zero kiosk. This allows you to trigger games remotely, monitor status, and test functionality.

Quick Setup

1. Setup MQTT Broker on Your Arch Host

# Install and configure mosquitto
./scripts/setup-mqtt-broker.sh

# Configure IP addresses automatically
./scripts/configure-mqtt-ip.sh

# Test the setup
./scripts/test-mqtt-setup.sh

2. Deploy to Radxa

# Full deployment (configure, commit, push, deploy)
./scripts/deploy-mqtt.sh

# Or manual deployment
git add . && git commit -m "MQTT setup" && git push
ssh [email protected] "cd /root/doombox && git pull"

Testing Commands

From Your Host (Launch Games Remotely)

# Launch game for specific player
python3 scripts/mqtt-test-client.py --broker localhost launch TestPlayer

# Simulate web form registration
python3 scripts/mqtt-test-client.py --broker localhost register TestPlayer

# Get kiosk status
python3 scripts/mqtt-test-client.py --broker localhost status

# Monitor all messages
python3 scripts/mqtt-test-client.py --broker localhost monitor

# Interactive mode
python3 scripts/mqtt-test-client.py --broker localhost interactive

From Radxa (Test Connection)

# Test connection to your host
python3 scripts/mqtt-test-client.py --broker 10.0.0.100 status

# Launch local test
python3 scripts/mqtt-test-client.py --broker 10.0.0.100 launch LocalTest

MQTT Topics

Topic Purpose Message Format
doombox/commands Game control commands {"command": "launch_game", "player_name": "...", "skill": 3}
doombox/start_game Web form registrations {"player_name": "...", "timestamp": "..."}
doombox/status Status updates {"connected": true, "game_running": false, ...}
doombox/scores Score updates {"player_name": "...", "score": 12345, ...}
doombox/players Player events {"action": "registered", "player_name": "..."}
doombox/system System commands {"action": "reboot"}

Commands

Launch Game

{
  "command": "launch_game",
  "player_name": "TestPlayer",
  "skill": 3,
  "timestamp": "2025-07-06T12:00:00"
}

Stop Game

{
  "command": "stop_game",
  "timestamp": "2025-07-06T12:00:00"
}

Get Status

{
  "command": "get_status",
  "timestamp": "2025-07-06T12:00:00"
}

Configuration

The MQTT settings are configured in config/config.py:

Troubleshooting

Connection Issues

# Check mosquitto service
sudo systemctl status mosquitto

# Test basic connectivity
mosquitto_pub -h localhost -t "test" -m "hello"
mosquitto_sub -h localhost -t "test"

# Check firewall
sudo ufw status
sudo ufw allow 1883

IP Address Issues

# Reconfigure IP addresses
./scripts/configure-mqtt-ip.sh

# Check current IP
hostname -I

Python Dependencies

# Install on host
pip3 install paho-mqtt flask

# Install on Radxa
ssh [email protected] "pip3 install paho-mqtt flask"

MQTT Development Log

2025-07-06 - Initial MQTT Setup

Test Commands Created:

Features:

2025-07-06 - MQTT Setup Complete & Tested ✅

Successfully completed full MQTT setup and testing:

✅ MQTT Broker Setup (Arch Host)

✅ Test Client Implementation

✅ Cross-Platform Deployment

✅ End-to-End Testing

Ready for Production Use:

The MQTT infrastructure is now fully operational and ready for integration with the web form and game launcher components.

Game State Management & Video Pause Implementation ⚡

Major enhancement to game lifecycle management and video playback control

🎮 Enhanced Game Launcher

📺 Smart Video Management

🔧 Technical Implementation

📊 Configuration Details

# Enhanced dsda-doom.cfg with fullscreen enforcement
screen_width 1280
screen_height 960
use_fullscreen 1
force_fullscreen 1
windowed_mode 0
allow_windowed 0

🧪 Testing Results

🚀 User Experience

Status: ✅ Complete game state management system operational with full video pause/resume functionality

Recent Development Log

July 7, 2025 - Display and Fullscreen Fixes ✅

Issues Resolved:

Technical Changes:

  1. Git Repository Cleanup
    • Used git filter-branch to remove large video files from Git history
    • Added proper .gitignore for video files (*.mp4, *.avi, *.mov)
    • Repository size reduced from 3GB to 1.2MB
    • Push/pull operations now complete in seconds instead of minutes
  2. Kiosk Display Management (src/kiosk-manager.py)
    • Changed from pygame.display.quit() to pygame.display.iconify()
    • Prevents destruction of display subsystem during game launch
    • Properly minimizes kiosk window instead of destroying it
    • Video player completely stopped and destroyed to free GPU/CPU resources
    • Added proper restoration of kiosk after game completion
  3. Game Fullscreen Configuration (src/game-launcher.py)
    • Simplified dsda-doom configuration to remove invalid/unsupported settings
    • Cleaned up command line arguments to only use valid flags:
      • Removed: -exclusive_fullscreen, -force_fullscreen, -nowindow, -nograb
      • Kept: -fullscreen, -width 1280, -height 960, -aspect 1.33
    • Enhanced SDL environment variables for better fullscreen support
    • Added delay for kiosk to properly minimize before game launch
  4. Controller Support Improvements
    • Enhanced controller detection and logging
    • Simplified dsda-doom controller configuration
    • Added proper controller status reporting

Testing Results:

Known Issues:

Next Steps:

Architecture

…existing code…