# snappergps/snappergps-firmware architecture

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

- Interactive diagram: https://gitdiagram.com/snappergps/snappergps-firmware
- Repository: https://github.com/snappergps/snappergps-firmware

## Overview

##### Project type and purpose
- This is an embedded firmware project for a SnapperGPS receiver built on a Silicon Labs EFM32HG (Arm Cortex-M0+) MCU.
- It comprises a common “shared_library” of hardware-abstraction and peripheral drivers (CMSIS, EMLIB, EMUSB, plus custom ADC/flash/radio/timer modules) plus one or more “firmware_versions” that pull in that library, compile application logic (main.c), and produce a final .bin/.elf for flashing.

##### File structure (component candidates)
- Top-level:
- shared_library/ – reusable HAL and peripheral drivers
- firmware_versions/ – one subfolder per firmware variant (snapper, snapper-accelerometer)
- Makefiles under each variant for build definitions (compiler path, linker script, flash origin)
- shared_library submodules:
- cmsis/ – core startup and CMSIS definitions
- device/ – silicon-specific registers and startup code
- emlib/ – Silicon Labs peripheral abstractions (ADC, GPIO, USART, etc.)
- emusb/ – USB device stack
- inc/ & src/ – custom drivers for ADC, flash chip, radio, timer
- firmware_versions/<variant>/inc & src/ – application logic, USB descriptors, config
- firmware_versions/<variant>/build – linker script (.ld), Makefile

##### Core README insights
- Purpose: Provide standard firmware & an accelerometer-enabled variant
- Build: Arm GNU Toolchain + Makefiles + Linker script
- Flashing: via WebUSB or SWD, making use of generic USB messages & SnapperGPS-specific WebUSB protocol

##### Components
1. Build System
- Arm-GNU Toolchain, Make & Linker scripts
2. Source Modules
- shared_library
- CMSIS (core_cm0plus, startup)
- device headers & startup code
- EMLIB (peripheral abstraction)
- EMUSB (USB stack)
- Custom drivers (ADC, Flash, Radio, Timer)
- firmware_versions/<variant>
- USB descriptors & config
- Application logic (main.c, accelerometer.c)
3. Firmware Binary (.bin/.elf)
4. Target Hardware (EFM32HG310F64G MCU)
- On-chip: Flash (internal), SRAM, peripherals (ADC, TIMER, USB FS, USART)
- Off-chip: W25N512GV external flash, GNSS radio front-end, optional accelerometer
5. Runtime Interfaces
- USB WebUSB interface (generic + SnapperGPS messages)
- GNSS snapshot capture (radio → memory)
- Data storage (external flash)
- ADC measurements (battery, temperature)
- Timer interrupts / RTC
6. Host-side Web App (snappergps.info)
- Configuration/firmware-update UI communicating over WebUSB

- Build System → pulls in shared_library + firmware_version → produces Firmware Binary
- Firmware Binary → flashed onto MCU
- At runtime:
- MCU firmware ↔ Web Browser (WebUSB)
- MCU firmware → reads GNSS radio → stores snapshots → stores to external flash → serves to host on request
- MCU firmware → measures battery/temp via ADC driver → reports in GET_STATUS
- MCU firmware → uses timer/RTC for scheduling snapshots or shutdown
- Custom drivers ←­ layered on top of EMLIB ←­ layered on top of CMSIS

c. Architectural patterns & design principles
- Layered HAL: CMSIS → device startup → EMLIB → custom drivers → application logic
- Clear separation between shared/common code and firmware-specific code
- Single-image firmware with generic USB-bootloader compatibility
- Build-time configuration via Makefile and linker script

d. Key technologies/frameworks
- Arm GNU Toolchain (gcc, ld)
- Make, linker script (.ld)
- CMSIS, Silicon Labs EMLIB, EMUSB stacks
- WebUSB standard + custom USB descriptors
- W25N512GV external SPI-flash
- Silicon Labs Happy Gecko peripherals: ADC, TIMER, USART, USB FS

## Diagram (Mermaid)

