131 lines
5.6 KiB
Markdown
131 lines
5.6 KiB
Markdown
# AGENTS.md — MTG RFID Companion (ESP-IDF)
|
|
|
|
> **Context for AI Agents & Assistant Tools:**
|
|
> This file outlines the architecture, coding guidelines, dependencies, hardware constraints, and build procedures for the **MTG RFID Companion** project. Read this completely before generating code, refactoring, or suggesting dependencies.
|
|
|
|
---
|
|
|
|
## 1. Project Overview
|
|
|
|
The **MTG RFID Companion** is a hand-held hardware utility for Magic: The Gathering players. It uses an **ESP32** microcontroller running **ESP-IDF v5.x (FreeRTOS)** to scan RFID/NFC tags embedded in card sleeves, query card data locally or via Scryfall's API, render data to a 2.0" ST7789 TFT LCD (240x320), and host a local registration web server.
|
|
|
|
---
|
|
|
|
## 2. Target Hardware & Specifications
|
|
|
|
* **MCU:** ESP32-WROOM-32 (Dual-Core Xtensa LX6, 240MHz, 520KB SRAM, 4MB Flash). *No external PSRAM.*
|
|
* **Display:** 2.0" ST7789 SPI TFT LCD (240x320 resolution, RGB565 format). Full-screen JPEG wallpapers supported via tjpgd decoder.
|
|
* **RFID Reader:** MFRC522 (13.56 MHz, SPI Interface, ISO/IEC 14443A).
|
|
* **Target Tags:** NTAG213 / NTAG215 micro FPC stickers or standard MIFARE ISO cards (7-byte or 4-byte UIDs).
|
|
* **User Input:** EC11 Rotary Encoder with integrated push button.
|
|
* **Storage:** On-chip SPI Flash partitioned with **LittleFS** (mounted at `/spiffs`, size ~1.5 MB).
|
|
|
|
---
|
|
|
|
## 3. Peripheral Wiring & GPIO Pinout
|
|
|
|
> **CRITICAL:** Do NOT modify GPIO pin assignments in code generation unless explicitly instructed. SPI bus is shared between ST7789 and MFRC522.
|
|
|
|
| Peripheral | Functional Pin | ESP32 GPIO Pin | Shared Bus / Notes |
|
|
| :--- | :--- | :--- | :--- |
|
|
| **Shared SPI** | SCK / MOSI / MISO | GPIO 18 / 23 / 19 | Shared SPI2_HOST (VSPI) |
|
|
| **MFRC522 RFID**| CS (SDA) / RST | GPIO 5 / GPIO 22 | Dedicated CS & Reset |
|
|
| **ST7789 Display**| CS / DC / RST | GPIO 15 / GPIO 2 / GPIO 4 | Dedicated CS, Data/Cmd & Reset |
|
|
| **Rotary Encoder**| CLK / DT / SW | GPIO 32 / GPIO 33 / GPIO 25 | Active low / Interrupt driven |
|
|
| **Indicators** | Neopixel (WS2812B) | GPIO 27 | RMT driver |
|
|
| **Audio** | Piezo Buzzer | GPIO 14 | LEDC PWM channel |
|
|
|
|
---
|
|
|
|
## 4. Software Architecture & FreeRTOS Task Allocation
|
|
|
|
The project strictly follows a **multithreaded, event-driven model** using FreeRTOS tasks and the ESP Event Loop.
|
|
|
|
### Core Core Split
|
|
* **Core 0 (System, I/O & Network):**
|
|
* `rc522_task`: Continuously polls RFID reader, emits events upon card detection.
|
|
* `net_task`: Manages Wi-Fi reconnects, Scryfall HTTPS fetches (`esp_http_client`), and `esp_http_server`.
|
|
* `storage_task`: Reads/writes JSON files to `/spiffs` via VFS.
|
|
* **Core 1 (User Interface & Rendering):**
|
|
* `ui_task`: Handles ST7789 display drawing using `esp_lcd` and rotary encoder inputs. Maintains UI frame rates without blocking Core 0 I/O.
|
|
|
|
### System State Machine
|
|
State transitions must be managed cleanly using FreeRTOS Event Groups or Queue messaging:
|
|
1. `STATE_BOOT`: Hardware setup, LittleFS mount, Wi-Fi auto-connect.
|
|
2. `STATE_SCANNER`: Waiting for RFID tag read.
|
|
3. `STATE_CARD_VIEW`: Displaying fetched/cached card attributes (P/T, Mana, Oracle text).
|
|
4. `STATE_LIFE_COUNTER`: Interactive 20/40 life counter utilizing rotary encoder.
|
|
5. `STATE_REGISTRATION`: Local SoftAP mode (`192.168.4.1`) active to pair unknown UIDs with card names via web browser.
|
|
|
|
---
|
|
|
|
## 5. Storage Structure (LittleFS `/spiffs`)
|
|
|
|
Do NOT assume an SD card is attached. All local database operations use standard C file I/O (`fopen`, `fread`, `fwrite`) over LittleFS.
|
|
|
|
* `/spiffs/mappings.json` — Maps scanned UIDs to Card Names:
|
|
```json
|
|
{
|
|
"04A2B3C4": "Sol Ring",
|
|
"04E1F2A3": "Atraxa, Praetors' Voice"
|
|
}
|
|
|
|
/spiffs/cards/[UID].json — Cached Scryfall card attribute details:
|
|
JSON
|
|
|
|
{
|
|
"name": "Sol Ring",
|
|
"mana_cost": "{1}",
|
|
"type": "Artifact",
|
|
"oracle": "Tap: Add CC.",
|
|
"price_usd": "1.25"
|
|
}
|
|
|
|
6. Coding Standards & Conventions
|
|
|
|
When generating or editing code for this repository:
|
|
|
|
Framework: Pure ESP-IDF v5.x (C99/C11 standard). Do NOT use Arduino.h headers, functions, or Arduino libraries (Serial.print, delay(), Wire, etc.).
|
|
|
|
Error Handling: Always wrap ESP-IDF API functions in ESP_ERROR_CHECK() or handle errors gracefully using esp_err_t ret. Log errors via ESP_LOGE().
|
|
|
|
Memory Management: SRAM is tight (~520KB total, no PSRAM).
|
|
|
|
Do NOT allocate huge static buffers on the FreeRTOS task stack.
|
|
|
|
Allocate HTTP response buffers and cJSON trees dynamically on the heap (heap_caps_malloc(..., MALLOC_CAP_8BIT)), and always free them immediately after use.
|
|
|
|
JSON Parsing: Use native cJSON. Check every pointer return for NULL before accessing object fields.
|
|
|
|
Logging Tag: Define a static tag per source file:
|
|
C
|
|
|
|
static const char *TAG = "MODULE_NAME";
|
|
|
|
7. Project Dependencies & Configuration
|
|
|
|
Managed via idf_component.yml:
|
|
|
|
abobija/rc522: SPI RFID reader driver.
|
|
|
|
joltwallet/littlefs: LittleFS VFS port for ESP-IDF.
|
|
|
|
espressif/esp_lcd: Official display subsystem (ST7789 controller driver).
|
|
|
|
Build Commands
|
|
|
|
Build Project: idf.py build
|
|
|
|
Flash to Device: idf.py -p <PORT> flash
|
|
|
|
Monitor Logs: idf.py -p <PORT> monitor
|
|
|
|
Partition Table: Uses custom partitions.csv (Flash allocation: 2MB App, 1.5MB LittleFS data).
|
|
|
|
8. Guidance for AI Agents Generating Code
|
|
|
|
When asked to build features: Write full, compile-ready C files (.c) and header files (.h) targeting ESP-IDF v5.x.
|
|
|
|
When modifying hardware code: Cross-check the shared SPI bus configurations to prevent SPI2_HOST bus conflicts between ST7789 and MFRC522.
|
|
|
|
When implementing network code: Use non-blocking esp_http_client requests running on a dedicated FreeRTOS task to keep screen rendering smooth. |