# darderik/relay_matrix_edsp architecture

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

- Interactive diagram: https://gitdiagram.com/darderik/relay_matrix_edsp
- Repository: https://github.com/darderik/relay_matrix_edsp

## Overview

##### Project Type and Purpose
- This is an embedded firmware project for an STM32F401 microcontroller that implements a SCPI‐like command interface over USB-serial to control a 4×4 relay matrix via TPL9201 SPI-driven MOSFET arrays, with ATX power-supply integration and basic power management.

##### Main System Components
a. Hardware Blocks:
- ATX Power Supply (12 V for relays, PS_ON & PWR_OK GPIO lines)
- TPL9201 Driver ICs (Groups A–D, each with NCS & NRST lines)
- Relay Matrix (4×4 crosspoint relays)
- STM32F401XE MCU with UART and SPI peripherals
b. Software Modules (inside MCU):
- HAL/CMSIS Layer (drivers for clock, GPIO, SPI, UART, interrupts)
- “Callbacks” module (UART RX/TX interrupt handlers)
- Parser component (SCPI-like command parsing)
- Command Queue (buffered commands)
- Interpreter (executes parsed commands)
- Actions module (high-level relay control logic)
- NanoTimer (for time-outs and scheduling)
- FSM (system state management: PASSIVE/ACTIVE/ERROR)
- Status Monitor & Response Queue

##### Relationships & Data Flow
- Serial data arrives on UART → UART RX callback → Parser → command enqueued in Command Queue
- Interpreter dequeues commands → invokes Actions → via STM32 SPI driver → TPL9201 → Relay Matrix
- FSM observes power state (PWR_OK) and interpreter events to switch PSU on/off (via PS_ON GPIO)
- Status Monitor reads current matrix state → enqueues status messages in Response Queue → UART TX callback → PC

##### Architectural Patterns & Design Principles
- Layered architecture: HAL/CMSIS low-level drivers at bottom, device-specific “components” above, application logic at top
- Modular components: each function (parser, queue, interpreter, actions, FSM) encapsulated in its own folder
- Producer–consumer queues for decoupling parsing, execution, and status reporting
- Finite State Machine controlling global power and error handling

##### Relevant Technologies & Frameworks
- STM32Cube HAL / CMSIS for peripheral abstraction
- C modules for each “component” (Core/Src/components/*)
- Makefile / VS Code tasks for build and flash
- SCPI-style commands over USB-serial (115200 baud)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Hardware Layer
    subgraph "Hardware Layer"
        direction TB
        ATX_PSU["ATX Power Supply"]:::hardware
        TPL_A["TPL9201 Group A"]:::hardware
        TPL_B["TPL9201 Group B"]:::hardware
        TPL_C["TPL9201 Group C"]:::hardware
        TPL_D["TPL9201 Group D"]:::hardware
        Relay_Matrix["Relay Matrix (4×4)"]:::hardware
    end

    %% MCU Software Layer
    subgraph "MCU Software Layer"
        direction TB
        Main["main.c"]:::software
        Callbacks["Callbacks Module"]:::software
        Parser["Parser Component"]:::software
        UQ["Unparsed Command Queue"]:::queue
        IQ["Interpreter & Exec Queue"]:::queue
        Interpreter["Interpreter"]:::software
        Actions["Actions Module"]:::software
        NanoTimer["NanoTimer"]:::software
        FSM["Finite State Machine"]:::software
        StatusMon["Status Monitor"]:::software
        RespQ["Response Queue"]:::queue
        HAL["HAL/CMSIS Layer"]:::software
    end

    %% External PC
    PC["PC (USB-Serial)"]:::external

    %% Command Flow
    PC -->|"SCPI command"| Callbacks
    Main -->|start| Callbacks
    Callbacks -->|"UART RX interrupt"| Parser
    Parser -->|"parsed tokens"| UQ
    UQ -->|"dequeue command"| IQ
    IQ -->|"invoke actions"| Actions
    Actions -->|"SPI frame"| HAL
    HAL -->|"SPI1, NCS/NRST"| TPL_A
    HAL -->|"SPI1, NCS/NRST"| TPL_B
    HAL -->|"SPI1, NCS/NRST"| TPL_C
    HAL -->|"SPI1, NCS/NRST"| TPL_D
    TPL_A -->|"drive MOSFETs"| Relay_Matrix
    TPL_B -->|"drive MOSFETs"| Relay_Matrix
    TPL_C -->|"drive MOSFETs"| Relay_Matrix
    TPL_D -->|"drive MOSFETs"| Relay_Matrix

    %% Power and State Control
    FSM <-->|"PS_ON / PWR_OK"| ATX_PSU
    FSM -->|"state events"| Interpreter
    FSM -->|"state events"| Actions
    NanoTimer -->|"timeouts / schedule"| Interpreter
    NanoTimer -->|"timeouts / schedule"| Actions

    %% Status/Response Flow
    Relay_Matrix -->|"read state"| StatusMon
    StatusMon -->|"status message"| RespQ
    RespQ -->|"UART TX interrupt"| Callbacks
    Callbacks -->|"serial out"| PC

    %% Click Events
    click HAL "https://github.com/darderik/relay_matrix_edsp/tree/main/Drivers/STM32F4xx_HAL_Driver"
    click Callbacks "https://github.com/darderik/relay_matrix_edsp/blob/main/Core/Src/components/peripherals/callbacks.c"
    click Parser "https://github.com/darderik/relay_matrix_edsp/blob/main/Core/Src/components/parser/parser.c"
    click UQ "https://github.com/darderik/relay_matrix_edsp/blob/main/Core/Src/components/queues/ucq/unparsed_command_queue.c"
    click IQ "https://github.com/darderik/relay_matrix_edsp/blob/main/Core/Src/components/queues/isq/interpreter.c"
    click RespQ "https://github.com/darderik/relay_matrix_edsp/blob/main/Core/Src/components/queues/isq/interpreter_status_queue.c"
    click Actions "https://github.com/darderik/relay_matrix_edsp/blob/main/Core/Src/components/actions/actions.c"
    click NanoTimer "https://github.com/darderik/relay_matrix_edsp/blob/main/Core/Src/components/nanotimer/nanotimer.c"
    click FSM "https://github.com/darderik/relay_matrix_edsp/blob/main/Core/Src/components/fsm/fsm.c"
    click Main "https://github.com/darderik/relay_matrix_edsp/blob/main/Core/Src/main.c"

    %% Styles
    classDef hardware fill:#ADD8E6,stroke:#000;
    classDef software fill:#98FB98,stroke:#000;
    classDef queue fill:#FFD700,stroke:#000;
    classDef external fill:#FFA500,stroke:#000;
```
