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>

firmware/include/cards.h

@@ -0,0 +1,118 @@
+/**
+ * @file cards.h
+ * @brief RFID Card database management for Minecraft Orb
+ *
+ * Provides structures and functions for storing and retrieving
+ * quest card data from ESP32 NVS (Non-Volatile Storage).
+ */
+
+#ifndef CARDS_H
+#define CARDS_H
+
+#include <Arduino.h>
+#include "config.h"
+
+/**
+ * @brief Quest card data structure
+ *
+ * Stores RFID card UID along with quest metadata.
+ */
+struct QuestCard {
+    byte uid[MAX_UID_LEN];      // Card UID bytes
+    byte uidLength;             // Actual UID length (4 or 7)
+    char name[CARD_NAME_LEN];   // Quest name
+    char clue[CARD_CLUE_LEN];   // Clue/description text
+};
+
+/**
+ * @brief Initialize the card database
+ *
+ * Opens NVS namespace and loads card count.
+ */
+void initCardDatabase();
+
+/**
+ * @brief Get the number of stored cards
+ *
+ * Returns:
+ *     int: Number of cards in database
+ */
+int getCardCount();
+
+/**
+ * @brief Find a card by UID
+ *
+ * Args:
+ *     uid: Pointer to UID bytes
+ *     uidLength: Length of UID
+ *     card: Pointer to QuestCard to fill if found
+ *
+ * Returns:
+ *     int: Card index if found, -1 if not found
+ */
+int findCardByUID(byte* uid, byte uidLength, QuestCard* card);
+
+/**
+ * @brief Add a new card to the database
+ *
+ * Args:
+ *     card: Pointer to QuestCard to add
+ *
+ * Returns:
+ *     bool: true if added successfully
+ */
+bool addCard(QuestCard* card);
+
+/**
+ * @brief Delete a card by index
+ *
+ * Args:
+ *     index: Card index to delete
+ *
+ * Returns:
+ *     bool: true if deleted successfully
+ */
+bool deleteCard(int index);
+
+/**
+ * @brief Get a card by index
+ *
+ * Args:
+ *     index: Card index
+ *     card: Pointer to QuestCard to fill
+ *
+ * Returns:
+ *     bool: true if card exists at index
+ */
+bool getCard(int index, QuestCard* card);
+
+/**
+ * @brief Clear all cards from database
+ */
+void clearAllCards();
+
+/**
+ * @brief Format UID as hex string
+ *
+ * Args:
+ *     uid: Pointer to UID bytes
+ *     uidLength: Length of UID
+ *     buffer: Output buffer (must be at least uidLength*3)
+ */
+void formatUID(byte* uid, byte uidLength, char* buffer);
+
+/**
+ * @brief Compare two UIDs
+ *
+ * Args:
+ *     uid1: First UID
+ *     len1: First UID length
+ *     uid2: Second UID
+ *     len2: Second UID length
+ *
+ * Returns:
+ *     bool: true if UIDs match
+ */
+bool compareUID(byte* uid1, byte len1, byte* uid2, byte len2);
+
+#endif // CARDS_H

firmware/include/config.h

@@ -0,0 +1,36 @@
+/**
+ * @file config.h
+ * @brief Configuration constants for Minecraft Orb
+ */
+
+#ifndef CONFIG_H
+#define CONFIG_H
+
+#include "secrets.h"  // WIFI_SSID, WIFI_PASSWORD
+
+// =============================================================================
+// WiFi Configuration
+// =============================================================================
+#define WIFI_TIMEOUT_MS     10000   // 10 seconds connection timeout
+
+// =============================================================================
+// Card Database Configuration
+// =============================================================================
+#define MAX_CARDS           15      // Maximum number of stored cards
+#define CARD_NAME_LEN       32      // Max length of quest name
+#define CARD_CLUE_LEN       128     // Max length of clue text
+#define MAX_UID_LEN         7       // Max RFID UID length (4 or 7 bytes)
+
+// =============================================================================
+// NVS Storage Keys
+// =============================================================================
+#define NVS_NAMESPACE       "orb_cards"
+#define NVS_CARD_COUNT      "card_count"
+
+// =============================================================================
+// Power Management (Battery Operation)
+// =============================================================================
+#define DISPLAY_TIMEOUT_MS  180000  // 3 minutes: turn off display
+#define SLEEP_TIMEOUT_MS    600000  // 10 minutes: enter deep sleep
+
+#endif // CONFIG_H

firmware/include/pins.h

@@ -0,0 +1,48 @@
+/**
+ * @file pins.h
+ * @brief Pin definitions for Minecraft Orb - ESP32-C3 SuperMini
+ *
+ * Hardware Configuration:
+ * - SSD1306 OLED Display (128x64) via I2C
+ * - RC522 RFID Reader via SPI
+ * - White LED indicator
+ * - Piezo buzzer for audio feedback
+ * - TTP223 capacitive touch sensor
+ */
+
+#ifndef PINS_H
+#define PINS_H
+
+// =============================================================================
+// I2C - SSD1306 OLED Display (Right side of board)
+// =============================================================================
+#define I2C_SDA         2   // I2C Data
+#define I2C_SCL         3   // I2C Clock
+#define OLED_ADDRESS    0x3C  // Default I2C address for SSD1306
+
+// =============================================================================
+// SPI - RC522 RFID Reader (Left side of board)
+// Pin order matches RC522 board: SDA, SCK, MOSI, MISO, RST
+// =============================================================================
+#define RC522_CS        6   // SDA - Chip Select for Reader
+#define SPI_SCK         7   // SCK - SPI Clock
+#define SPI_MOSI        8   // MOSI - SPI Data Out
+#define SPI_MISO        9   // MISO - SPI Data In
+#define RC522_RST       10  // RST - Reset for Reader
+
+// =============================================================================
+// LED (Right side of board)
+// =============================================================================
+#define LED_WHITE       4   // White LED (via 100 ohm resistor)
+
+// =============================================================================
+// Buzzer (Right side of board)
+// =============================================================================
+#define BUZZER_PIN      0   // Piezo buzzer (passive)
+
+// =============================================================================
+// Touch Sensor (Left side of board)
+// =============================================================================
+#define TOUCH_PIN       5   // TTP223 capacitive touch sensor (GPIO0-5 for deep sleep wake)
+
+#endif // PINS_H

firmware/include/secrets.h.example

@@ -0,0 +1,14 @@
+/**
+ * @file secrets.h
+ * @brief Sensitive credentials — DO NOT COMMIT
+ *
+ * Copy this file to secrets.h and fill in your values.
+ */
+
+#ifndef SECRETS_H
+#define SECRETS_H
+
+#define WIFI_SSID       "your-ssid"
+#define WIFI_PASSWORD   "your-password"
+
+#endif // SECRETS_H