# lnc0831/1bitfm architecture

> Architecture diagram of the GitHub repository lnc0831/1bitfm, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lnc0831/1bitfm
- Repository: https://github.com/lnc0831/1bitfm

## Overview

1bitFM streams stereo PCM audio from a computer to a Zynq FPGA, where RTL produces a 1-bit FM waveform for an FM receiver. The main workflow is file/tone preparation, TCP transfer, firmware buffering and optional processing, DMA delivery, stereo FM encoding and RF serialization. A separate Simulink reference model covers algorithm-level modulation and demodulation. RTL connections are summarized from the README and tree; detailed implementation wiring was not sampled, so uncertain internal links are omitted.

Main entry points: [`rtl/fm_top.sv`](https://github.com/lnc0831/1bitfm/blob/main/rtl/fm_top.sv) (FPGA top), [`vitis/fm_app/src/main.c`](https://github.com/lnc0831/1bitfm/blob/main/vitis/fm_app/src/main.c) (Firmware service), [`simulink/runFmDemo.m`](https://github.com/lnc0831/1bitfm/blob/main/simulink/runFmDemo.m) (Simulation runner), [`rtl/fm_tx_core.sv`](https://github.com/lnc0831/1bitfm/blob/main/rtl/fm_tx_core.sv) (FM transmit core)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_source["Audio input"]
  node_sender["Audio sender<br/>[send-audio.py]"]
end

subgraph group_firmware["PS firmware"]
  node_firmware_main["Firmware service<br/>[main.c]"]
  node_audio_queue["PCM block queue<br/>[audio_queue.c]"]
  node_audio_processor["Audio processing<br/>[audio_processor.c]"]
  node_dma["AXI DMA<br/>[ps.bd]"]
end

subgraph group_pl["FPGA signal path"]
  node_pl_fifo["AXIS audio FIFO"]
  node_axis_rx["PCM AXIS receive<br/>[axis_pcm_rx.sv]"]
  node_stereo_dsp["Stereo DSP<br/>[stereo_dsp.sv]"]
  node_stereo_encoder["Stereo encoder<br/>[stereo_encoder.sv]"]
  node_tx_core["FM transmit core<br/>[fm_tx_core.sv]"]
  node_frequency_word["FM frequency word"]
  node_nco["FM NCO<br/>[fm_nco8.sv]"]
  node_serializer["RF serializer<br/>[fm_serializer.sv]"]
  node_fm_top["FPGA top<br/>[fm_top.sv]"]
end

subgraph group_reference["Reference model"]
  node_demo["Simulation runner<br/>[runFmDemo.m]"]
  node_model_builder["Model builder<br/>[buildFmModel.m]"]
  node_reference_chain["Reference signal chain<br/>[fm1bit_tx.slx]"]
  node_demod["Demodulation functions"]
end

node_computer(("Audio source"))
node_tcp(("TCP client"))
node_rf_output(("1-bit RF output"))
node_receiver(("FM receiver"))

node_computer -->|"provides audio"| node_sender
node_sender -->|"sends PCM"| node_tcp
node_tcp -->|"TCP stream"| node_firmware_main
node_firmware_main -->|"queues PCM"| node_audio_queue
node_firmware_main -->|"processes blocks"| node_audio_processor
node_firmware_main -->|"starts transfers"| node_dma
node_audio_queue -->|"supplies blocks"| node_firmware_main
node_dma -->|"streams AXIS"| node_pl_fifo
node_pl_fifo -->|"provides audio"| node_axis_rx
node_axis_rx -->|"feeds top-level path"| node_fm_top
node_fm_top -->|"routes PCM"| node_stereo_dsp
node_fm_top -->|"routes stereo audio"| node_stereo_encoder
node_fm_top -->|"routes transmit data"| node_tx_core
node_tx_core -->|"computes tuning word"| node_frequency_word
node_tx_core -->|"generates FM"| node_nco
node_fm_top -->|"routes serial output"| node_serializer
node_serializer -->|"emits serial bits"| node_rf_output
node_rf_output -->|"radiates waveform"| node_receiver
node_demo -->|"builds when needed"| node_model_builder
node_demo -->|"runs simulation"| node_reference_chain
node_demo -->|"checks reception"| node_demod

click node_sender "https://github.com/lnc0831/1bitfm/blob/main/scripts/send-audio.py"
click node_firmware_main "https://github.com/lnc0831/1bitfm/blob/main/vitis/fm_app/src/main.c"
click node_audio_queue "https://github.com/lnc0831/1bitfm/blob/main/vitis/fm_app/src/audio_queue.c"
click node_audio_processor "https://github.com/lnc0831/1bitfm/blob/main/vitis/fm_app/src/audio_processor.c"
click node_dma "https://github.com/lnc0831/1bitfm/blob/main/bd/ps/ps.bd"
click node_pl_fifo "https://github.com/lnc0831/1bitfm/blob/main/ip/audio_axis_fifo/audio_axis_fifo.xci"
click node_axis_rx "https://github.com/lnc0831/1bitfm/blob/main/rtl/axis_pcm_rx.sv"
click node_stereo_dsp "https://github.com/lnc0831/1bitfm/blob/main/rtl/stereo_dsp.sv"
click node_stereo_encoder "https://github.com/lnc0831/1bitfm/blob/main/rtl/stereo_encoder.sv"
click node_tx_core "https://github.com/lnc0831/1bitfm/blob/main/rtl/fm_tx_core.sv"
click node_frequency_word "https://github.com/lnc0831/1bitfm/blob/main/rtl/fm_frequency_word.sv"
click node_nco "https://github.com/lnc0831/1bitfm/blob/main/rtl/fm_nco8.sv"
click node_serializer "https://github.com/lnc0831/1bitfm/blob/main/rtl/fm_serializer.sv"
click node_fm_top "https://github.com/lnc0831/1bitfm/blob/main/rtl/fm_top.sv"
click node_demo "https://github.com/lnc0831/1bitfm/blob/main/simulink/runFmDemo.m"
click node_model_builder "https://github.com/lnc0831/1bitfm/blob/main/simulink/buildFmModel.m"
click node_reference_chain "https://github.com/lnc0831/1bitfm/blob/main/simulink/fm1bit_tx.slx"
click node_demod "https://github.com/lnc0831/1bitfm/blob/main/simulink/fmDownconvertFrame.m"

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_sender,node_tcp toneBlue
class node_firmware_main,node_audio_queue,node_audio_processor,node_dma toneAmber
class node_pl_fifo,node_axis_rx,node_stereo_dsp,node_stereo_encoder,node_tx_core,node_frequency_word,node_nco,node_serializer,node_fm_top toneMint
class node_demo,node_model_builder,node_reference_chain,node_demod toneRose
class node_computer,node_rf_output,node_receiver toneIndigo
```

## Components

### Audio input

- [Audio sender](https://github.com/lnc0831/1bitfm/blob/main/scripts/send-audio.py): `scripts/send-audio.py`

### PS firmware

- [Firmware service](https://github.com/lnc0831/1bitfm/blob/main/vitis/fm_app/src/main.c): `vitis/fm_app/src/main.c`
- [PCM block queue](https://github.com/lnc0831/1bitfm/blob/main/vitis/fm_app/src/audio_queue.c): `vitis/fm_app/src/audio_queue.c`
- [Audio processing](https://github.com/lnc0831/1bitfm/blob/main/vitis/fm_app/src/audio_processor.c): `vitis/fm_app/src/audio_processor.c`
- [AXI DMA](https://github.com/lnc0831/1bitfm/blob/main/bd/ps/ps.bd): `bd/ps/ps.bd`

### FPGA signal path

- [AXIS audio FIFO](https://github.com/lnc0831/1bitfm/blob/main/ip/audio_axis_fifo/audio_axis_fifo.xci): `ip/audio_axis_fifo/audio_axis_fifo.xci`
- [PCM AXIS receive](https://github.com/lnc0831/1bitfm/blob/main/rtl/axis_pcm_rx.sv): `rtl/axis_pcm_rx.sv`
- [Stereo DSP](https://github.com/lnc0831/1bitfm/blob/main/rtl/stereo_dsp.sv): `rtl/stereo_dsp.sv`
- [Stereo encoder](https://github.com/lnc0831/1bitfm/blob/main/rtl/stereo_encoder.sv): `rtl/stereo_encoder.sv`
- [FM transmit core](https://github.com/lnc0831/1bitfm/blob/main/rtl/fm_tx_core.sv): `rtl/fm_tx_core.sv`
- [FM frequency word](https://github.com/lnc0831/1bitfm/blob/main/rtl/fm_frequency_word.sv): `rtl/fm_frequency_word.sv`
- [FM NCO](https://github.com/lnc0831/1bitfm/blob/main/rtl/fm_nco8.sv): `rtl/fm_nco8.sv`
- [RF serializer](https://github.com/lnc0831/1bitfm/blob/main/rtl/fm_serializer.sv): `rtl/fm_serializer.sv`
- [FPGA top](https://github.com/lnc0831/1bitfm/blob/main/rtl/fm_top.sv): `rtl/fm_top.sv`

### Reference model

- [Simulation runner](https://github.com/lnc0831/1bitfm/blob/main/simulink/runFmDemo.m): `simulink/runFmDemo.m`
- [Model builder](https://github.com/lnc0831/1bitfm/blob/main/simulink/buildFmModel.m): `simulink/buildFmModel.m`
- [Reference signal chain](https://github.com/lnc0831/1bitfm/blob/main/simulink/fm1bit_tx.slx): `simulink/fm1bit_tx.slx`
- [Demodulation functions](https://github.com/lnc0831/1bitfm/blob/main/simulink/fmDownconvertFrame.m): `simulink/fmDownconvertFrame.m`

### Other components

- **Audio source**
- **TCP client**
- **1-bit RF output**
- **FM receiver**

## Connections

- Audio source → Audio sender: provides audio
- Audio sender → TCP client: sends PCM
- TCP client → Firmware service: TCP stream
- Firmware service → PCM block queue: queues PCM
- Firmware service → Audio processing: processes blocks
- Firmware service → AXI DMA: starts transfers
- PCM block queue → Firmware service: supplies blocks
- AXI DMA → AXIS audio FIFO: streams AXIS
- AXIS audio FIFO → PCM AXIS receive: provides audio
- PCM AXIS receive → FPGA top: feeds top-level path
- FPGA top → Stereo DSP: routes PCM
- FPGA top → Stereo encoder: routes stereo audio
- FPGA top → FM transmit core: routes transmit data
- FM transmit core → FM frequency word: computes tuning word
- FM transmit core → FM NCO: generates FM
- FPGA top → RF serializer: routes serial output
- RF serializer → 1-bit RF output: emits serial bits
- 1-bit RF output → FM receiver: radiates waveform
- Simulation runner → Model builder: builds when needed
- Simulation runner → Reference signal chain: runs simulation
- Simulation runner → Demodulation functions: checks reception