OpenConsole is an open-source gaming console operating system designed for modern indie games. It provides a controller-friendly interface for launching and managing games from multiple sources, with native support for local games and itch.io integration.

Forked from: EmulationStation

• Multi-Source Game Library: Scan local directories, itch.io library, and USB drives
• Multiple Game Formats: AppImage, Ren'Py, .deb packages, Electron apps, and more
• SQLite Database: Fast, reliable game metadata storage with play statistics
• Plugin Architecture: Extensible system for adding new game sources
• Secure Credential Storage: AES-256 encrypted storage for API tokens
• Controller-First UI: Designed for living room gaming without keyboard/mouse
• Virtual Keyboard: On-screen keyboard with full controller navigation
• Built-in itch.io Integration: Browse and download games from your itch.io library (always accessible)
• Universal Settings Access: OpenConsole Settings available in all UI modes
• Robust Game Scanning: Fully functional scanner with detailed statistics
• Auto-Boot Support: Boot directly into OpenConsole on Raspberry Pi
• Theme Support: Compatible with existing EmulationStation themes

• Primary Target: Raspberry Pi 5
• Supported: Raspberry Pi 4, Generic Linux x86_64
• Experimental: Windows, macOS

Comprehensive documentation is available in the docs/ directory:

• Architecture Overview
• Database Layer
• Plugin System
• Game Launcher System
• UI Components Guide
• itch.io Integration Guide
• Creating Plugins
• Configuration Guide
• System Integration
• Changelog

The easiest way to get started is with a pre-built image:

# Download the latest image
wget https://github.com/aldoram5/OpenConsole/releases/latest/download/openconsole-pi5.img.xz

# Flash to SD card (replace /dev/sdX with your SD card device)
xzcat openconsole-pi5.img.xz | sudo dd of=/dev/sdX bs=4M status=progress
sync

Insert the SD card into your Raspberry Pi 5 and power on. The system will boot directly into OpenConsole.

For installation on existing Linux systems:

# Clone the repository
git clone --recursive https://github.com/aldoram5/OpenConsole.git
cd OpenConsole

# Run the installer (standard mode)
sudo ./install.sh

# Or for console appliance mode (auto-boot to OpenConsole)
sudo ./install.sh --console-mode

The installer will:

• Install all dependencies
• Build OpenConsole from source
• Create the openconsole system user
• Configure the systemd service
• Set up controller support

OpenConsole uses C++11 and requires CMake for the build process.

Core Dependencies:

• CMake (3.10+)
• SDL2
• FreeImage
• FreeType
• libVLC (3.0+)
• libCURL
• SQLite3
• OpenSSL
• RapidJSON
• Boost (filesystem, system, locale)

# Install dependencies
sudo apt-get update
sudo apt-get install -y \
    build-essential cmake git \
    libsdl2-dev libfreeimage-dev libfreetype6-dev \
    libcurl4-openssl-dev rapidjson-dev libasound2-dev \
    libgl1-mesa-dev libssl-dev libsqlite3-dev \
    libvlc-dev libvlccore-dev vlc-bin \
    libboost-system-dev libboost-filesystem-dev libboost-locale-dev \
    fonts-droid-fallback

# Clone repository with submodules
git clone --recursive https://github.com/aldoram5/OpenConsole.git
cd OpenConsole

# Create build directory
mkdir build && cd build

# Configure and build
cmake ..
make -j$(nproc)

# The binary will be at build/emulationstation

# Install dependencies (enable RPM Fusion for VLC)
sudo dnf install -y \
    cmake gcc-c++ git \
    SDL2-devel freeimage-devel freetype-devel \
    libcurl-devel rapidjson-devel alsa-lib-devel \
    mesa-libGL-devel openssl-devel sqlite-devel \
    vlc-devel boost-devel

# Clone and build
git clone --recursive https://github.com/aldoram5/OpenConsole.git
cd OpenConsole
mkdir build && cd build
cmake ..
make -j$(nproc)

# Install Homebrew if not already installed
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install dependencies
brew install cmake sdl2 freeimage freetype curl openssl sqlite boost rapidjson pugixml libvlc

# Clone repository with submodules
git clone --recursive https://github.com/aldoram5/OpenConsole.git
cd OpenConsole

# If you already cloned without --recursive, initialize submodules:
# git submodule update --init --recursive

# Create build directory
mkdir build && cd build

