# simon-gardier/dance-dance-revolution-assembly architecture

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

- Interactive diagram: https://gitdiagram.com/simon-gardier/dance-dance-revolution-assembly
- Repository: https://github.com/simon-gardier/dance-dance-revolution-assembly

## Overview

##### Project type and purpose
- This is an embedded‐systems project: a Dance Dance Revolution–style game written entirely in PIC16F1789 assembly.
- It implements video signal generation (PAL-G), audio via the PSMC module, input polling, game logic, and a simple menu/high-score system—all on a single microcontroller.

##### High-level system components
a. Hardware
- PIC16F1789 microcontroller
– CPU core (fetch/execute assembly instructions)
– Program memory (flash) holding .s and .inc modules
– Data memory (RAM) for frame buffering and game state
– PSMC (Programmable Switch-Mode Controller) for sound output
– PORTC latch used as video shift-register
– GPIO ports for button inputs
- Composite video output (to TV/monitor)
- Audio amplifier/speaker
- Button matrix or individual inputs (dance pad)
- Power supply circuitry (L7805CV, MOSFETs, connectors)
- PCB traces/connector to external display and controls

b. Firmware modules (in /code)
- main.s               — Initialization, main loop, frame synchronization
- video.inc / video.s  — PAL-G sync pulses, pixel-by-pixel shifting via PORTC
- game_logic.inc / game_logic.s
— State machine: menu, in-game, scoring, lives
- inputs.inc / inputs.s — Polling of buttons, debouncing
- music.inc / music.s  — Frame-synchronous music generation via PSMC
- ram.inc              — Definitions for RAM usage (frame buffer, state)
- bits.inc, utils.inc  — Shared macros and utility routines

c. Documentation & supporting files
- electrical_schematic.pdf — Full hardware electrical schematic
- report.pdf             — Overall design rationale, performance trade-offs
- datasheets in documentation/— PIC16F1789, video standard, connectors

##### Interactions & data flows
- At power-on, main.s initializes I/O, PSMC, timer, and enters the vertical-blank–synchronized loop.
- Each video frame:
– music module checks whether to advance the audio waveform
– video module shifts out pixels one bit at a time via PORTC, generating sync and video signals
- Outputs:
– Video output → TV (composite PAL-G)
– Audio output → speaker
- Inputs:
– Button presses → GPIO → inputs.s → game_logic

