MinecraftOrb/firmware

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.

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.