#pragma once

/**
 * @file board_pins_mediakit.h
 *
 * Freenove FNK0102H Media Kit v1.2 pin map.
 *
 * Board: Freenove ESP32-S3 WROOM N16R8 (FNK0102H)
 * Sources:
 *   - docs/FNK0102H_SOURCE_OF_TRUTH.md (canonical pin tables)
 *   - ui_freenove_allinone/include/ui_freenove_config.h (validated firmware)
 *
 * Date frozen: 2026-06-10
 *
 * CRITICAL NOTE (voice_pipeline defaults):
 *   The voice_pipeline component defaults (in idf_zacus/components/voice_pipeline/voice_pipeline.c)
 *   are configured for a different wiring:
 *     - Mic: 14 (BCLK), 15 (WS), 22 (DIN)
 *     - Speaker: 11 (BCLK), 12 (LRC), 13 (DOUT)
 *
 *   These defaults COLLIDE with the FNK0102H camera pins:
 *     - 15 = CAM_PIN_XCLK
 *     - 13 = CAM_PIN_PCLK
 *     - 11 = CAM_PIN_D0 (Y2)
 *     - 12 = CAM_PIN_D4 (Y6)
 *
 *   When initializing voice_pipeline on the Media Kit, the defaults MUST be overridden
 *   with the FNK0102H values defined below (mic: 3/14/46, speaker: 42/41/1).
 *   This override is performed in the main application initialization (separate task).
 */

/* Camera pins (8-bit parallel interface + control) */
#define CAM_PIN_PWDN   -1   /* Power down: not wired */
#define CAM_PIN_RESET  -1   /* Reset: not wired */
#define CAM_PIN_XCLK   15   /* Master clock */
#define CAM_PIN_SIOD   4    /* I2C SDA (camera config) */
#define CAM_PIN_SIOC   5    /* I2C SCL (camera config) */
#define CAM_PIN_VSYNC  6    /* Vertical sync */
#define CAM_PIN_HREF   7    /* Horizontal ref / data enable */
#define CAM_PIN_PCLK   13   /* Pixel clock */

/* Camera data pins (D0..D7 = Y2..Y9 per esp32-camera convention) */
#define CAM_PIN_D0     11   /* Y2 */
#define CAM_PIN_D1     9    /* Y3 */
#define CAM_PIN_D2     8    /* Y4 */
#define CAM_PIN_D3     10   /* Y5 */
#define CAM_PIN_D4     12   /* Y6 */
#define CAM_PIN_D5     18   /* Y7 */
#define CAM_PIN_D6     17   /* Y8 */
#define CAM_PIN_D7     16   /* Y9 */

/* Microphone I2S IN (PDM or PCM, input path) */
#define MIC_PIN_BCLK   3    /* Bit clock (I2S_IN_SCK) */
#define MIC_PIN_WS     14   /* Word select (I2S_IN_WS) */
#define MIC_PIN_DIN    46   /* Data in (I2S_IN_DIN) */

/* Speaker I2S OUT (output path) */
#define SPK_PIN_BCLK   42   /* Bit clock (I2S_BCK) */
#define SPK_PIN_LRC    41   /* Left-right clock / word select (I2S_WS) */
#define SPK_PIN_DIN    1    /* Data out (I2S_DOUT) */

/**
 * GPIO Coexistence Table
 *
 * All GPIO pins used across camera, microphone, and speaker:
 *
 * GPIO  │ Device   │ Function
 * ──────┼──────────┼────────────────────
 *   1   │ Speaker  │ DOUT (I2S OUT)
 *   3   │ Mic      │ BCLK (I2S IN)
 *   4   │ Camera   │ SIOD (I2C SDA)
 *   5   │ Camera   │ SIOC (I2C SCL)
 *   6   │ Camera   │ VSYNC
 *   7   │ Camera   │ HREF
 *   8   │ Camera   │ D2 (Y4)
 *   9   │ Camera   │ D1 (Y3)
 *  10   │ Camera   │ D3 (Y5)
 *  11   │ Camera   │ D0 (Y2)
 *  12   │ Camera   │ D4 (Y6)
 *  13   │ Camera   │ PCLK
 *  14   │ Mic      │ WS (I2S IN)
 *  15   │ Camera   │ XCLK
 *  16   │ Camera   │ D7 (Y9)
 *  17   │ Camera   │ D6 (Y8)
 *  18   │ Camera   │ D5 (Y7)
 *  41   │ Speaker  │ LRC (I2S OUT)
 *  42   │ Speaker  │ BCLK (I2S OUT)
 *  46   │ Mic      │ DIN (I2S IN)
 *
 * Result: ZERO collision. Each GPIO assigned to exactly one device.
 *
 * Note: GPIO -1 (PWDN, RESET) indicates "not wired" and is not allocated.
 */

/* ── TFT display (FNK0102H ST7796 320×480) ─────────────────────────────────
 *
 * Source: ui_freenove_allinone/include/ui_freenove_config.h (validated firmware)
 *         docs/FNK0102H_SOURCE_OF_TRUTH.md (canonical pin tables)
 *
 * SPI host: SPI2_HOST (FSPI) — FREENOVE_LCD_USE_HSPI == 0 in the reference
 *   firmware, so the default FSPI host is used (not HSPI/SPI3_HOST).
 * Write frequency: 80 MHz.  Read frequency: 20 MHz.
 * CS pin: -1 (not wired — the panel is the only device on this SPI bus).
 *
 * Coexistence with camera/mic/speaker:
 *   GPIO 20 (TFT_PIN_RST): not present in the camera/mic/speaker tables above.
 *   GPIO 21 (TFT_PIN_MOSI): not present in the camera/mic/speaker tables above.
 *   GPIO 45 (TFT_PIN_DC):   not present in the camera/mic/speaker tables above.
 *   GPIO 47 (TFT_PIN_SCK):  not present in the camera/mic/speaker tables above.
 *   GPIO  2 (TFT_PIN_BL):   not present in the camera/mic/speaker tables above.
 *   RESULT: ZERO collision with any already-mapped GPIO.
 *
 * BACKLIGHT / LEDC NOTE (Phase 1):
 *   The reference firmware uses Light_PWM (LEDC) on GPIO 2.  In Phase 1 we
 *   drive the backlight as plain GPIO (full-on) because qr_puzzle already
 *   claims LEDC_TIMER_0 / LEDC_CHANNEL_0 for the camera XCLK.  Phase 2 will
 *   switch to Light_PWM on a free LEDC channel/timer once the XCLK is moved
 *   to the esp32-camera driver's own LEDC allocation.
 */
#define TFT_PIN_SCK    47   /* SPI clock */
#define TFT_PIN_MOSI   21   /* SPI MOSI  */
#define TFT_PIN_MISO   -1   /* not wired */
#define TFT_PIN_DC     45   /* D/C (register select) */
#define TFT_PIN_RST    20   /* hardware reset */
#define TFT_PIN_BL      2   /* backlight enable (Phase 1: plain GPIO, full-on) */