##### Architectural patterns & design principles
- Single-threaded, frame-paced loop: ensures deterministic timing aligned with video’s 50 Hz refresh.
- Separation of concerns:
- Hardware interface (video.s, music.s, inputs.s)
- Core logic (game_logic.s)
- Resource-constrained optimization: bit-banging video on PORTC, minimal branching in tight loops, RAM usage carefully planned.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% PIC Block with subcomponents and firmware modules
    subgraph "PIC16F1789"
        direction TB
        CPU_core["CPU Core"]:::hardware
        Flash["Program Memory (Flash)"]:::hardware
        RAM["Data Memory (RAM)"]:::hardware
        PSMC["PSMC (Audio Output)"]:::hardware
        PORTC["PORTC (Video Shift)"]:::hardware
        GPIO["GPIO Ports (Inputs)"]:::hardware
        subgraph "Firmware Modules"
            direction TB
            ML["Main Loop & Initialization"]:::util
            Video_sub["Video Subsystem"]:::video
            Draw["Rendering Primitives"]:::video
            Logic["Game Logic State Machine"]:::logic
            Input["Input Handling"]:::input
            Audio["Audio Subsystem"]:::audio
            RAM_mod["RAM Layout & Frame Buffer"]:::util
            Util_mod["Shared Macros & Utilities"]:::util
        end
    end

    %% External hardware and docs
    Buttons["Button Panel"]:::external
    TV["Composite Video → TV"]:::external
    Speaker["Audio Amplifier → Speaker"]:::external
    Power["Power Regulator"]:::external
    Build["Build System (Makefile)"]:::external
    Schem["Electrical Schematic"]:::external
    MCU_pdf["PIC16F1789 Datasheet"]:::external
    PAL_pdf["PAL-G Standard Doc"]:::external
    PSG_pdf["Connector Datasheet"]:::external
    Report["Project Report"]:::external

    %% Data & Control Flows
    CPU_core -->|fetch instructions| Flash
    CPU_core -->|read/write frame buffer & state| RAM
    CPU_core -->|audio commands| PSMC
    CPU_core -->|pixel stream| PORTC
    GPIO -->|button presses| CPU_core

    ML -->|initializes| CPU_core
    ML -->|sync loop| Video_sub

    Video_sub -->|writes bitlines| PORTC
    Draw -->|draw primitives to buffer| RAM
    Logic -->|update state| RAM
    Logic -->|requests draw| Draw
    Logic -->|reads inputs| Input
    Logic -->|triggers audio| Audio

    Input -->|poll & debounce| GPIO
    Audio -->|PSMC waveform| PSMC
    PORTC -->|composite signal| TV
    PSMC -->|audio signal| Speaker
    Power -->|power supply| PIC16F1789

    %% Documentation & Build
    Build --> ML
    Build --> Video_sub
    Build --> Draw
    Build --> Logic
    Build --> Input
    Build --> Audio
    Build --> Util_mod
    Schem -->|ref| Power
    MCU_pdf -->|ref| CPU_core
    PAL_pdf -->|ref| Video_sub
    PSG_pdf -->|ref| PSMC
    Report -->|design rationale| ML

    %% Click Events
    click ML "https://github.com/simon-gardier/dance-dance-revolution-assembly/blob/main/code/main.s"
    click Video_sub "https://github.com/simon-gardier/dance-dance-revolution-assembly/blob/main/code/video.inc"
    click Video_sub "https://github.com/simon-gardier/dance-dance-revolution-assembly/blob/main/code/video.s"
    click Draw "https://github.com/simon-gardier/dance-dance-revolution-assembly/blob/main/code/draw.inc"
    click Draw "https://github.com/simon-gardier/dance-dance-revolution-assembly/blob/main/code/draw.s"
    click Logic "https://github.com/simon-gardier/dance-dance-revolution-assembly/blob/main/code/game_logic.inc"
    click Logic "https://github.com/simon-gardier/dance-dance-revolution-assembly/blob/main/code/game_logic.s"
    click Input "https://github.com/simon-gardier/dance-dance-revolution-assembly/blob/main/code/inputs.inc"
    click Input "https://github.com/simon-gardier/dance-dance-revolution-assembly/blob/main/code/inputs.s"
    click Audio "https://github.com/simon-gardier/dance-dance-revolution-assembly/blob/main/code/music.inc"
    click Audio "https://github.com/simon-gardier/dance-dance-revolution-assembly/blob/main/code/music.s"
    click RAM_mod "https://github.com/simon-gardier/dance-dance-revolution-assembly/blob/main/code/ram.inc"
    click Util_mod "https://github.com/simon-gardier/dance-dance-revolution-assembly/blob/main/code/bits.inc"
    click Util_mod "https://github.com/simon-gardier/dance-dance-revolution-assembly/blob/main/code/utils.inc"
    click Util_mod "https://github.com/simon-gardier/dance-dance-revolution-assembly/blob/main/code/utils.s"
    click Build "https://github.com/simon-gardier/dance-dance-revolution-assembly/tree/main/code/Makefile"
    click Schem "https://github.com/simon-gardier/dance-dance-revolution-assembly/blob/main/electrical_schematic.pdf"
    click MCU_pdf "https://github.com/simon-gardier/dance-dance-revolution-assembly/blob/main/documentation/PIC16f1789_mcu.pdf"
    click PAL_pdf "https://github.com/simon-gardier/dance-dance-revolution-assembly/blob/main/documentation/R-REC-BT.470-6-199811_pal.pdf"
    click PSG_pdf "https://github.com/simon-gardier/dance-dance-revolution-assembly/blob/main/documentation/PSG01512_connector.pdf"
    click Report "https://github.com/simon-gardier/dance-dance-revolution-assembly/blob/main/report.pdf"

    %% Styles
    classDef video fill:#D0E7FF,stroke:#0366D6,color:#0366D6
    classDef logic fill:#DFFFE0,stroke:#28A745,color:#28A745
    classDef input fill:#FFF5CC,stroke:#DAA520,color:#DAA520
    classDef audio fill:#FFE0E0,stroke:#D73A49,color:#D73A49
    classDef util fill:#F0F0F0,stroke:#6A737D,color:#24292E
    classDef hardware fill:#EDEDED,stroke:#444444,color:#444444
    classDef external fill:#FFF0F5,stroke:#C92255,color:#C92255
```
