# tahmid-mahmud-fahim/fpga-based-plc-programmable-logic-controller- architecture

> Architecture diagram of the GitHub repository tahmid-mahmud-fahim/fpga-based-plc-programmable-logic-controller-, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tahmid-mahmud-fahim/fpga-based-plc-programmable-logic-controller-
- Repository: https://github.com/tahmid-mahmud-fahim/fpga-based-plc-programmable-logic-controller-

## Overview

1. **Project purpose**
   - This repository implements a **soft PLC in Verilog** for the **Digilent Nexys A7-100T** FPGA. The design lets a user create and run ladder-logic programs directly on the board, without a PC-based programming tool.

2. **Top-level architecture**
   - The main system boundary is the top module, `src/plc_multi_rung_top.v`.
   - It contains the **program storage**, **edit-mode UI**, **run-mode scan engine**, runtime state registers, and the logic that drives LEDs and the seven-segment display.

3. **Input front-end**
   - Physical switches and pushbuttons enter the design through `debounce_onepulse.v`.
   - This module filters switch/button bounce and converts button presses into clean single-cycle pulses, which is important because the rest of the PLC logic is synchronous and page-driven.

4. **Clocking and timing**
   - `tick_gen.v` derives slower timing events from the board’s **100 MHz clock**.
   - The README indicates these ticks support the PLC’s **1 ms timing base** for timers and also generate a display refresh tick for the multiplexed seven-segment output.

5. **PLC execution model**
   - The controller follows a standard **scan-cycle** model: inputs are sampled, ladder rungs are evaluated from top to bottom, and outputs/state are updated synchronously.
   - Runtime state includes **outputs (Q)**, **markers (M)**, **timers**, and **counters**, all stored internally in the FPGA fabric.

6. **Program representation**
   - The ladder program is stored on-chip as a structured grid:
     - up to **8 rungs**
     - **3 parallel lanes** per rung
     - **7 cells** per lane
   - Each cell can represent empty space, wire, normally-open contact, or normally-closed contact, with sources drawn from inputs, outputs, markers, and done bits from timers/counters.

7. **Edit-mode subsystem**
   - The board has a **page-based editor** controlled by switches and pushbuttons.
   - In edit mode, the user can select a rung/lane/column coordinate, write or delete cells, assign rung actions, set preset values, and trigger service operations like loading a demo program or clearing memory.
   - This is an important architectural boundary: the same physical controls are reused across multiple pages, so the UI layer is part of the top-level controller rather than a separate module.

8. **Run-mode subsystem**
   - In run mode, the design maps physical board inputs to PLC inputs and continuously evaluates the ladder program.
   - Outputs and internal states are then reflected to LEDs and the seven-segment display.
   - The run-mode view is intended for live observation rather than configuration, so it exposes active rung state, outputs, markers, and status flags.

9. **Output and visualization path**
   - `sevenseg_driver.v` handles the **8-digit seven-segment display** using time-division multiplexing.
   - LEDs provide a simpler status channel: some bits show physical inputs, while others show rung-visible results and system status such as validity, dirty state, and error indication.

10. **Timing-sensitive industrial logic blocks**
   - The PLC supports **TON**, **TOF**, **CTU**, and reset instructions, meaning the top module must maintain internal time and count state across scans.
   - Done bits from timers and counters feed back into the ladder evaluation path, which creates a closed control loop between the scan engine and the stored runtime state.

11. **Repository structure**
   - `src/` contains the synthesizable design files.
   - `constraints/plc_multi_rung_top_xdc.xdc` provides the pin mapping for the Nexys A7 board.
   - `docs/EEE304-Jul2025-B1-G05.pdf` is the full project report and likely contains deeper design rationale, state diagrams, and implementation results.

12. **Architectural constraints and status**
   - The design is a **functional educational prototype** rather than a production PLC.
   - The README notes that the build does **not meet 100 MHz timing closure**, so an architecture diagram should show the system as functionally complete but timing-limited.
   - Program storage is also **volatile**, meaning the ladder program lives only in FPGA state and is lost on reset or power-off.

