# j0k3r-joel/botball_library architecture

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

- Interactive diagram: https://gitdiagram.com/j0k3r-joel/botball_library
- Repository: https://github.com/j0k3r-joel/botball_library

## Overview

##### Project type and purpose
- This is a language-level (Python) robotics utility and communication toolkit for the KIPR Wombat framework. It’s not a single application but a layered library: hardware abstractions (sensors, drives, servos, camera), communication tools (TCP/IP, Wi-Fi), simulation utilities (FakeR, PausR), file/logging helpers, and example “apps” that wire everything together.

##### File structure
- Top level: config scripts, docs, examples, and a large `src/` folder.
- Under `src/` you find parallel module sets:
- `src_Base`, `src_BIAS`, `src_COMM`, `src_Camera`, `src_Fake-Client`, `src_Fake-Server`, `src_WIFI` – each defines the same interfaces (Digital, analog, driveR, RoboComm, etc.) for different runtime contexts.
- `src_WIFI_FOR_INSTALLATION` and `src/scripts/` support deployment/configuration.
- `examples/teaching_JBC` shows how to combine BIAS and Base modules into a working robot program.
- docs/ and doc/explainer/ contain detailed design notes for each class.

##### README for insights
- Technology stack: Python, KIPR Wombat OS, TCP/IP, Wi-Fi
- Architectural intent: clear separation between hardware-level wrappers, communication layers, high-level utility functions, and simulation.
- Deployment: wrapper scripts configure the robot’s OS and Wi-Fi, then run user code.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Deployment & Setup Layer
    subgraph "Deployment & Setup"
        direction TB
        BaseExec["base_executor.sh"]:::script
        SetupHarrogate["setup_harrogate.sh"]:::script
        ConfigScript["config.sh"]:::config
        StdWifiConf["LOCAL_STD_WIFI.conf"]:::config
    end

    %% Application Layer
    subgraph "Application Layer"
        direction TB
        TeachExample["Teaching Example"]:::app
        WifiInstallApp["Wi-Fi Installation Script"]:::app
    end

    %% Utility Layer
    subgraph "Utility Layer"
        direction TB
        FileIO["File I/O Helper"]:::util
        Logger["Logging Utility"]:::util
        UtilGen["Generic Utilities"]:::util
        StopMgr["Stop Signal Manager"]:::util
    end

    %% Simulation Layer
    subgraph "Simulation Layer"
        direction TB
        FakeBase["FakeR"]:::sim
        FakeClient["Fake-Client"]:::sim
        FakeServer["Fake-Server"]:::sim
        PauseSim["PausR"]:::sim
    end

    %% Communication Layer
    subgraph "Communication Layer"
        direction TB
        RoboComm["Robot Communicator\n(TCP/IP)"]:::comm
        WifiConnector["Wi-Fi Connector"]:::comm
        WifiInstallHelper["Wi-Fi Main"]:::comm
    end

    %% Abstraction Layer
    subgraph "Abstraction Layer"
        direction TB
        DriveR["DriveR Module"]:::abst
        MotorSched["Motor Scheduler"]:::abst
        ServoSched["Servo Scheduler"]:::abst
    end

    %% Hardware Layer
    subgraph "Hardware Layer"
        direction TB
        DigitalSensor["Digital Sensor Interface"]:::hw
        DistanceSensor["Distance Sensor Interface"]:::hw
        LightSensor["Light Sensor Interface"]:::hw
        ServoActuator["Servo Actuator Interface"]:::hw
        WheelR["WheelR Motor Interface"]:::hw
        CameraMgr["Camera Manager"]:::hw
    end

    %% Interactions
    BaseExec -->|initializes| TeachExample
    SetupHarrogate -->|configures| WifiInstallApp
    ConfigScript -->|loads| WifiInstallApp
    StdWifiConf -->|provides| WifiInstallApp

    TeachExample -->|uses| DriveR
    TeachExample -->|uses| DigitalSensor
    TeachExample -->|uses| DistanceSensor
    TeachExample -->|uses| LightSensor
    TeachExample -->|uses| ServoActuator
    TeachExample -->|uses| WheelR
    WifiInstallApp -->|calls| WifiConnector

    DriveR -->|schedules| MotorSched
    DriveR -->|schedules| ServoSched
    MotorSched -->|controls| WheelR
    ServoSched -->|controls| ServoActuator

    DriveR -->|calls| RoboComm
    RoboComm <-->|simulates| FakeBase
    FakeClient -->|connects| RoboComm
    FakeServer -->|connects| RoboComm
    RoboComm <-->|pauses| PauseSim

    AnyLayer_Log[["Any Layer"]] -->|logs| Logger
    AnyLayer_File[["Any Layer"]] -->|writes| FileIO
    AnyLayer_Gen[["Any Layer"]] -->|utilizes| UtilGen
    AnyLayer_Stop[["Any Layer"]] -->|checks| StopMgr

    %% Utility generic connections
    subgraph "_Utility Access_"
        direction TB
        AnyLayer_Log
        AnyLayer_File
        AnyLayer_Gen
        AnyLayer_Stop
    end

    %% Click Events
    click DigitalSensor "https://github.com/j0k3r-joel/botball_library/blob/main/src/src_Base/digital.py"
    click DistanceSensor "https://github.com/j0k3r-joel/botball_library/blob/main/src/src_Base/distance_sensor.py"
    click LightSensor "https://github.com/j0k3r-joel/botball_library/blob/main/src/src_Base/light_sensor.py"
    click ServoActuator "https://github.com/j0k3r-joel/botball_library/blob/main/src/src_Base/servo.py"
    click WheelR "https://github.com/j0k3r-joel/botball_library/blob/main/src/src_Base/wheelR.py"
    click CameraMgr "https://github.com/j0k3r-joel/botball_library/blob/main/src/src_Camera/camera_manager.py"

    click DriveR "https://github.com/j0k3r-joel/botball_library/blob/main/src/src_Base/driveR.py"
    click MotorSched "https://github.com/j0k3r-joel/botball_library/blob/main/src/src_Base/motor_scheduler.py"
    click ServoSched "https://github.com/j0k3r-joel/botball_library/blob/main/src/src_Base/servo_scheduler.py"

    click RoboComm "https://github.com/j0k3r-joel/botball_library/blob/main/src/src_Base/RoboComm.py"
    click WifiConnector "https://github.com/j0k3r-joel/botball_library/blob/main/src/src_WIFI/wifi.py"
    click WifiInstallHelper "https://github.com/j0k3r-joel/botball_library/blob/main/src/WIFI_FOR_INSTALLATION/wifi.py"

    click FakeBase "https://github.com/j0k3r-joel/botball_library/blob/main/src/src_Base/fake.py"
    click FakeClient "https://github.com/j0k3r-joel/botball_library/blob/main/src/src_Fake-Client/fake.py"
    click FakeServer "https://github.com/j0k3r-joel/botball_library/blob/main/src/src_Fake-Server/fake.py"
    click PauseSim "https://github.com/j0k3r-joel/botball_library/blob/main/src/src_Base/pausR.py"

    click FileIO "https://github.com/j0k3r-joel/botball_library/blob/main/src/src_Base/fileR.py"
    click Logger "https://github.com/j0k3r-joel/botball_library/blob/main/src/src_Base/logger.py"
    click UtilGen "https://github.com/j0k3r-joel/botball_library/blob/main/src/src_Base/util.py"
    click StopMgr "https://github.com/j0k3r-joel/botball_library/blob/main/src/src_Base/stop_manager.py"

    click TeachExample "https://github.com/j0k3r-joel/botball_library/blob/main/examples/teaching_JBC/src_BIAS/main.py"
    click WifiInstallApp "https://github.com/j0k3r-joel/botball_library/blob/main/src/WIFI_FOR_INSTALLATION/main.py"

    click BaseExec "https://github.com/j0k3r-joel/botball_library/blob/main/src/scripts/base_executor.sh"
    click SetupHarrogate "https://github.com/j0k3r-joel/botball_library/blob/main/src/scripts/setup_harrogate.sh"
    click ConfigScript "https://github.com/j0k3r-joel/botball_library/blob/main/config.sh"
    click StdWifiConf "https://github.com/j0k3r-joel/botball_library/blob/main/LOCAL_STD_WIFI.conf"

    %% Styles
    classDef hw fill:#cce5ff,stroke:#004085
    classDef abst fill:#e2e3e5,stroke:#6c757d
    classDef comm fill:#d4edda,stroke:#155724
    classDef sim fill:#fff3cd,stroke:#856404
    classDef util fill:#e2e3f,stroke:#343a40
    classDef app fill:#d6d8db,stroke:#1b1e21
    classDef script fill:#ffeeba,stroke:#856404,stroke-dasharray: 5 5
    classDef config fill:#f8d7da,stroke:#721c24,stroke-dasharray: 5 5
```
