Initial commit: Minecraft Orb project

ESP32-C3 firmware for interactive treasure hunt device with RFID, OLED display, LED effects, buzzer, and touch input. Includes 3D printable STL files for the enclosure. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-04-03 18:43:15 +01:00 · 2026-04-03 18:43:15 +01:00 · 28c36c51f6
commit 28c36c51f6
36 changed files with 2733 additions and 0 deletions
--- a/firmware/README.md
+++ b/firmware/README.md
@ -0,0 +1,149 @@
+# Minecraft Orb - Firmware
+
+An ESP32-C3 powered interactive treasure hunt device. Players scan RFID cards to reveal clues, solve Morse code puzzles, and complete touch-based challenges. Quest data is stored directly on MIFARE Classic 1K cards.
+
+Built for the **Giulio Hunt 2025** project.
+
+## Hardware
+
+| Component | Model | Interface | GPIO |
+|-----------|-------|-----------|------|
+| Microcontroller | ESP32-C3 SuperMini | - | - |
+| Display | SSD1306 128x64 OLED | I2C | SDA=2, SCL=3 |
+| RFID Reader | RC522 (13.56 MHz) | SPI | SCK=7, MOSI=8, MISO=9, CS=6, RST=10 |
+| LED | White (100 ohm resistor) | PWM | 4 |
+| Buzzer | Passive piezo | Tone | 0 |
+| Touch Sensor | TTP223 capacitive | Digital | 5 |
+
+Power is supplied via the **ESP32-C3 SuperMini Expansion Board**, which supports 3.7V LiPo battery with USB charging.
+
+```
+ESP32-C3 SuperMini Pinout (Top View, USB-C facing down)
+
+Left Side              Right Side
+---------              ----------
+GPIO5  <- Touch         5V
+GPIO6  <- RC522 SDA     GND
+GPIO7  <- RC522 SCK     3V3
+GPIO8  <- RC522 MOSI    GPIO4  <- LED
+GPIO9  <- RC522 MISO    GPIO3  <- LCD SCL
+GPIO10 <- RC522 RST     GPIO2  <- LCD SDA
+GPIO20   (FREE)         GPIO1    (FREE)
+GPIO21   (FREE)         GPIO0  <- Buzzer
+```
+
+## Building & Uploading
+
+Requires [PlatformIO](https://platformio.org/).
+
+```bash
+pio run                     # Build
+pio run --target upload     # Upload via USB-C
+pio device monitor          # Serial monitor (115200 baud)
+```
+
+## How It Works
+
+### Startup: Authentication
+
+On power-up, the device requires **5 players to scan their AUTH cards in ascending order** (IDs 1 through 5). Each card must have higher ID than the previous one. An out-of-order scan resets the sequence.
+
+AUTH card clue format: `PlayerName|ID|WelcomeMessage`
+
+Once all 5 authenticate successfully, the quest begins.
+
+### Quest Mode
+
+Players scan RFID cards to reveal clues on the OLED display. There are three types of quest cards:
+
+**Regular cards** — Display the card name and clue text on screen.
+
+**MORSE cards** — The clue is played as Morse code through the buzzer and LED. Dots and dashes are shown on the display but the text itself stays hidden.
+
+**INPUT cards** — A touch-based number puzzle. Players press the touch sensor N times to enter a code (1-10). The answer auto-submits after 3 seconds of no input. Correct answers reveal a message; wrong answers show an error.
+
+Card clue format for INPUT: `answer|message` (e.g., `5|The treasure is under the bridge`)
+
+### Programming Cards
+
+Connect via serial (115200 baud) and enter programming mode:
+
+```
+> PROG
+>>> Entered programming mode
+
+> ADD Quest 1|Go to the old oak tree near the lake
+Scan card to add as 'Quest 1'...
+<scan card>
+OK: Card programmed as 'Quest 1'
+
+> SCAN
+<scan card>
+Card UID: 12:AB:34:CD
+Name: Quest 1
+Clue: Go to the old oak tree near the lake
+
+> EXIT
+```
+
+| Command | Description |
+|---------|-------------|
+| `PROG` | Enter programming mode |
+| `EXIT` | Leave programming mode |
+| `SCAN` | Read card UID and contents |
+| `ADD name\|clue` | Write quest data to next scanned card |
+| `HELP` | Show commands |
+
+### Card Data Layout (MIFARE Classic 1K)
+
+| Sector | Blocks | Content | Size |
+|--------|--------|---------|------|
+| 1 | 4-5 | Card name | 32 bytes |
+| 2 | 8-10 | Clue part 1 | 48 bytes |
+| 3 | 12-14 | Clue part 2 | 48 bytes |
+| 4 | 16-18 | Clue part 3 | 48 bytes |
+
+Total capacity: 32 bytes name + 144 bytes clue. Uses default MIFARE key A (0xFFFFFFFFFFFF).
+
+## Battery Operation
+
+The device supports battery power via the ESP32-C3 SuperMini Expansion Board with a 3.7V LiPo cell. USB charging is handled by the board's TP4056 circuit (green LED = charging, LED off = full).
+
+Power saving features:
+
+| Event | Timeout | Behavior |
+|-------|---------|----------|
+| Display auto-off | 3 min inactivity | OLED turned off, any interaction wakes it |
+| Deep sleep | 10 min inactivity | All peripherals powered down (~uA draw) |
+| Wake | Touch sensor press | Full reboot through startup sequence |
+
+Timeouts are configurable in `include/config.h` (`DISPLAY_TIMEOUT_MS`, `SLEEP_TIMEOUT_MS`).
+
+The touch sensor must be on GPIO 0-5 for deep sleep wake to work (ESP32-C3 hardware limitation).
+
+## Project Structure
+
+```
+firmware/
+├── platformio.ini          # Build configuration
+├── include/
+│   ├── pins.h              # GPIO pin assignments
+│   ├── config.h            # Timeouts, card limits, NVS keys
+│   └── cards.h             # Card data structures
+└── src/
+    ├── main.cpp            # Firmware: init, event loop, display, RFID, audio, power
+    └── cards.cpp           # NVS card database, MIFARE read/write operations
+```
+
+## Dependencies
+
+| Library | Version | Purpose |
+|---------|---------|---------|
+| Adafruit SSD1306 | 2.5.x | OLED display driver |
+| Adafruit GFX | 1.12.x | Graphics primitives |
+| MFRC522 | 1.4.x | RC522 RFID reader |
+| Preferences | built-in | ESP32 NVS storage |
+
+## License
+
+Part of the Giulio Hunt 2025 project.