# edge-tronics/chess-robot architecture

> Architecture diagram of the GitHub repository edge-tronics/chess-robot, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/edge-tronics/chess-robot
- Repository: https://github.com/edge-tronics/chess-robot

## Overview

##### Main Components
- Interface Module (Interface.py): This is the front-end of the application built with PySimpleGUI that users interact with. It manages inputs (e.g., move commands and game state visualizations) and displays output.
- Chess Logic Module (ChessLogic.py): This component handles the game rules, move validations, and decision-making. It likely integrates with external chess engines (as seen by the Stockfish executable in the “games” folder) and the python-chess library.
- Vision Module (VisionModule.py): Using OpenCV, it captures and processes images from the camera to identify the chessboard’s state.
- Arm Control Module (ArmControl.py, lss.py, and lss_const.py): Responsible for calculating and executing the robotic arm movements (using the LSS serial protocol) so that the arm can interact with the physical chessboard.
- Supporting Resources:
– Audio files (in the audio directory) provide auditory feedback.
– Visual resources (interface_images and pieces_images) for GUI elements and potential logging or debugging.
– Configuration (params.txt and requirements.txt) manages calibration and dependency details.
– External Engine: Stockfish (found in the games folder) supplies advanced chess move recommendations when needed.

##### Interactions and Data Flow
- User Interaction Flow:
– The user starts the application by running Interface.py. Through this UI, inputs (like moves or settings) are registered.
- Game Logic Flow:
– The Interface passes user inputs to the ChessLogic module.
– ChessLogic processes the moves and, when necessary, queries the Stockfish chess engine for move decisions.
– If any discrepancies on the board arise, the Vision Module takes camera captured images and analyzes the board state, feeding that information back into ChessLogic.
- Physical Actuation Flow:
– Once a move is confirmed (either by the chess logic or inputed by the user), ChessLogic instructs the Arm Control module.
– The Arm Control module uses inverse kinematics calculations (presumably via lss.py and lss_const.py) to command the robotic arm to move the chess pieces accordingly.
- Feedback and Notifications:
– Audio feedback files play sounds (for example, for moves or errors).
– The user interface updates to show the board changes and any action confirmations.

##### Architectural Patterns and Technologies
- Modular Structure: Different responsibilities (vision, logic, control, and interface) are separated into individual Python files. This is similar to a layered or component-based architecture.
- Integration of External Libraries: OpenCV for vision, python-chess and Stockfish for game logic, and PySimpleGUI for the user interface.
- Hardware Interface: The Arm Control module directly correlates with the physical hardware (LSS 4 DoF robotic arm and possibly sensor inputs from the camera).
- Data Flow: There is a clear request–response pattern between the front-end (Interface) and back-end components (ChessLogic, Vision, and ArmControl).

- That every module has its dependencies and interactions clearly annotated.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Main Components
    UI["User Interface (Interface.py)"]:::software
    CL["Chess Logic (ChessLogic.py)"]:::software
    VM["Vision Module (VisionModule.py)"]:::software
    EC["External Chess Engine (Stockfish)"]:::external

    %% Connections between main components
    UI -->|"sends_commands"| CL
    CL -->|"queries_move"| EC
    CL -->|"validates_board"| VM
    VM -->|"feeds_board_state"| CL

    %% Arm Control Module Subgraph
    subgraph "Arm Control Module"
        A1["ArmControl.py"]:::hardware
        A2["lss.py"]:::hardware
        A3["lss_const.py"]:::hardware
        A1 -->|"uses"| A2
        A2 -->|"uses"| A3
    end
    CL -->|"executes_movement"| A1

    %% Supporting Resources Subgraph
    subgraph "Supporting Resources"
        Audio["Audio Feedback"]:::resources
        subgraph "Visual Resources"
            VI["Interface Images"]:::resources
            VP["Pieces Images"]:::resources
        end
        subgraph "Configuration"
            CFG1["params.txt"]:::resources
            CFG2["requirements.txt"]:::resources
        end
    end

    %% Connections to Resources
    UI ---|"loads_visuals"| VI
    UI ---|"loads_visuals"| VP
    UI ---|"plays_sound"| Audio
    CL ---|"reads_config"| CFG1
    CL ---|"reads_config"| CFG2

    %% Styles
    classDef software fill:#E0F7FA,stroke:#006064,stroke-width:2px;
    classDef hardware fill:#FFECB3,stroke:#FF9800,stroke-width:2px;
    classDef resources fill:#C8E6C9,stroke:#388E3C,stroke-width:2px;
    classDef external fill:#F8BBD0,stroke:#C2185B,stroke-width:2px;

    %% Click Events
    click UI "https://github.com/edge-tronics/chess-robot/blob/master/Interface.py"
    click CL "https://github.com/edge-tronics/chess-robot/blob/master/ChessLogic.py"
    click VM "https://github.com/edge-tronics/chess-robot/blob/master/VisionModule.py"
    click A1 "https://github.com/edge-tronics/chess-robot/blob/master/ArmControl.py"
    click A2 "https://github.com/edge-tronics/chess-robot/blob/master/lss.py"
    click A3 "https://github.com/edge-tronics/chess-robot/blob/master/lss_const.py"
    click EC "https://github.com/edge-tronics/chess-robot/blob/master/games/stockfishX64.exe"
    click Audio "https://github.com/edge-tronics/chess-robot/tree/master/audio/"
    click VI "https://github.com/edge-tronics/chess-robot/tree/master/interface_images/"
    click VP "https://github.com/edge-tronics/chess-robot/tree/master/pieces_images/"
    click CFG1 "https://github.com/edge-tronics/chess-robot/blob/master/params.txt"
    click CFG2 "https://github.com/edge-tronics/chess-robot/blob/master/requirements.txt"
```