# Configure with Homebrew paths
cmake .. \
    -DOPENSSL_ROOT_DIR=$(brew --prefix openssl) \
    -DFREETYPE_INCLUDE_DIRS=$(brew --prefix freetype)/include/freetype2 \
    -DSDL2_INCLUDE_DIR=$(brew --prefix sdl2)/include/SDL2

# Build
make -j$(sysctl -n hw.ncpu)

macOS Build Notes:

• The --recursive flag is important to initialize git submodules (nanosvg, pugixml). If you skip this, you must run git submodule update --init --recursive separately.
• If pugixml submodule is not initialized, the build system will look for it via Homebrew (brew install pugixml).
• libvlc provides the VLC development libraries needed for video support (different from the VLC.app cask).
• On Apple Silicon Macs, Homebrew libraries are in /opt/homebrew/, while Intel Macs use /usr/local/. The build system automatically searches both locations.

For Raspberry Pi OS (Bullseye or later), use Mesa GLES:

# Install dependencies
sudo apt-get update
sudo apt-get install -y \
    build-essential cmake git \
    libsdl2-dev libfreeimage-dev libfreetype6-dev \
    libcurl4-openssl-dev rapidjson-dev libasound2-dev \
    libgles2-mesa-dev libssl-dev libsqlite3-dev \
    libvlc-dev libvlccore-dev vlc-bin \
    libboost-system-dev libboost-filesystem-dev libboost-locale-dev \
    fonts-droid-fallback

# Clone and build
git clone --recursive https://github.com/aldoram5/OpenConsole.git
cd OpenConsole
mkdir build && cd build

# Configure with Mesa GLES and Pi optimizations
cmake .. -DUSE_MESA_GLES=On -DRPI=On

# Build (use fewer jobs on Pi to avoid memory issues)
make -j2

See the original EmulationStation Windows build instructions for Windows-specific setup. Windows support is experimental and may require additional configuration for OpenConsole-specific features.

Common CMake options:

• -DCMAKE_BUILD_TYPE=Debug - Build with debug symbols
• -DCMAKE_BUILD_TYPE=Release - Optimized release build
• -DUSE_MESA_GLES=On - Use Mesa GLES (required for Pi 4/5)
• -DRPI=On - Enable Raspberry Pi optimizations
• -DUSE_GLES1=On - Use GLESv1 legacy renderer

# Run OpenConsole (from build directory)
./emulationstation

# Or if installed system-wide
openconsole

On first run, OpenConsole will:

1. Create configuration directories (~/.emulationstation/, ~/.openconsole/)
2. Initialize the SQLite database
3. Prompt for controller configuration
4. Display the main menu

~/.emulationstation/     # EmulationStation configuration
├── es_settings.cfg      # User settings
├── es_input.cfg         # Controller mappings
└── es_log.txt           # Application log

~/.openconsole/          # OpenConsole-specific data
├── games.db             # Game database
├── credentials.enc      # Encrypted API tokens
├── downloads/           # Downloaded games
└── config.xml           # OpenConsole settings

1. Start OpenConsole
2. Hold a button on your controller when prompted
3. Map the buttons as instructed
4. Select "SAVE" to save the configuration

For advanced controller setup, use the provided utility:

./system/configure-controllers.sh

1. Open OpenConsole Settings (from main menu)
2. Navigate to "Plugins" section
3. Select "itch.io Authentication" -> "CONFIGURE"
4. Follow the instructions to obtain your API key from https://itch.io/user/settings/api-keys
5. Enter the API key using the virtual keyboard
6. Authentication will be tested automatically

1. Open OpenConsole Settings
2. Navigate to "Scanning" section
3. Select "Scan for Games Now"
4. OpenConsole will scan:
   • Local directories (~/Games, ~/.local/share/games, etc.)
   • itch.io library (if authenticated)
   • USB drives (if configured)

# Start OpenConsole
sudo systemctl start openconsole

# Stop OpenConsole
sudo systemctl stop openconsole

# Enable auto-start on boot
sudo systemctl enable openconsole

# View logs
sudo journalctl -u openconsole -f

# Check status
sudo systemctl status openconsole

Create a distributable image with OpenConsole pre-installed. There are multiple ways to build the image:

The easiest option is to use the automated GitHub Actions releases:

# Download latest release
wget https://github.com/aldoram5/OpenConsole/releases/latest/download/openconsole-pi5-<version>.img.xz

# Verify checksum
wget https://github.com/aldoram5/OpenConsole/releases/latest/download/openconsole-pi5-<version>.img.xz.sha256
sha256sum -c openconsole-pi5-<version>.img.xz.sha256

