193 lines
5.5 KiB
Markdown
193 lines
5.5 KiB
Markdown
# 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*
|