# shellever/sa5-ultra architecture

> Architecture diagram of the GitHub repository shellever/sa5-ultra, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/shellever/sa5-ultra
- Repository: https://github.com/shellever/sa5-ultra

## Overview

##### Project Type and Purpose
- tinySA is an embedded firmware project for a handheld, battery‑powered spectrum analyzer built around an STM32 microcontroller (F072 or F303).
- It uses ChibiOS as its RTOS, FatFs for filesystem access, drivers for RF front‑ends (Si4432/Si446x), display (ILI9341 LCD), audio codec (TLV320AIC3204), and USB DFU for firmware updates.
- There is also a small Python‑based PC companion tool under the python/ directory.

##### File Structure Analysis
Top‑level components:
- Third‑party libraries:
– ChibiOS/ (RTOS kernel + HAL)
– FatFs/ (FAT filesystem)
- Board‑specific code:
– NANOVNA_STM32_F072/ and NANOVNA_STM32_F303/ subdirs (board configuration, MCU settings, Makefile snippets)
- HAL drivers and peripherals (/*.c, *.h):
– adc.c, hal_adc_lld.c
– spi.h
– si4432.c/.h, si4468.c + radio_config_*.h
– si5351.c/.h (clock generator)
– ili9341.c (LCD)
– tlv320aic3204.c (audio)
– rtc.c
– usbcfg.c/.h (USB DFU)
- Application layer:
– main.c (system init, thread startup)
– sa_core.c/.h (sweep engine + DSP)
– sa_cmd.c (command interface)
– plot.c, waterfall.c (data visualization)
– ui.c (menu system, user input)
– vna_browser.c (data export over USB)
- Build & config:
– Makefile, board linker scripts (STM32F072xB.ld, STM32F303xC.ld), chconf.h, halconf.h, mcuconf.h
- Python companion:
– python/nanovna.py, requirements.txt

##### Key Architectural Insights from README
- Real‑time sampling sweeps across RF bands using the Si445x front‑end, digitized by the ADC
- Data is processed and drawn to an ILI9341 LCD in real time (sweep plots, waterfall)
- ChibiOS threads isolate peripherals, DSP, UI, and USB
- Firmware is built with GCC‑ARM and flashed via DFU

##### Components
a. Hardware Layer
- STM32 MCU (F072 or F303)
- RF front‑end (Si4432/Si446x) + matching network
- Clock generator (Si5351)
- ADC (internal ADC peripheral)
- LCD display (ILI9341 via SPI)
- Audio codec (TLV320AIC3204 via I²S/SPI)
- USB interface (DFU device)
- Battery & power management (optional block)
b. Software Layer
- ChibiOS RTOS:
- Kernel + Thread scheduler
- HAL drivers (ADC, SPI, I²C, USB, RTC)
- Drivers & Abstraction:
- Radio driver (si446x.h/c + radio_config headers)
- Driver (ili9341.c)
- Audio driver (tlv320aic3204.c)
- Filesystem (FatFs) – used only if an SD card is present (optional)
- Application Threads:
- Sweep Engine Thread (sa_core.c)
- UI Thread (ui.c + chprintf)
- Plotting Thread (plot.c)
- Waterfall Thread (waterfall.c)
- USB Command/DFU Thread (usbcfg.c + vna_browser.c)
- Configuration Layer
- chconf.h, halconf.h, mcuconf.h
c. External Tools
- DFU Utility (host side)
- Python nanovna.py (USB‑based PC interface)

##### Interactions & Data Flows
- Control Flow: UI → commands → Sweep Engine → configures front‑end clock & radio registers
- Data Flow: ADC samples → DSP → Plot/Waterfall buffers → Display driver → LCD
- USB Flow: PC (Python) ↔ USB DFU & VNA browser interface → firmware update or data export

##### Architectural Patterns & Principles
- Layered architecture: HAL → drivers → RTOS services → application threads → UI
- Thread‑based concurrency for real‑time tasks
- Separation of concerns: RF sweep logic isolated from UI and display drawing
- Configurable builds: board‑specific directories for F072 vs. F303

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Hardware Layer
    subgraph "Hardware Layer"
        MC["STM32 MCU (F072/F303)"]:::hw
        RF["RF Front-end (Si4432/Si446x)"]:::hw
        CLK["Clock Generator (Si5351)"]:::hw
        ADC_HW["ADC Peripheral"]:::hw
        LCD["ILI9341 LCD"]:::hw
        AUDIO_HW["TLV320AIC3204 Audio Codec"]:::hw
        USB_HW["USB Interface (DFU)"]:::hw
        BAT["Battery & Power Mgmt"]:::hw
    end

    %% RTOS & Drivers
    subgraph "RTOS & Drivers"
        CHK["ChibiOS Kernel & HAL"]:::rtos
        FAT["FatFs Filesystem"]:::rtos
        HAL_ADC["ADC HAL Driver"]:::rtos
        HAL_SPI["SPI HAL Abstraction"]:::rtos
        DRM_RTC["RTC Driver"]:::rtos
        DRF_USB["USB DFU Interface"]:::rtos
        DRF_SI4432["Si4432 Driver"]:::rtos
        DRF_SI446x["Si446x Driver"]:::rtos
        RADIO_CFG["Radio Config Headers"]:::rtos
        DRF_SI5351["Si5351 Driver"]:::rtos
        DRF_LCD["ILI9341 Driver"]:::rtos
        DRF_AUDIO["TLV320AIC3204 Driver"]:::rtos
    end

    %% Application Threads
    subgraph "Application Threads"
        CORE["Sweep Engine Thread"]:::app
        UI["UI Thread"]:::app
        PLOT["Plotting Thread"]:::app
        WF["Waterfall Thread"]:::app
        USB_T["USB DFU/VNA Browser Thread"]:::app
    end

    %% Config & Build
    subgraph "Config & Build"
        CONF["Configuration Headers"]:::config
        LINK["Linker Scripts"]:::config
    end

    %% External Tools
    subgraph "External Tools"
        DFU_UTIL["DFU Utility"]:::ext
        PY_TOOL["Python nanovna.py"]:::ext
    end

    %% Control & Data Flows
    UI -->|"commands"| CORE
    CORE -->|"program radio via SPI"| RF
    CORE -->|"set clock via I2C"| CLK
    CORE -->|"start sampling"| ADC_HW
    ADC_HW -->|"samples"| CORE
    CORE -->|"DSP data"| PLOT
    CORE -->|"DSP data"| WF
    PLOT -->|"SPI"| LCD
    WF -->|"SPI"| LCD
    PY_TOOL <-->|"USB"| USB_T
    DFU_UTIL <-->|"USB"| USB_T

    %% Driver Relationships
    CHK --> HAL_ADC
    CHK --> HAL_SPI
    CHK --> DRM_RTC
    CHK --> DRF_USB
    CHK --> FAT
    HAL_SPI --> DRF_LCD
    HAL_SPI --> DRF_AUDIO
    HAL_SPI --> DRF_SI4432
    HAL_SPI --> DRF_SI446x
    HAL_SPI --> DRF_SI5351
    MC -->|"peripheral"| HAL_ADC
    MC -->|"SPI/I2C"| HAL_SPI
    MC -->|"USB"| DRF_USB
    CHK --> CORE
    CHK --> UI
    CHK --> PLOT
    CHK --> WF
    CHK --> USB_T
    CONF --> CHK
    CONF --> HAL_ADC
    LINK --> MC

    %% Click Events
    click CHK "https://github.com/shellever/sa5-ultra/tree/main/ChibiOS/"
    click FAT "https://github.com/shellever/sa5-ultra/tree/main/FatFs/"
    click HAL_ADC "https://github.com/shellever/sa5-ultra/blob/main/hal_adc_lld.c"
    click HAL_SPI "https://github.com/shellever/sa5-ultra/blob/main/spi.h"
    click DRM_RTC "https://github.com/shellever/sa5-ultra/blob/main/rtc.c"
    click DRF_USB "https://github.com/shellever/sa5-ultra/blob/main/usbcfg.c"
    click DRF_USB "https://github.com/shellever/sa5-ultra/blob/main/usbcfg.h"
    click DRF_SI4432 "https://github.com/shellever/sa5-ultra/blob/main/si4432.c"
    click DRF_SI4432 "https://github.com/shellever/sa5-ultra/blob/main/si4432.h"
    click DRF_SI446x "https://github.com/shellever/sa5-ultra/blob/main/si4468.c"
    click DRF_SI446x "https://github.com/shellever/sa5-ultra/blob/main/si446x.h"
    click RADIO_CFG "https://github.com/shellever/sa5-ultra/blob/main/radio_config_Si4468_*.h"
    click DRF_SI5351 "https://github.com/shellever/sa5-ultra/blob/main/si5351.c"
    click DRF_SI5351 "https://github.com/shellever/sa5-ultra/blob/main/si5351.h"
    click DRF_LCD "https://github.com/shellever/sa5-ultra/blob/main/ili9341.c"
    click DRF_AUDIO "https://github.com/shellever/sa5-ultra/blob/main/tlv320aic3204.c"
    click CORE "https://github.com/shellever/sa5-ultra/blob/main/sa_core.c"
    click UI "https://github.com/shellever/sa5-ultra/blob/main/ui.c"
    click PLOT "https://github.com/shellever/sa5-ultra/blob/main/plot.c"
    click WF "https://github.com/shellever/sa5-ultra/blob/main/waterfall.c"
    click USB_T "https://github.com/shellever/sa5-ultra/blob/main/vna_browser.c"
    click CONF "https://github.com/shellever/sa5-ultra/blob/main/chconf.h"
    click CONF "https://github.com/shellever/sa5-ultra/blob/main/halconf.h"
    click CONF "https://github.com/shellever/sa5-ultra/blob/main/mcuconf.h"
    click LINK "https://github.com/shellever/sa5-ultra/blob/main/STM32F072xB.ld"
    click LINK "https://github.com/shellever/sa5-ultra/blob/main/STM32F303xC.ld"
    click PY_TOOL "https://github.com/shellever/sa5-ultra/blob/main/python/nanovna.py"

    %% Styles
    classDef hw fill:#e0e0e0,stroke:#333,stroke-width:1px
    classDef rtos fill:#bbdefb,stroke:#333,stroke-width:1px
    classDef app fill:#c8e6c9,stroke:#333,stroke-width:1px
    classDef config fill:#fff9c4,stroke:#666,stroke-width:1px
    classDef ext fill:#ffe0b2,stroke:#333,stroke-width:1px
```
