97 lines
No EOL
3.8 KiB
Markdown
97 lines
No EOL
3.8 KiB
Markdown
# 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. |