# ntue2719-commits/secded-bpsk-fpga architecture

> Architecture diagram of the GitHub repository ntue2719-commits/secded-bpsk-fpga, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ntue2719-commits/secded-bpsk-fpga
- Repository: https://github.com/ntue2719-commits/secded-bpsk-fpga

## Overview

This repository implements a deterministic FPGA SECDED/BPSK communication system, with a Python Golden Model and generated reference vectors supporting RTL verification. The principal workflow receives UART configuration and data, processes each nibble through the six-stage DSP pipeline, then returns packed result and status bytes over UART. The graph follows the documented architecture; unsampled RTL details are represented only where the README explicitly describes the connection.

Main entry points: [`rtl/tx_rx_dsp_top.v`](https://github.com/ntue2719-commits/secded-bpsk-fpga/blob/main/rtl/tx_rx_dsp_top.v) (DSP pipeline integration), [`rtl/uart_controller.v`](https://github.com/ntue2719-commits/secded-bpsk-fpga/blob/main/rtl/uart_controller.v) (UART controller), [`python/export_hex.py`](https://github.com/ntue2719-commits/secded-bpsk-fpga/blob/main/python/export_hex.py) (Vector exporter), [`rtl/uart_rx.v`](https://github.com/ntue2719-commits/secded-bpsk-fpga/blob/main/rtl/uart_rx.v) (UART receiver)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["UART interface"]
  node_uart_rx["UART receiver<br/>[uart_rx.v]"]
  node_controller["UART controller<br/>[uart_controller.v]"]
  node_fpga_top["FPGA top<br/>[fpga_top.v]"]
  node_uart_tx["UART transmitter<br/>[uart_tx.v]"]
end

subgraph group_dsp["DSP pipeline"]
  node_dsp_top["DSP pipeline integration<br/>[tx_rx_dsp_top.v]"]
  node_encoder["SECDED encoder<br/>[hamming_encoder.v]"]
  node_error_channel["Bit-flip channel<br/>[bit_flip_channel.v]"]
  node_modulator["BPSK modulator<br/>[bpsk_modulator.v]"]
  node_noise["LFSR noise injector"]
  node_demodulator["BPSK demodulator<br/>[bpsk_demodulator.v]"]
  node_decoder["SECDED decoder<br/>[hamming_decoder.v]"]
end

subgraph group_reference["Reference model"]
  node_golden_model["Stateful Golden Model<br/>[golden_model.py]"]
  node_exporter["Vector exporter<br/>[export_hex.py]"]
end

subgraph group_vectors["Verification data"]
  node_data["Reference vectors"]
end

node_host(("UART host"))

node_host -->|"sends serial data"| node_uart_rx
node_uart_rx -->|"delivers received bytes"| node_controller
node_controller -->|"processes nibbles"| node_dsp_top
node_dsp_top -->|"encodes payload"| node_encoder
node_dsp_top -->|"injects bit errors"| node_error_channel
node_dsp_top -->|"maps to BPSK"| node_modulator
node_dsp_top -->|"adds noise"| node_noise
node_dsp_top -->|"demodulates samples"| node_demodulator
node_dsp_top -->|"decodes codeword"| node_decoder
node_controller -->|"transmits packed response"| node_uart_tx
node_uart_tx -->|"returns serial response"| node_host
node_exporter -->|"generates from"| node_golden_model
node_exporter -->|"writes vectors"| node_data

click node_uart_rx "https://github.com/ntue2719-commits/secded-bpsk-fpga/blob/main/rtl/uart_rx.v"
click node_controller "https://github.com/ntue2719-commits/secded-bpsk-fpga/blob/main/rtl/uart_controller.v"
click node_fpga_top "https://github.com/ntue2719-commits/secded-bpsk-fpga/blob/main/rtl/fpga_top.v"
click node_uart_tx "https://github.com/ntue2719-commits/secded-bpsk-fpga/blob/main/rtl/uart_tx.v"
click node_dsp_top "https://github.com/ntue2719-commits/secded-bpsk-fpga/blob/main/rtl/tx_rx_dsp_top.v"
click node_encoder "https://github.com/ntue2719-commits/secded-bpsk-fpga/blob/main/rtl/hamming_encoder.v"
click node_error_channel "https://github.com/ntue2719-commits/secded-bpsk-fpga/blob/main/rtl/bit_flip_channel.v"
click node_modulator "https://github.com/ntue2719-commits/secded-bpsk-fpga/blob/main/rtl/bpsk_modulator.v"
click node_noise "https://github.com/ntue2719-commits/secded-bpsk-fpga/blob/main/rtl/lfsr_noise_injector.v"
click node_demodulator "https://github.com/ntue2719-commits/secded-bpsk-fpga/blob/main/rtl/bpsk_demodulator.v"
click node_decoder "https://github.com/ntue2719-commits/secded-bpsk-fpga/blob/main/rtl/hamming_decoder.v"
click node_golden_model "https://github.com/ntue2719-commits/secded-bpsk-fpga/blob/main/python/golden_model.py"
click node_exporter "https://github.com/ntue2719-commits/secded-bpsk-fpga/blob/main/python/export_hex.py"
click node_data "https://github.com/ntue2719-commits/secded-bpsk-fpga/tree/main/data"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_uart_rx,node_controller,node_fpga_top,node_uart_tx toneBlue
class node_dsp_top,node_encoder,node_error_channel,node_modulator,node_noise,node_demodulator,node_decoder toneAmber
class node_golden_model,node_exporter toneMint
class node_data toneRose
class node_host toneIndigo
```

## Components

### UART interface

- [UART receiver](https://github.com/ntue2719-commits/secded-bpsk-fpga/blob/main/rtl/uart_rx.v): `rtl/uart_rx.v`
- [UART controller](https://github.com/ntue2719-commits/secded-bpsk-fpga/blob/main/rtl/uart_controller.v): `rtl/uart_controller.v`
- [FPGA top](https://github.com/ntue2719-commits/secded-bpsk-fpga/blob/main/rtl/fpga_top.v): `rtl/fpga_top.v`
- [UART transmitter](https://github.com/ntue2719-commits/secded-bpsk-fpga/blob/main/rtl/uart_tx.v): `rtl/uart_tx.v`

### DSP pipeline

- [DSP pipeline integration](https://github.com/ntue2719-commits/secded-bpsk-fpga/blob/main/rtl/tx_rx_dsp_top.v): `rtl/tx_rx_dsp_top.v`
- [SECDED encoder](https://github.com/ntue2719-commits/secded-bpsk-fpga/blob/main/rtl/hamming_encoder.v): `rtl/hamming_encoder.v`
- [Bit-flip channel](https://github.com/ntue2719-commits/secded-bpsk-fpga/blob/main/rtl/bit_flip_channel.v): `rtl/bit_flip_channel.v`
- [BPSK modulator](https://github.com/ntue2719-commits/secded-bpsk-fpga/blob/main/rtl/bpsk_modulator.v): `rtl/bpsk_modulator.v`
- [LFSR noise injector](https://github.com/ntue2719-commits/secded-bpsk-fpga/blob/main/rtl/lfsr_noise_injector.v): `rtl/lfsr_noise_injector.v`
- [BPSK demodulator](https://github.com/ntue2719-commits/secded-bpsk-fpga/blob/main/rtl/bpsk_demodulator.v): `rtl/bpsk_demodulator.v`
- [SECDED decoder](https://github.com/ntue2719-commits/secded-bpsk-fpga/blob/main/rtl/hamming_decoder.v): `rtl/hamming_decoder.v`

### Reference model

- [Stateful Golden Model](https://github.com/ntue2719-commits/secded-bpsk-fpga/blob/main/python/golden_model.py): `python/golden_model.py`
- [Vector exporter](https://github.com/ntue2719-commits/secded-bpsk-fpga/blob/main/python/export_hex.py): `python/export_hex.py`

### Verification data

- [Reference vectors](https://github.com/ntue2719-commits/secded-bpsk-fpga/tree/main/data): `data`

### Other components

- **UART host**

## Connections

- UART host → UART receiver: sends serial data (evidence: `README.md`)
- UART receiver → UART controller: delivers received bytes (evidence: `README.md`)
- UART controller → DSP pipeline integration: processes nibbles (evidence: `README.md`)
- DSP pipeline integration → SECDED encoder: encodes payload (evidence: `README.md`)
- DSP pipeline integration → Bit-flip channel: injects bit errors (evidence: `README.md`)
- DSP pipeline integration → BPSK modulator: maps to BPSK (evidence: `README.md`)
- DSP pipeline integration → LFSR noise injector: adds noise (evidence: `README.md`)
- DSP pipeline integration → BPSK demodulator: demodulates samples (evidence: `README.md`)
- DSP pipeline integration → SECDED decoder: decodes codeword (evidence: `README.md`)
- UART controller → UART transmitter: transmits packed response (evidence: `README.md`)
- UART transmitter → UART host: returns serial response (evidence: `README.md`)
- Vector exporter → Stateful Golden Model: generates from (evidence: `python/export_hex.py`)
- Vector exporter → Reference vectors: writes vectors (evidence: `python/export_hex.py`)