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