ESP32 OLED Game System

This project implements a simple multi-game system on an ESP32 microcontroller, featuring an OLED display for graphics and physical buttons for user interaction. It provides a modular framework for easily adding new games.

Features

• Game Selection Menu Navigate and select different games using physical buttons.

• Multiple Games Includes "Jump Bird" and "Arkanoid" as examples, with a clear structure for adding more.

• OLED Display Utilizes an SSD1306 OLED display for all game graphics and menu navigation.

• Button Input Reads inputs from push buttons for both menu navigation and in-game control.

• LED Feedback Provides visual status feedback through an LED.

• Modular Game Architecture Each game is implemented as a standalone module following a shared interface, enabling easy expansion.

Hardware Requirements

To run this project, you’ll need:

• ESP32 Development Board Any ESP32 board compatible with ESP-IDF (e.g., ESP32-DevKitC).

• SSD1306 OLED Display 128x64 pixel, I²C interface.

• I²C Wiring

  • SDA: GPIO 19
  • SCL: GPIO 18
  • VCC: 3.3V
  • GND: GND

• Push Buttons At least two buttons:

  • One for "select/jump/right"
  • One for "move left/menu navigation"

• LED Standard LED with a current-limiting resistor.

• Jumper Wires / Breadboard For prototyping and connections.

Software Requirements

• ESP-IDF Version 5.x or later is recommended. Follow the official ESP-IDF Programming Guide for setup.

• ESP-IDF Toolchain Installed as part of ESP-IDF setup.

Project Structure

esp32-oled-game-system/
│
├── main/                                # Application entry point
│   └── main.c                           # app_main function and orchestration
│
├── tasks/                               # Functional FreeRTOS tasks
│   ├── button_task.c/h                  # Button input handling
│   ├── led_task.c/h                     # LED control
│   ├── button_led_comm.c/h             # Shared structures between button & LED
│   ├── display_task.c/h                # OLED rendering logic
│   └── game/                            # Game system components
│       ├── game_framework.h            # Common game interface (game_t)
│       ├── game_menu.c/h               # Game selection menu logic
│       ├── game_drawing.c/h            # Drawing utilities for games
│       ├── jump_bird_game.c/h          # "Jump Bird" game
│       └── arkanoid_game.c/h           # "Arkanoid" game
│
├── components/
│   └── ssd1306/                         # SSD1306 OLED driver

Building and Flashing

1. Navigate to Project Directory

cd C:/Users/HomePC/Desktop/Projects/rc-car/

(Replace with your actual path.)

2. Clean Project (Recommended)

idf.py clean

3. Build

idf.py build

4. Flash to Device

idf.py flash

5. Monitor Serial Output

idf.py monitor

Press Ctrl+] to exit the monitor.

How to Play

Menu Navigation

• Left Button: Move down through game options.
• Right Button: Select the highlighted game.

In-Game Controls

• Jump Bird

  • Any button: Make the bird jump.

• Arkanoid

  • Left Button: Move paddle left.
  • Right Button: Move paddle right.

Game Over Screen

• Displays "GAME OVER!" with your score.
• Left Button: Restart the same game.
• Right Button: Return to main menu.

Adding New Games

The system is designed to be easily extensible. See the detailed guide: 📄 How to Add a New Game to the ESP32 Game System

Troubleshooting

OLED Not Displaying

• Check I2C wiring (SDA/SCL/VCC/GND).
• Confirm OLED I2C address (0x3C default, some use 0x3D). Adjust OLED_I2C_ADDRESS in display_task.c if needed.
• Look for errors like:
  • Failed to create I2C bus
  • Failed to add I2C OLED device

Buttons Not Responding

• Check GPIO wiring and resistors.
• Validate button GPIO numbers in button_task.c.
• Look for input signal logs in idf.py monitor.

Multiple Definition Errors

• Happens when functions or variables are duplicated across .c files.
• Ensure common code is in shared files (game_drawing.c) and only declared in headers.
• Run:

  idf.py clean
  idf.py build

Game Freezes or Crashes

• Check idf.py monitor for runtime logs or panic messages.
• Debug issues in game state handling, task communication, or I2C initialization.