# 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.