```mermaid
graph TD
    %% Build System
    subgraph "Build System" 
        direction TB
        Make_Snapper["Makefile (snapper)"]:::build
        Linker_Snapper["snapper.ld"]:::build
        Make_Accel["Makefile (snapper-accelerometer)"]:::build
        Linker_Accel["snapper.ld"]:::build
    end

    %% Source Modules
    subgraph "Source Modules" 
        direction TB
        subgraph "shared_library" 
            direction TB
            CMSIS["CMSIS (core_cm0plus, startup)"]:::code
            DEVICE_INC["device/inc"]:::code
            STARTUP["startup_efm32hg.s"]:::code
            SYSTEM["system_efm32hg.c"]:::code
            subgraph "EMLIB" 
                direction TB
                EMLIB_INC["emlib/inc"]:::code
                EMLIB_SRC["emlib/src"]:::code
            end
            subgraph "EMUSB"
                direction TB
                EMUSB_INC["emusb/inc"]:::code
                EMUSB_SRC["emusb/src"]:::code
            end
            subgraph "Custom Drivers"
                direction TB
                ADC["analogToDigitalConverter.h/.c"]:::code
                FLASH["flash.h/.c"]:::code
                RADIO["radio.h/.c"]:::code
                TIMER["timer.h/.c"]:::code
                PINOUTS["pinouts.h"]:::code
            end
        end
        subgraph "firmware_versions"
            direction TB
            subgraph "snapper"
                direction TB
                USBCALL_S["usbcallbacks.h"]:::code
                USBCONF_S["usbconfig.h"]:::code
                USBDESC_S["usbdescriptors.h"]:::code
                MAIN_S["main.c"]:::code
            end
            subgraph "snapper-accelerometer"
                direction TB
                ACCEL_H["accelerometer.h"]:::code
                USBCALL_A["usbcallbacks.h"]:::code
                USBCONF_A["usbconfig.h"]:::code
                USBDESC_A["usbdescriptors.h"]:::code
                ACCEL_C["accelerometer.c"]:::code
                MAIN_A["main.c"]:::code
            end
        end
    end

    %% Firmware Binary
    FirmwareBin["Firmware Binary (.bin/.elf)"]:::firmware

    %% Hardware
    subgraph "Target Hardware (EFM32HG310F64G MCU)"
        direction TB
        OnChip["On-chip:\nFlash, SRAM, ADC, TIMER, USB FS, USART"]:::hardware
        OffChip["Off-chip:\nW25N512GV flash, GNSS radio, accelerometer"]:::hardware
    end

    %% Runtime Interfaces
    subgraph "Runtime Interfaces"
        direction TB
        USB_IF["USB WebUSB Interface"]:::interface
        GNSS_FLOW["GNSS Radio → Memory"]:::interface
        STORAGE["External Flash Storage"]:::interface
        ADC_MEAS["ADC Measurements"]:::interface
        TIMER_IF["Timer/RTC"]:::interface
    end

    %% Host Web App
    HostApp["Host-side Web App\n(snappergps.info)"]:::host

    %% Connections
    Make_Snapper -->|pulls in| CMSIS
    Make_Snapper -->|pulls in| DEVICE_INC
    Make_Snapper -->|pulls in| EMLIB_INC
    Make_Snapper -->|pulls in| EMUSB_INC
    Make_Snapper -->|pulls in| ADC
    Make_Snapper -->|pulls in| USBCALL_S
    Make_Snapper -->|uses| Linker_Snapper
    Make_Accel -->|pulls in| CMSIS
    Make_Accel -->|pulls in| DEVICE_INC
    Make_Accel -->|pulls in| EMLIB_INC
    Make_Accel -->|pulls in| EMUSB_INC
    Make_Accel -->|pulls in| ACCEL_H
    Make_Accel -->|pulls in| USBCALL_A
    Make_Accel -->|uses| Linker_Accel

    CMSIS -->|layer| DEVICE_INC
    DEVICE_INC -->|layer| EMLIB_INC
    EMLIB_INC -->|layer| EMUSB_INC
    EMUSB_INC -->|layer| ADC
    ADC -->|layer| FLASH
    FLASH -->|layer| RADIO
    RADIO -->|layer| TIMER

    CMSIS & DEVICE_INC & EMLIB_INC & EMUSB_INC & ADC & USBCALL_S & MAIN_S -->|compile| FirmwareBin
    CMSIS & DEVICE_INC & EMLIB_INC & EMUSB_INC & ACCEL_H & MAIN_A -->|compile| FirmwareBin

    FirmwareBin -->|flashed onto| OnChip
    FirmwareBin -->|flashed onto| OffChip

    OnChip -->|runs firmware↔| USB_IF
    USB_IF -->|interacts with| HostApp
    OnChip -->|captures| GNSS_FLOW
    GNSS_FLOW -->|stores to| STORAGE
    OnChip -->|measures| ADC_MEAS
    OnChip -->|schedules via| TIMER_IF

    %% Click events
    click Make_Snapper "https://github.com/snappergps/snappergps-firmware/tree/main/firmware_versions/snapper/build/Makefile"
    click Linker_Snapper "https://github.com/snappergps/snappergps-firmware/blob/main/firmware_versions/snapper/build/snapper.ld"
    click Make_Accel "https://github.com/snappergps/snappergps-firmware/tree/main/firmware_versions/snapper-accelerometer/build/Makefile"
    click Linker_Accel "https://github.com/snappergps/snappergps-firmware/blob/main/firmware_versions/snapper-accelerometer/build/snapper.ld"
    click CMSIS "https://github.com/snappergps/snappergps-firmware/tree/main/shared_library/cmsis"
    click DEVICE_INC "https://github.com/snappergps/snappergps-firmware/tree/main/shared_library/device/inc"
    click STARTUP "https://github.com/snappergps/snappergps-firmware/blob/main/shared_library/device/src/startup_efm32hg.s"
    click SYSTEM "https://github.com/snappergps/snappergps-firmware/blob/main/shared_library/device/src/system_efm32hg.c"
    click EMLIB_INC "https://github.com/snappergps/snappergps-firmware/tree/main/shared_library/emlib/inc"
    click EMLIB_SRC "https://github.com/snappergps/snappergps-firmware/tree/main/shared_library/emlib/src"
    click EMUSB_INC "https://github.com/snappergps/snappergps-firmware/tree/main/shared_library/emusb/inc"
    click EMUSB_SRC "https://github.com/snappergps/snappergps-firmware/tree/main/shared_library/emusb/src"
    click ADC "https://github.com/snappergps/snappergps-firmware/blob/main/shared_library/src/analogToDigitalConverter.c"
    click FLASH "https://github.com/snappergps/snappergps-firmware/blob/main/shared_library/src/flash.c"
    click RADIO "https://github.com/snappergps/snappergps-firmware/blob/main/shared_library/src/radio.c"
    click TIMER "https://github.com/snappergps/snappergps-firmware/blob/main/shared_library/src/timer.c"
    click USBCALL_S "https://github.com/snappergps/snappergps-firmware/blob/main/firmware_versions/snapper/inc/usbcallbacks.h"
    click USBCONF_S "https://github.com/snappergps/snappergps-firmware/blob/main/firmware_versions/snapper/inc/usbconfig.h"
    click USBDESC_S "https://github.com/snappergps/snappergps-firmware/blob/main/firmware_versions/snapper/inc/usbdescriptors.h"
    click MAIN_S "https://github.com/snappergps/snappergps-firmware/blob/main/firmware_versions/snapper/src/main.c"
    click ACCEL_H "https://github.com/snappergps/snappergps-firmware/blob/main/firmware_versions/snapper-accelerometer/inc/accelerometer.h"
    click USBCALL_A "https://github.com/snappergps/snappergps-firmware/blob/main/firmware_versions/snapper-accelerometer/inc/usbcallbacks.h"
    click USBCONF_A "https://github.com/snappergps/snappergps-firmware/blob/main/firmware_versions/snapper-accelerometer/inc/usbconfig.h"
    click USBDESC_A "https://github.com/snappergps/snappergps-firmware/blob/main/firmware_versions/snapper-accelerometer/inc/usbdescriptors.h"
    click ACCEL_C "https://github.com/snappergps/snappergps-firmware/blob/main/firmware_versions/snapper-accelerometer/src/accelerometer.c"
    click MAIN_A "https://github.com/snappergps/snappergps-firmware/blob/main/firmware_versions/snapper-accelerometer/src/main.c"

    %% Styles
    classDef build fill:#cce5ff,stroke:#004085,color:#004085;
    classDef code fill:#d4edda,stroke:#155724,color:#155724;
    classDef firmware fill:#ffe5b4,stroke:#cc8400,color:#cc8400;
    classDef hardware fill:#fff3cd,stroke:#856404,color:#856404;
    classDef interface fill:#f8d7da,stroke:#721c24,color:#721c24;
    classDef host fill:#e2e3e5,stroke:#6c757d,color:#6c757d;
```
