# protossgp32/omega architecture

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

- Interactive diagram: https://gitdiagram.com/protossgp32/omega
- Repository: https://github.com/protossgp32/omega

## Overview

##### Project type and purpose
- This is a fully open-source hardware implementation of an MSX2-compatible home computer (“Omega”).
- It comprises: a keyboard PCB, a main motherboard PCB, a BIOS flash image, an enclosure design, and supporting KiCad libraries plus build scripts.

##### File structure
- Top-level directories:
- BIOS – firmware binaries and ROM-building script
- Keyboard – KiCad PCB, schematic, gerbers, docs
- Mainboard – KiCad PCB, schematic, SPLD source, gerbers, docs
- Enclosure – mechanical CAD (.scad, .dxf, .stl), drawings
- kicad_libraries – custom footprint & 3D models
- README*.md – project overview & per-module guides
- Build scripts: BIOS/make_roms.sh
- CAD files (.scad, .dxf) for the enclosure.

##### Key insights from README
- Implements core MSX2 subsystems: Z80 CPU, VDP (V9958), PSG (YM2149F), PPI (8255), SRAM, Flash, SPLDs for glue logic, 7400-series TTL.
- Keyboard stacks on top of main board inside a 3D-printed or laser-cut enclosure.

##### Main components and their interactions
a. Digital CPU & glue logic domain
- Z80 CPU
- Flash ROM (BIOS) & SRAM mapped on Z80 bus
- ATF16V8B SPLDs (chip_select, slot_dir, slot_select) implement address decoding / bus arbitration
- 74xx TTL gates (glue for reset, interrupts)
b. Video & audio subsystems
- V9958 VDP — connects to Z80 data/address bus and to video output connector
- AY-3-8910 PSG — connects to Z80 via PPI or direct bus lines, drives audio out
c. I/O and peripherals
- 8255 PPI interfaces keyboard matrix, joystick ports, cassette I/O
- Edge connectors / slots for cartridge expansion
- Mini-DIN, RCA, edge-connector I/O on rear panel
d. Keyboard PCB
- Key matrix scanned by PPI on mainboard bus
- Ribbon cable / pin header between keyboard and mainboard
e. Enclosure
- Mechanical housing holds stacked PCBs, external connectors, and cables
- CAD models for 3D printing or laser cutting

##### Relationships & data-flows
- Z80 CPU at center:
→ reads BIOS from Flash, executes code
→ reads/writes SRAM
→ issues address lines to SPLDs → selects ROM/RAM/VDP/PSG/PPI
→ communicates with VDP for video memory and registers → video out
→ communicates with PSG → audio out
→ reads keyboard scan data via PPI → user input
- SPLD blocks: decode CPU address lines → generate chip‐select signals for each peripheral
- PPI: multiplexes data bus to keyboard matrix lines / joystick lines
- Clock & reset distribution: 74xx logic ensures correct timing and boot reset

