ESPsNAKE/README.md

ESPsNAKE

ESPsNAKE is a small handheld Snake console built around an ESP32-C3. It uses a 1.3" I2C OLED, four directional buttons, and a buzzer for sound effects. The firmware also stores settings and per-difficulty leaderboards in non-volatile memory.

Overview

The project combines three parts:

• code/: the Arduino/PlatformIO firmware that runs the game.
• pcb/: the KiCad schematic and PCB for the handheld.
• 3d/: the enclosure and mechanical design reference.

The game starts on a title screen, supports multiple difficulty presets, a custom difficulty mode, leaderboard tracking, and name entry for new high scores.

Features

• Classic Snake gameplay with wall and self-collision.
• Sound feedback for food pickups and game over events.
• Sprint mode that activates by holding a direction button long enough.
• Three preset difficulties: Easy, Medium, and Hard.
• Custom difficulty with configurable step speed, speedup per food, and min/max limits.
• Persistent settings and leaderboards stored on the device.
• Separate leaderboards for Easy, Medium, and Hard.

Controls

The four buttons are active-low inputs with pull-ups enabled in firmware.

Button	GPIO	Main use
Up	GPIO0	Start game, move up, move through menus
Right	GPIO1	Open settings, move right
Down	GPIO3	Move down
Left	GPIO10	Open leaderboard, move left

Other controls and behaviors:

• L+R together confirm selections during name entry.
• The leaderboard shortcut is disabled while Custom difficulty is selected.
• Name entry uses an on-screen 4x7 keyboard with DEL and OK keys.

Hardware

Main parts shown in the schematic and PCB:

• ESP32-C3 SuperMini module: main controller.
• OLED 128x64 I2C display: game screen.
• SW1 to SW4: four tactile buttons.
• BZ1: polarized buzzer.
• TP4056 charger IC: single-cell Li-ion/LiPo charging from USB-C.
• DW01A + FS8205A: battery protection circuit.
• D1 and D2: charger status LEDs.
• J1 and J3: headers for serial/control access.
• Battery connector: 2-pin LiPo battery input.

Pin mapping used by the firmware

• Display I2C clock: GPIO9
• Display I2C data: GPIO8
• Buzzer: GPIO7
• Up: GPIO0
• Right: GPIO1
• Down: GPIO3
• Left: GPIO10

Power and Charging

The board is designed for a single-cell lithium battery.

• USB-C provides power for charging.
• The charger section uses a TP4056-class linear charger.
• The protection section uses DW01A and FS8205A for overcharge, overcurrent, and overdischarge protection.
• The schematic includes charge-status LEDs driven from the charger status pins.

Software Notes

The firmware is a PlatformIO Arduino project targeting esp32-c3-devkitm-1.

• Display library: U8g2.
• Runtime states: start screen, playing, game over, settings, leaderboard, and name entry.
• Settings saved in Preferences include buzzer frequency, difficulty, sprint enable, and custom difficulty values.
• Leaderboards are stored separately for each preset difficulty and use 8-character names.
• Sprint scoring awards 2 points per food while sprinting, otherwise 1 point.

3D Design

The enclosure/mechanical reference is stored in 3d/readme and points to the Onshape model:

https://cad.onshape.com/documents/bb9db5aa964d643ccd7e46c3/w/9284d4a7438acf7663ad1fe7/e/a1c5cd401b084cdfb7fd39db?renderMode=0&uiState=6a0da37ffa326fa20df8f248

If you extend the enclosure, keep the OLED, buttons, buzzer, USB-C access, and battery connector aligned with the PCB placement.

Notes

• Custom difficulty does not use the standard leaderboard flow.
• The game stores board-specific leaderboard data, so changing difficulty changes which board is active.
• The README is based on the current firmware and PCB files; verify mechanical details directly in Onshape before manufacturing changes.