RAZ TAMAGOTCHI - WIRING GUIDE
==============================

PROGRAMMER: ESP32-C3 Super Mini -> Raz (via SWD)
=================================================

The N32G031 SWD debug lines are accessible through the 8-pin
"USB-WK" junction on the Raz PCB (connects USB-C subsystem to
main board).

USB-WK JUNCTION PINOUT (measured & confirmed on Raz TN9000):

    Pin 1:  3.8V  (battery positive)
    Pin 2:  2.9V  (regulated power rail)
    Pin 3:  SWCLK (MCU PA14, pin 24) - 5.1k ohms to MCU
    Pin 4:  2.9V  (regulated power rail)
    Pin 5:  GND
    Pin 6:  SWDIO (MCU PA13, pin 23) - 10k ohms to MCU
    Pin 7:  GND
    Pin 8:  GND

CONNECTIONS (only 3 wires needed):

    ESP32-C3 Super Mini     Raz USB-WK Junction
    -------------------     -------------------
    GPIO 4  ------------->  USB-WK pin 3  (SWCLK / MCU PA14 pin 24)
    GPIO 5  ------------->  USB-WK pin 6  (SWDIO / MCU PA13 pin 23)
    GND     ------------->  USB-WK pin 5, 7, or 8  (any ground pin)

IMPORTANT:
  - Both boards are 3.3V logic. Direct connection is safe.
  - Do NOT use an Arduino Nano/Uno (5V logic) without level shifting!
  - Keep wires short (under 6 inches / 15cm) for reliable SWD.
  - The Raz battery should be charged. If the MCU doesn't respond,
    try feeding 3.3V from the ESP32's 3.3V pin to USB-WK pin 2 or 4.
  - USB-WK pins 5, 7, and 8 are ALL ground. Use whichever is easiest.

WARNING: Do NOT confuse the ground pins (5, 7, 8) with signal pins!
  The first board was bricked by accidentally soldering SWDIO to
  pin 8 (ground) instead of pin 6. Double-check with a meter.

FINDING THE SWD PADS ON YOUR RAZ:
  1. Pry open the case carefully (there are clips, no screws)
  2. Look for the 8-pin "USB-WK" junction between USB-C and main board
  3. Pin 1 is closest to the USB-C connector side
  4. Verify with multimeter: pin 3 should show ~5k ohms to MCU pin 24
     and pin 6 should show ~10k ohms to MCU pin 23
  5. Reference photos at: https://github.com/xbenkozx/RAZ-RE

N32G031 MCU RESET PIN:
  If the factory firmware has reconfigured SWD pins as GPIO, you may
  need to hold NRST (MCU pin 4, top-left near dot) to ground during
  the SWD connection sequence. This keeps the MCU in reset so the
  firmware can't override the SWD pin defaults.


PIN ASSIGNMENTS IN THE TAMAGOTCHI FIRMWARE:
==========================================

These are the pin connections from the N32G031 to the LCD via
the 5-pin FPC connector. SPI1 is remapped to Port B pins via AFIO.

    N32G031 Pin     Function              FPC Pin
    -----------     --------              -------
    PB3 (pin 25)    SPI1_SCK (remapped)   FPC 3 (SCK)
    PB5 (pin 27)    SPI1_MOSI (remapped)  FPC 4 (MOSI/SDA)
    PB7             GPIO out              FPC 1 (DC - data/command)
    PB4 (pin 26)    GPIO out              FPC 5 (LCD power enable)
    PA1             ADC CH1               Airflow/pressure sensor

    No CS pin (display always selected on 5-pin FPC)
    No RST pin (tied to VCC internally)

HOW TO VERIFY PIN ASSIGNMENTS:
  1. With the Raz open, find the 5-pin FPC connector
  2. Use a multimeter in continuity/resistance mode
  3. Touch one probe to FPC connector pins, the other to MCU pins
  4. Map which MCU pin goes to which FPC signal
  5. If assignments are wrong, the LCD just won't respond.
     Nothing will be damaged - you'll just see a blank screen.
     Swap the pin defines in main.c and reflash.