Releases are automatically created when you push a version tag:

git tag v1.0.0
git push origin v1.0.0
# GitHub Actions will build and publish the image

For local builds on non-Linux systems, use the Docker-based script:

# Requires Docker Desktop installed and running
./system/build-pi-image-docker.sh

# Output will be in ./output/openconsole-pi5-<date>.img.xz

This runs the build process inside a Linux container, so it works on macOS, Windows (WSL), and Linux.

On a Linux system (Debian/Ubuntu), you can run the build script directly:

# Install dependencies
sudo apt-get install -y wget xz-utils kpartx qemu-user-static parted

# Build the image
cd system
sudo ./build-pi-image.sh

This creates a compressed image file (openconsole-pi5-YYYYMMDD.img.xz) ready for flashing.

# Linux
xzcat openconsole-pi5-*.img.xz | sudo dd of=/dev/sdX bs=4M status=progress

# macOS (using Raspberry Pi Imager)
# 1. Open Raspberry Pi Imager
# 2. Choose OS → Use custom → select the .img.xz file
# 3. Choose Storage → select your SD card
# 4. Write

To create a new release with GitHub Actions:

1. Tag your version:

   git tag v1.0.0
   git push origin v1.0.0

2. GitHub Actions will automatically:

   • Build the Raspberry Pi image
   • Create a GitHub Release
   • Attach the image file with checksums

3. Monitor progress at: https://github.com/aldoram5/OpenConsole/actions

OpenConsole/
├── es-core/           # Core EmulationStation components
├── es-app/            # Application-specific code
│   ├── src/
│   │   ├── db/        # Database layer (SQLite)
│   │   ├── plugins/   # Game source plugins
│   │   ├── launchers/ # Game launchers
│   │   ├── api/       # External API clients
│   │   ├── utils/     # Utility classes
│   │   └── guis/      # GUI components
├── docs/              # Documentation
├── system/            # System integration files
└── CMake/             # CMake modules

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests (when available)
5. Submit a pull request

See the documentation for architecture details and development guides.

# Check logs
tail -f ~/.emulationstation/es_log.txt

# Check systemd service (if using)
sudo systemctl status openconsole
sudo journalctl -u openconsole -n 50

# List input devices
ls -l /dev/input/

# Check user groups
groups $(whoami)
# Should include: input video audio

# Add to input group if missing
sudo usermod -a -G input $(whoami)
# Log out and back in for changes to take effect

# View database statistics in OpenConsole Settings
# Or manually check the database
sqlite3 ~/.openconsole/games.db ".tables"
sqlite3 ~/.openconsole/games.db "SELECT COUNT(*) FROM games;"

For more troubleshooting information, see:

• UI Components Guide
• itch.io Integration Guide
• System Integration Guide

OpenConsole is built on top of EmulationStation by Alec "Aloshi" Lofquist.

OpenConsole is licensed under the same license as EmulationStation. See LICENSE.md for details.

• Repository: https://github.com/aldoram5/OpenConsole
• Issues: https://github.com/aldoram5/OpenConsole/issues
• Documentation: docs/
• Original EmulationStation: https://github.com/RetroPie/EmulationStation

The following sections are retained from the original EmulationStation documentation for reference.

C:\src>git clone https://github.com/Microsoft/vcpkg.git
C:\src>.\vcpkg\bootstrap-vcpkg.bat

C:\src\OpenConsole>mkdir nuget
C:\src\OpenConsole>cd nuget
C:\src\OpenConsole\nuget>nuget install -ExcludeVersion VideoLAN.LibVLC.Windows

c:\src>.\vcpkg\vcpkg install curl:x86-windows-static-md
c:\src>.\vcpkg\vcpkg install freeimage:x86-windows-static-md
c:\src>.\vcpkg\vcpkg install freetype:x86-windows-static-md
c:\src>.\vcpkg\vcpkg install sdl2:x86-windows-static-md
c:\src>.\vcpkg\vcpkg install rapidjson:x86-windows-static-md
c:\src>.\vcpkg\vcpkg install openssl:x86-windows-static-md
c:\src>.\vcpkg\vcpkg install sqlite3:x86-windows-static-md
c:\src>.\vcpkg\vcpkg install boost-filesystem:x86-windows-static-md
c:\src>.\vcpkg\vcpkg install boost-system:x86-windows-static-md
c:\src>.\vcpkg\vcpkg install boost-locale:x86-windows-static-md