# krithikalluri/neurowheel architecture

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

- Interactive diagram: https://gitdiagram.com/krithikalluri/neurowheel
- Repository: https://github.com/krithikalluri/neurowheel

## Overview

##### Project type and purpose
- Neurowheel is an embedded control system combining brain-computer interface (EEG capture), machine learning signal processing, and motor control on a wheelchair platform.
- It is neither a classic full-stack web app nor a library; it’s a hardware-software integration project with distinct embedded, edge-compute, and robotic control layers.

##### File structure
- Top-level Python scripts (ComputerComms.py, Joystick.py, RPISerialComms.py, tutorial_1_simple_example_motor_imagery.py) implement data acquisition, signal processing, and communications.
- Multiple Arduino sketches (.ino files in root and in FinalSerialComms/) target microcontrollers that drive the wheelchair motors and handle serial or I²C comms.
- FinalSerialComms/ holds the production-ready Arduino code and its build metadata (sketch.json).
- I2CDetector.ino likely probes I²C peripherals, and DigiComms.ino is an earlier comms prototype.
- There’s no traditional “frontend” folder; the “user interface” is the EEG headset and optional joystick override.

##### README for additional insights
- EEG signals are captured via an OpenBCI Cyton headset at specific electrode positions.
- Machine learning algorithms in Python convert raw EEG into discrete movement commands (forward, left, right).
- The processed commands are forwarded over serial (or I²C) to an Arduino (or RP2040 on the wheelchair) that drives the motor controllers.

##### Main components and interactions
a. EEG Acquisition Layer
- Block: “OpenBCI Cyton Headset”
- Connects via Bluetooth or USB serial to the edge-compute device.
b. Edge Compute & Signal Processing
- Block: “Raspberry Pi / PC” running Python scripts
- Subcomponents:
- EEG Data Reader (ComputerComms.py or RPISerialComms.py)
- Feature Extraction & ML Model (tutorial_1_simple_example_motor_imagery.py)
- Joystick Fallback Handler (Joystick.py)
- Output: movement commands over serial or I²C
c. Embedded Control Layer
- Block: “Arduino Microcontroller” (FinalSerialComms.ino)
- Responsibilities: parse incoming commands, generate PWM signals to motor drivers
- I²CDetector.ino can be shown as a utility/probe block
d. Actuation Layer
- Block: “Motor Drivers & Wheelchair Motors”
- Receives PWM signals to control wheel rotation and direction
e. (Optional) Logging / Monitoring
- Could show Python scripts writing logs or a serial console for debugging

##### Architectural patterns & design principles
- Pipeline architecture: raw EEG → preprocessing → ML inference → command dispatch → actuation
- Separation of concerns: sensing, processing, control
- Modularity: interchangeable ML models, multiple comms protocols (serial, I²C), joystick override

##### Key technologies/frameworks
- OpenBCI Python SDK (EEG data capture)
- scikit-learn / TensorFlow / custom ML code for classification
- Python 3.x for signal processing and host communications
- Arduino C++ sketches for real-time motor control
- Raspberry Pi or equivalent SBC as the edge compute host

##### Elements
- Clear, consistent component labels (e.g., “EEG Acquisition,” “Signal Processing,” “Motion Controller”).
- Callouts for key file names or scripts (e.g., “ML logic: tutorial_1_simple_example_motor_imagery.py”).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Sensing Layer
    subgraph "Sensing Layer"
        OB["OpenBCI Cyton Headset"]:::hardware
    end

    %% Processing Layer
    subgraph "Processing Layer"
        ReaderUSB["EEG Data Reader\nComputerComms.py"]:::processing
        ReaderPi["EEG Data Reader\nRPISerialComms.py"]:::processing
        Feature["Feature Extraction & ML Inference\ntutorial_1_simple_example_motor_imagery.py"]:::processing
        JoystickNode["Joystick Fallback Handler\nJoystick.py"]:::processing
        CommandDisp["Command Dispatcher\n(Serial / I²C)"]:::processing
        Logging["Logging / Monitoring\n(Optional)"]:::processing
    end

    %% Embedded Control Layer
    subgraph "Embedded Control Layer"
        FinalFW["Production Firmware\nFinalSerialComms.ino"]:::firmware
        SketchConfig["Firmware Metadata\nsketch.json"]:::firmware
        subgraph "Prototypes"
            I2CProbe["I²C Probe Utility\nI2CDetector.ino"]:::firmware
            SerialProto["Serial Comms Prototype\nDigiComms.ino"]:::firmware
        end
    end

    %% Actuation Layer
    subgraph "Actuation Layer"
        MotorDrivers["Motor Drivers & Wheelchair Motors"]:::actuation
    end

    %% Documentation
    subgraph "Documentation"
        README["Project README\nREADME.md"]:::docs
    end

    %% Connections
    OB -->|"Bluetooth/USB"| ReaderUSB
    OB -->|"Bluetooth/USB"| ReaderPi
    ReaderUSB -->|"EEG stream"| Feature
    ReaderPi -->|"EEG stream"| Feature
    Feature -->|"features"| CommandDisp
    JoystickNode -->|"fallback commands"| CommandDisp
    CommandDisp -->|"command packets\nSerial/I²C @115200"| FinalFW
    CommandDisp -.->|"dev path"| I2CProbe
    CommandDisp -.->|"dev path"| SerialProto
    FinalFW -->|"PWM signals"| MotorDrivers
    FinalFW -->|"status feedback"| CommandDisp
    Logging --> CommandDisp

    %% Click Events
    click ReaderUSB "https://github.com/krithikalluri/neurowheel/blob/main/ComputerComms.py"
    click ReaderPi "https://github.com/krithikalluri/neurowheel/blob/main/RPISerialComms.py"
    click Feature "https://github.com/krithikalluri/neurowheel/blob/main/tutorial_1_simple_example_motor_imagery.py"
    click JoystickNode "https://github.com/krithikalluri/neurowheel/blob/main/Joystick.py"
    click FinalFW "https://github.com/krithikalluri/neurowheel/blob/main/FinalSerialComms/FinalSerialComms.ino"
    click SketchConfig "https://github.com/krithikalluri/neurowheel/blob/main/FinalSerialComms/sketch.json"
    click I2CProbe "https://github.com/krithikalluri/neurowheel/blob/main/I2CDetector.ino"
    click SerialProto "https://github.com/krithikalluri/neurowheel/blob/main/DigiComms.ino"
    click README "https://github.com/krithikalluri/neurowheel/blob/main/README.md"

    %% Styles
    classDef hardware fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef processing fill:#98FB98,stroke:#000,stroke-width:1px
    classDef firmware fill:#FFA500,stroke:#000,stroke-width:1px
    classDef actuation fill:#D3D3D3,stroke:#000,stroke-width:1px
    classDef docs fill:#D8BFD8,stroke:#000,stroke-width:1px
```