##### Architectural patterns & design principles
- Classic bus architecture: single shared data/address bus, multiplexed by glue logic
- Modular PCB stacking: keyboard stack with standoffs onto mainboard for mechanical simplicity
- Separation of concerns: distinct PCBs for input (keyboard) and core logic (mainboard)
- Open CAD toolchain: KiCad for PCBs, OpenSCAD and DXF for mechanical

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Processor Domain
    subgraph "Processor Domain"
        Z80["Z80 CPU"]:::processor
    end

    %% Memory
    subgraph "Memory"
        FlashROM["Flash ROM (BIOS)"]:::memory
        SRAM["SRAM"]:::memory
    end

    %% Glue Logic
    subgraph "Glue Logic"
        subgraph "SPLDs (Address Decoding)"
            SPLD_CS["chip_select"]:::logic
            SPLD_SD["slot_dir"]:::logic
            SPLD_SS["slot_select"]:::logic
        end
        TTL["74xx TTL (Reset/Interrupt)"]:::logic
    end

    %% Video & Audio
    subgraph "Video & Audio"
        VDP["V9958 VDP"]:::output
        PSG["AY-3-8910 PSG"]:::output
    end

    %% I/O Subsystem
    subgraph "I/O & Peripherals"
        PPI["8255 PPI"]:::io
        Keyboard["Keyboard Matrix"]:::io
    end

    %% Expansion
    subgraph "Expansion Slots"
        Slots["Expansion Slots & Edge Connectors"]:::io
    end

    %% Mechanical Enclosure
    subgraph "Enclosure Mechanical"
        Enclosure["Enclosure CAD Models"]:::mech
    end

    %% Auxiliary Components
    subgraph "Auxiliary"
        Build["BIOS Build Pipeline"]:::ext
        Libraries["KiCad Libraries & 3D Models"]:::ext
    end

    %% Data & Control Flows
    Z80 -->|read/write| FlashROM
    Z80 -->|read/write| SRAM
    Z80 -->|address bus| SPLD_CS
    Z80 -->|address bus| SPLD_SD
    Z80 -->|address bus| SPLD_SS
    Z80 -->|clock/reset| TTL
    Z80 -->|data/address| VDP
    Z80 -->|data/address| PSG
    Z80 -->|data/address| PPI
    PPI -->|scan matrix| Keyboard
    SPLD_CS -->|chip select| FlashROM
    SPLD_CS -->|chip select| SRAM
    SPLD_CS -->|chip select| VDP
    SPLD_CS -->|chip select| PSG
    SPLD_CS -->|chip select| PPI
    Z80 -.->|bus| Slots
    Keyboard -.->|ribbon cable| Z80
    Build -->|generates| FlashROM

    %% Click Events
    click Z80 "https://github.com/protossgp32/omega/blob/master/Mainboard/KiCad/Omega-Processor.sch"
    click FlashROM "https://github.com/protossgp32/omega/blob/master/BIOS/make_roms.sh"
    click SRAM "https://github.com/protossgp32/omega/blob/master/Mainboard/KiCad/Omega-Memory.sch"
    click SPLD_CS "https://github.com/protossgp32/omega/blob/master/Mainboard/SPLDs/omega-chip_select.*"
    click SPLD_SD "https://github.com/protossgp32/omega/blob/master/Mainboard/SPLDs/omega-slot_dir.*"
    click SPLD_SS "https://github.com/protossgp32/omega/blob/master/Mainboard/SPLDs/omega-slot_select.*"
    click TTL "https://github.com/protossgp32/omega/blob/master/Mainboard/KiCad/Omega-Processor.sch"
    click VDP "https://github.com/protossgp32/omega/blob/master/Mainboard/KiCad/Omega-VDP.sch"
    click PSG "https://github.com/protossgp32/omega/blob/master/Mainboard/KiCad/Omega-PSG.sch"
    click PPI "https://github.com/protossgp32/omega/blob/master/Mainboard/KiCad/Omega-PPI.sch"
    click Keyboard "https://github.com/protossgp32/omega/blob/master/Keyboard/KiCad/Omega-Keyboard.sch"
    click Keyboard "https://github.com/protossgp32/omega/blob/master/Keyboard/KiCad/Omega-Keyboard.kicad_pcb"
    click Slots "https://github.com/protossgp32/omega/blob/master/Mainboard/KiCad/Omega-Slots.sch"
    click Slots "https://github.com/protossgp32/omega/blob/master/Enclosure/Omega-Slots_Guide.scad"
    click Enclosure "https://github.com/protossgp32/omega/blob/master/Enclosure/Omega-Slots_Guide.scad"
    click Enclosure "https://github.com/protossgp32/omega/blob/master/Enclosure/Omega-Eco?_User.dxf"
    click Enclosure "https://github.com/protossgp32/omega/blob/master/Enclosure/Omega-Slots_Guide.stl"
    click Libraries "https://github.com/protossgp32/omega/blob/master/kicad_libraries/omega_components.pretty"
    click Libraries "https://github.com/protossgp32/omega/tree/master/kicad_libraries/3d_models"

    %% Styles
    classDef processor fill:#f9f,stroke:#333,stroke-width:1px
    classDef memory fill:#ccf,stroke:#333,stroke-width:1px
    classDef logic fill:#cfc,stroke:#333,stroke-width:1px
    classDef io fill:#fcc,stroke:#333,stroke-width:1px
    classDef output fill:#fc9,stroke:#333,stroke-width:1px
    classDef mech fill:#cce,stroke:#333,stroke-width:1px
    classDef ext fill:#eee,stroke:#666,stroke-dasharray: 5 5,stroke-width:1px
```