Main entry points: [`src/plc_multi_rung_top.v`](https://github.com/tahmid-mahmud-fahim/fpga-based-plc-programmable-logic-controller-/blob/main/src/plc_multi_rung_top.v) (PLC top), [`src/debounce_onepulse.v`](https://github.com/tahmid-mahmud-fahim/fpga-based-plc-programmable-logic-controller-/blob/main/src/debounce_onepulse.v) (Debounce), [`src/tick_gen.v`](https://github.com/tahmid-mahmud-fahim/fpga-based-plc-programmable-logic-controller-/blob/main/src/tick_gen.v) (Tick gen), [`constraints/plc_multi_rung_top_xdc.xdc`](https://github.com/tahmid-mahmud-fahim/fpga-based-plc-programmable-logic-controller-/blob/main/constraints/plc_multi_rung_top_xdc.xdc) (XDC)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_src["src"]
  node_n_top["PLC top<br/>top controller"]
  node_n_debounce["Debounce<br/>input filter"]
  node_n_tick["Tick gen<br/>timing base<br/>[tick_gen.v]"]
  node_n_editor["Editor UI<br/>page-based UI"]
  node_n_program[("Program store<br/>ladder memory")]
  node_n_scan["Scan engine<br/>ladder evaluator"]
  node_n_runtime[("Runtime state<br/>PLC state")]
  node_n_timers["Timers<br/>TON/TOF"]
  node_n_counters["Counters<br/>CTU/reset"]
  node_n_display["7-seg driver<br/>display mux<br/>[sevenseg_driver.v]"]
end

subgraph group_group_board["board"]
  node_n_input["Inputs<br/>board I/O"]
  node_n_clock(("100 MHz<br/>board clock"))
  node_n_leds(("LED output<br/>status display"))
  node_n_constraints["XDC<br/>pin mapping"]
end

subgraph group_group_docs["docs"]
  node_n_report["Project report<br/>documentation"]
end

node_n_input -->|"buttons/switches"| node_n_debounce
node_n_clock -->|"clock"| node_n_tick
node_n_debounce -->|"events"| node_n_top
node_n_tick -->|"ticks"| node_n_top
node_n_top -->|"edit mode"| node_n_editor
node_n_top -->|"store/update"| node_n_program
node_n_program -->|"ladder grid"| node_n_scan
node_n_runtime -->|"state in"| node_n_scan
node_n_scan -->|"state out"| node_n_runtime
node_n_timers -->|"done bits"| node_n_runtime
node_n_counters -->|"done bits"| node_n_runtime
node_n_runtime -->|"time state"| node_n_timers
node_n_runtime -->|"count state"| node_n_counters
node_n_top -->|"TON/TOF"| node_n_timers
node_n_top -->|"CTU/reset"| node_n_counters
node_n_top -->|"segments"| node_n_display
node_n_top -->|"status LEDs"| node_n_leds
node_n_constraints -.->|"pins"| node_n_top
node_n_report -.->|"design context"| node_n_top

click node_n_top "https://github.com/tahmid-mahmud-fahim/fpga-based-plc-programmable-logic-controller-/blob/main/src/plc_multi_rung_top.v"
click node_n_debounce "https://github.com/tahmid-mahmud-fahim/fpga-based-plc-programmable-logic-controller-/blob/main/src/debounce_onepulse.v"
click node_n_tick "https://github.com/tahmid-mahmud-fahim/fpga-based-plc-programmable-logic-controller-/blob/main/src/tick_gen.v"
click node_n_display "https://github.com/tahmid-mahmud-fahim/fpga-based-plc-programmable-logic-controller-/blob/main/src/sevenseg_driver.v"
click node_n_constraints "https://github.com/tahmid-mahmud-fahim/fpga-based-plc-programmable-logic-controller-/blob/main/constraints/plc_multi_rung_top_xdc.xdc"
click node_n_report "https://github.com/tahmid-mahmud-fahim/fpga-based-plc-programmable-logic-controller-/blob/main/docs/EEE304-Jul2025-B1-G05.pdf"

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_n_top,node_n_debounce,node_n_tick,node_n_editor,node_n_program,node_n_scan,node_n_runtime,node_n_timers,node_n_counters,node_n_display toneBlue
class node_n_input,node_n_clock,node_n_leds,node_n_constraints toneAmber
class node_n_report toneMint
```

## Components

### src

Synthesizable FPGA design modules

- [PLC top](https://github.com/tahmid-mahmud-fahim/fpga-based-plc-programmable-logic-controller-/blob/main/src/plc_multi_rung_top.v): top controller · Main soft-PLC system boundary: edit mode, scan cycle, runtime state, and display/LED control · `src/plc_multi_rung_top.v`
- [Debounce](https://github.com/tahmid-mahmud-fahim/fpga-based-plc-programmable-logic-controller-/blob/main/src/debounce_onepulse.v): input filter · Debounces switches/buttons and emits clean one-pulse events · `src/debounce_onepulse.v`
- [Tick gen](https://github.com/tahmid-mahmud-fahim/fpga-based-plc-programmable-logic-controller-/blob/main/src/tick_gen.v): timing base · Derives slower scan and refresh timing from the 100 MHz clock · `src/tick_gen.v`
- **Editor UI**: page-based UI · Multi-page edit-mode control for rung/lane/cell programming and service actions
- **Program store**: ladder memory · Volatile on-chip storage for up to 8 rungs x 3 lanes x 7 cells
- **Scan engine**: ladder evaluator · Evaluates rungs top-to-bottom and updates outputs/state synchronously
- **Runtime state**: PLC state · Internal Q/M bits plus timer and counter state retained across scans
- **Timers**: TON/TOF · Timing instructions driven by the PLC timing base
- **Counters**: CTU/reset · Count and reset instructions used by the ladder program
- [7-seg driver](https://github.com/tahmid-mahmud-fahim/fpga-based-plc-programmable-logic-controller-/blob/main/src/sevenseg_driver.v): display mux · Time-multiplexed 8-digit seven-segment display driver · `src/sevenseg_driver.v`

### board

Board integration and physical I/O

- **Inputs**: board I/O · Physical switches and pushbuttons entering the PLC
- **100 MHz**: board clock · Nexys A7 master clock source
- **LED output**: status display · LED indicators for inputs, rung-visible results, and system status
- [XDC](https://github.com/tahmid-mahmud-fahim/fpga-based-plc-programmable-logic-controller-/blob/main/constraints/plc_multi_rung_top_xdc.xdc): pin mapping · Nexys A7 pin and I/O constraints · `constraints/plc_multi_rung_top_xdc.xdc`

### docs

Reference and project documentation

- [Project report](https://github.com/tahmid-mahmud-fahim/fpga-based-plc-programmable-logic-controller-/blob/main/docs/EEE304-Jul2025-B1-G05.pdf): documentation · Full design report and implementation rationale · `docs/EEE304-Jul2025-B1-G05.pdf`

## Connections

- Inputs → Debounce: buttons/switches · Raw board inputs are filtered before use
- 100 MHz → Tick gen: clock · System clock feeds timing generation
- Debounce → PLC top: events · Clean pulses and debounced controls enter the controller
- Tick gen → PLC top: ticks · Slow timing events drive scan and display timing
- PLC top → Editor UI: edit mode · Top controller routes controls through the editor UI
- PLC top → Program store: store/update · Editor and service actions mutate ladder memory
- Program store → Scan engine: ladder grid · Stored program is consumed by the scan engine
- Runtime state → Scan engine: state in · Current PLC state participates in rung evaluation
- Scan engine → Runtime state: state out · Scan results update outputs and internal bits
- Timers → Runtime state: done bits · Timer state feeds back into the runtime loop
- Counters → Runtime state: done bits · Counter state feeds back into the runtime loop
- Runtime state → Timers: time state · Timers retain elapsed-time state across scans
- Runtime state → Counters: count state · Counters retain accumulated count state across scans
- PLC top → Timers: TON/TOF · Top controller manages timing instructions
- PLC top → Counters: CTU/reset · Top controller manages counting instructions
- PLC top → 7-seg driver: segments · Controller drives the multiplexed seven-segment display
- PLC top → LED output: status LEDs · Controller maps inputs and status to LEDs
- XDC → PLC top: pins · Board constraints bind the top module to hardware I/O
- Project report → PLC top: design context · Documentation explains the architecture and intended behavior