# AGENTS.md

## Hardware

- **Board**: STM32H7S78-DK evaluation board
- **MCU**: STM32H7S78 (Cortex-M7 @ 480MHz)
- **Flash**: 2 MB external OSPI Flash (for Boot)
- **RAM**: 1 MB internal + external PSRAM (for Audio/Framebuffers)

## Project Architecture

### Dual-Boot Structure

This project uses a **dual-project architecture**:

| Project | Directory | Purpose |
|---------|-----------|---------|
| **Boot** | `/Boot/` | Bootloader - initializes hardware, loads application from external flash |
| **Appli** | `/Appli/` | Main application - TouchGFX UI + audio processing |

**Flashing order**: Boot must be flashed first, then Appli. After flashing Appli, press NRST button to start.

## Project Setup

- **IDE**: STM32CubeIDE with STM32CubeMX plugin
- **RTOS**: FreeRTOS V10.5.1 (CMSIS-RTOS V2)
- **GUI**: TouchGFX 4.26.1 with NemaGFX GPU acceleration
- **Language**: C/C++
- **Build System**: GCC Makefile (not CMake)

## Key Constraints

1. **Dual-boot flashing sequence**: Flash Boot first, then Appli. Press NRST after Appli flash.
2. **Never edit `Core/Src/` and `Core/Inc/` directly** - regenerate via STM32CubeMX instead
3. **High-speed audio acquisition (48kHz)** - uses DMA for ADF1 (microphone) and audio codec
4. **External memory usage**: Audio buffers (>900KB) stored in external PSRAM (section `AudioLooperBuffer`)
5. **TouchGFX architecture**: Two-stage debug - debug Boot first, then Appli
6. **FreeRTOS heap size**: Configured to 50KB in `FreeRTOSConfig.h` (heap_4)
7. **Interrupt priorities**: Audio interrupts at priority 2 (high priority), touch/SD at 14-15

## Build & Flash

### Prerequisites
- STM32CubeIDE (for CubeMX GUI, code generation)
- gcc-arm-embedded (`arm-none-eabi-gcc`)
- OpenOCD (for flashing)
- TouchGFX 4.26.1 (for GUI generation)

### Build Commands

**From `/gcc/` directory:**
```bash
make          # Build both Boot and Appli
make clean    # Clean all build artifacts
```

**Individual projects:**
```bash
# Build only Boot
make -f makefile_boot all

# Build only Appli
make -f makefile_appli all

# Flash Appli (after Boot is already flashed)
make -f makefile_appli flash
```

### Debugging

**Two-stage debugging process:**

1. **Debug Boot project first:**
```bash
# In STM32CubeIDE:
# 1. Open Boot project
# 2. Launch debug session
# 3. Wait for compilation/flash complete
# 4. Terminate session (Ctrl+F2)
```

2. **Debug Appli project:**
```bash
# In STM32CubeIDE:
# 1. Open Appli project
# 2. Launch debug session
# 3. Wait for compilation/flash complete
# 4. Click Resume (F8)
# 5. Press the black NRST button on the board
# 6. Application breaks at first line of main() in Appli
```

**Command line (if needed):**
```bash
# Start GDB server
openocd -f interface/jlink.cfg -f target/sth7rs.cfg

# In another terminal
arm-none-eabi-gdb gcc/target.elf
(gdb) target remote :3333
(gdb) load
(gdb) break main
(gdb) continue
```

## Sensors/Peripherals

### Audio (Primary Function)
- **ADF1** - Digital microphone (PDM interface, 48kHz sample rate)
- **I2C1** - Audio codec (STM32 Audio BSP)
- **DMA2D/GPDMA1/HPDMA1** - Audio DMA channels

### Display
- **LTDC** - LCD-TFT controller
- **GPU2D (NemaGFX)** - 2D acceleration
- **Display**: ST7789 (240x240 RGB)

### Storage & Communication
- **XSPI1** - External PSRAM (for audio buffers)
- **XSPI2** - External Flash (for TouchGFX assets)
- **I2C1** - Touch controller (FT5336), sensors

### Touch Control
- **FT5336** - Capacitive touch controller
- **SPI** - Touch interface
- **GPIO** - Touch interrupt (TP_IRQ)

## Audio Processing

### Effects Chain (in order)
1. **Octaver** - Dual-grain pitch shifting (-2, -1, +1, +2 octaves)
2. **Equalizer** - 5-band graphic EQ
3. **Overdrive** - Distortion effect
4. **Saturation** - Audio saturation
5. **Echo** - Delay-based echo
6. **Reverb** - Room reverb

### Analysis
- **FFT**: 2048-point real FFT (CMSIS-DSP)
- **Sample rate**: 48kHz
- **Bins**: 1024 (0-24kHz spectrum)
- **Peak detection**: Frequency with maximum magnitude

### Looping
- **Duration**: Up to 5 seconds at 48kHz
- **Playback**: 2x speed (raises pitch by octave)
- **Storage**: External PSRAM (937.5KB buffer)

## TouchGFX Architecture

### Project Structure
```
Appli/
├── TouchGFX/
│   ├── App/                    # Application code (user created)
│   ├── assets/                 # Images, fonts, videos
│   ├── build/                  # Generated build files
│   ├── config/                 # Build configuration
│   ├── generated/              # Auto-generated code (DO NOT EDIT)
│   ├── gui/                    # Custom GUI code (views, presenters)
│   ├── simulator/              # Simulator files
│   └── target/                 # Target-specific code
```

### GUI Screens
- **InitScreen** - Initial splash screen
- **Overview** - Main screen with audio on/off, volume, looper button
- **Oscillo** - Spectrum analyzer display
- **Octaver, Equalizer, Overdrive, Saturation, Echo, Reverb** - Effect tuning screens

## Memory Map

### Key Sections
- **AudioLooperBuffer** - External PSRAM (audio loop recording)
- **TouchGFX framebuffers** - External PSRAM (LCD display)
- **Heap** - Internal RAM (50KB FreeRTOS heap)
- **Stack** - Internal RAM (task stacks)

### External Memory
- **PSRAM**: 8MB (XSPI1) - Audio buffers + framebuffers
- **Flash**: 128MB (XSPI2) - TouchGFX assets (compressed images/fonts)

## Data Logging

- **Format**: CSV (to be implemented)
- **Storage**: SD card via SPI (not currently implemented in main code)
- **FATFS**: File system (available via Middlewares/ST)

---

*Last updated: October 2026*
*Project: STM32H7S78-DK Audio Effects Processor with TouchGFX*