# ryzee119/hawk architecture

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

- Interactive diagram: https://gitdiagram.com/ryzee119/hawk
- Repository: https://github.com/ryzee119/hawk

## Overview

##### Project type and purpose
- Hawk is an open-source hardware/firmware replacement of the Xbox Live Communicator.
- It comprises a custom PCB (KiCad files under hardware/), a BOM/gerbers (kitspace/), and embedded firmware (src/).

##### File structure
- hardware/… — KiCad schematic and PCB layout, part libraries, footprints.
- kitspace/… — Gerber outputs and BOM for manufacturing.
- src/… — Firmware source, broken into:
– HAL and system startup (stm32g4xx/)
– USB device stack (usbd/)
– I²S audio codec driver (max9860/)
– EEPROM emulation (eeprom_emulation/)
– FIFO buffer (fifo.c/h)
– Application entrypoint (main.c)
– Syscalls, memory (syscalls.c, sysmem.c)
- platformio.ini — Build configuration.

##### Pull insights from the README
- Main MCU: STM32G431 series
- Audio codec: MAX9860
- Physical I/O: push-button, LED, 3.5 mm TRRS jack
- Interfaces: Xbox controller port (USB 1.1), DFU via USB, ST-Link header

##### Main components
A. Hardware Blocks
1. STM32G431 MCU
2. MAX9860 audio codec
3. TRRS headset jack
4. Volume/mode button
5. Status LED
6. USB D+ / D– lines
7. ST-Link 5-pin header
B. Firmware Layers
1. STM32 HAL + startup code (stm32g4xx_*.c)
2. USB device stack (usbd_conf, xblc)
3. Audio codec driver (max9860.c/h)
4. FIFO buffering (fifo.c/h)
5. EEPROM emulation (ee.c/h)
6. Application logic (main.c/h)
7. System calls / memory (syscalls.c, sysmem.c)

##### Relationships and data flows
- USB↔STM32 USB‐Device Stack ↔ Application Logic
- Application Logic ↔ EEPROM Emulation (persistent volume & gain)
- Application Logic ↔ FIFO ↔ MAX9860 Codec ↔ TRRS Jack
- Application Logic ↔ LED PWM (volume indication)
- Button GPIO → Application Logic (interrupts or polling)
- DFU Mode: USB DFU Bootloader (via USB lines)
- ST-Link: programming/debug directly into STM32

##### Architectural patterns
- Layered embedded design
– Hardware Abstraction Layer (stm32g4xx_hal_*)
– Middleware (USB stack)
– Device drivers (max9860, fifo)
– Application layer (main.c)
- Separation of concerns: I/O drivers vs. business logic vs. persistence
- Non-volatile emulation: eeprom_emulation stores settings in flash

##### Essential elements
- Blocks: MCU, codec, button, LED, jack, USB host, ST-Link
- Firmware layers and key modules (HAL, USB, max9860 driver, eeprom_emulation, app)
– USB host→MCU USB stack→app
– app→codec driver→codec↔TRRS
– button→app; app→LED
– app↔eeprom_emulation
- Annotations: mention PlatformIO (platformio.ini) and KiCad files as build inputs

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Entities
    USB_HOST("USB Host"):::external
    HEADSET("Headset (External)"):::external

    %% Hardware Blocks
    subgraph "Hardware Blocks"
        direction TB
        MCU["STM32G431 MCU"]:::hardware
        CODEC["MAX9860 Audio Codec"]:::hardware
        JACK["TRRS Headset Jack"]:::hardware
        BUTTON["Push-button"]:::hardware
        LED["Status LED"]:::hardware
        USB_LINES["USB D+/D- Lines"]:::hardware
        STLINK["ST-Link Header"]:::hardware
    end

    %% Firmware Layers
    subgraph "Firmware Layers"
        direction TB
        HAL["STM32 HAL & Startup"]:::firmware
        SYSCALLS["Syscalls & Memory"]:::firmware
        USBSTACK["USB Device Stack"]:::firmware
        subgraph "Device Drivers"
            direction TB
            CODEC_DRV["MAX9860 Driver"]:::firmware
            FIFO["FIFO Buffer"]:::firmware
            EEPROM["EEPROM Emulation"]:::firmware
        end
        APP["Application Logic"]:::firmware
    end

    %% Build & Design Artifacts
    PLATFORMIO["platformio.ini"]:::docs
    KICAD["KiCad Files (hardware/)"]:::docs
    PARTS["Hardware Parts (hardware/parts/)"]:::docs
    KITSPACE["Manufacturing Artifacts (.kitspace/)"]:::docs
    BOARDS["Board Definition (boards/hawk_stm32g431.json)"]:::docs

    %% Connections: External to Hardware
    USB_HOST --> USB_LINES
    HEADSET --> JACK

    %% Hardware to Firmware
    USB_LINES --> MCU
    MCU --> USBSTACK
    MCU --> HAL
    MCU --> STLINK
    MCU --> CODEC
    CODEC --> JACK
    BUTTON --> APP
    APP --> LED

    %% Firmware Data Flows
    USBSTACK --> APP
    APP --> FIFO
    FIFO --> CODEC_DRV
    CODEC_DRV --> CODEC
    APP --> EEPROM
    APP --> SYSCALLS
    SYSCALLS --> HAL

    %% Artifact Links
    PLATFORMIO --> HAL
    KICAD --> MCU
    PARTS --> CODEC
    KITSPACE --> KICAD
    BOARDS --> PLATFORMIO

    %% Click Events
    click HAL "https://github.com/ryzee119/hawk/tree/master/src/stm32g4xx/"
    click USBSTACK "https://github.com/ryzee119/hawk/tree/master/src/usbd/"
    click CODEC_DRV "https://github.com/ryzee119/hawk/tree/master/src/max9860/"
    click FIFO "https://github.com/ryzee119/hawk/blob/master/src/fifo.c"
    click EEPROM "https://github.com/ryzee119/hawk/tree/master/src/eeprom_emulation/"
    click APP "https://github.com/ryzee119/hawk/blob/master/src/main.c"
    click SYSCALLS "https://github.com/ryzee119/hawk/blob/master/src/syscalls.c"
    click PLATFORMIO "https://github.com/ryzee119/hawk/blob/master/platformio.ini"
    click KICAD "https://github.com/ryzee119/hawk/tree/master/hardware/"
    click PARTS "https://github.com/ryzee119/hawk/tree/master/hardware/parts/"
    click KITSPACE "https://github.com/ryzee119/hawk/tree/master/.kitspace/"
    click BOARDS "https://github.com/ryzee119/hawk/blob/master/boards/hawk_stm32g431.json"

    %% Styles
    classDef hardware fill:#ccf,stroke:#339,stroke-width:1px
    classDef firmware fill:#cfc,stroke:#393,stroke-width:1px,stroke-dasharray: 5 5
    classDef external fill:#fc9,stroke:#f60,stroke-width:1px
    classDef docs fill:#ffc,stroke:#aa0,stroke-width:1px,stroke-dasharray: 2 2
```
