# zackakil/rgb-neural-net architecture

> Architecture diagram of the GitHub repository zackakil/rgb-neural-net, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/zackakil/rgb-neural-net
- Repository: https://github.com/zackakil/rgb-neural-net

## Overview

##### Project Type & Purpose
- This is an IOT “physical neural network” visualization system.
- A host computer (Python/Scikit-learn) trains a toy neural net and streams weight updates over WiFi.
- A Raspberry Pi Zero runs a Flask API, exposing a REST endpoint.
- The Pi drives an Arduino Uno via serial, which in turn updates RGB LEDs embedded in 3D-printed “neurons” linked by fiber-optic tubing.

##### File‐Structure Analysis
- arduino/led_strip_hello_world & arduino/led_strip_serial_control
- Arduino sketches that drive LED strips – one demo, one with serial interface.
- neural-network/
- Jupyter notebooks for data generation, training, testing.
- led_api/led_api.py – Python client library mapping a Scikit-learn MLPClassifier to JSON payloads.
- rgb_nn.py – wrapper exposing RGB_NN(server_loc) and display_weights(nn).
- raspberry-pi/led_server.py
- Flask application exposing POST /change_leds.
- Reads JSON, formats serial commands, writes to /dev/ttyACM0 at 9600bps.
- images/ – documentation and UI mockups, not part of runtime.

##### Key Insights from README
- The training loop on the host:
for each epoch → nn.fit(…) → rgb.display_weights(nn)
- Hardware list: Arduino Uno, Pi Zero, RGB LED strips, 3D printed nodes, fiber-optic tubing.
- Communication chain: Python → HTTP → Flask (Pi) → Serial → Arduino → LEDs.

a. Main Components
- Host Machine (Python training + Jupyter front end)
- Python RGB-NN Client Library (neural-network/led_api + rgb_nn.py)
- Network (WiFi/LAN between Host and Pi)
- Raspberry Pi Zero (Flask API server)
- Serial Link (/dev/ttyACM0 at 9600 baud)
- Arduino Uno (LED strip driver)
- Physical LEDs & Fiber-optic Neurons (3D-printed nodes)
b. Relationships & Data Flow
1. Host generates synthetic data and trains sklearn.MLPClassifier.
2. rgb.display_weights() serializes weight matrices into a JSON body.
3. HTTP POST to Pi: /change_leds with array of {led_num, red, green, blue}.
4. Flask server parses JSON, batches updates, writes ASCII commands over serial.
5. Arduino firmware receives commands, parses them, writes to LED strip via FastLED/analogWrite.
6. LED strips illuminate, light travels through fiber optic ⇒ visual neural net.
c. Architectural Patterns & Principles
- Layered Architecture – clear separation: ML Training Layer / API Layer / Hardware Driver Layer / Physical Layer.
- Adapter Pattern – led_api.py adapts sklearn’s weight matrices to REST JSON.
- Message‐Based Integration – HTTP/JSON between Host & Pi, ASCII‐serial between Pi & Arduino.
d. Key Technologies & Frameworks
- Python 3.x, Scikit-learn (ML)
- Flask (REST API)
- serial (pySerial)
- Arduino C++ & FastLED (LED control)
- Raspberry Pi OS (Debian)
- Fiber-optic hardware, 3D-printed components

##### Final Advice
- Be exhaustive: represent all major software modules and hardware pieces.
- Both logical flow (data transformations) and physical flow (wiring, network).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Host Layer
    subgraph "Host Machine (Training Layer)"
        direction TB
        MLNotebooks["ML Training Notebooks"]:::host
        JupyterExamples["Jupyter Examples & Tests"]:::host
        RGBNNClient["Python RGB-NN Client Library"]:::host
        RGBNNWrapper["Python RGB_NN Wrapper"]:::host
        LedMap["Neural-Network Utility (led_map.py)"]:::host
    end

    %% Network
    Network["WiFi Network"]:::network

    %% Edge Layer - Raspberry Pi
    subgraph "Edge: Raspberry Pi Zero (API Layer)"
        direction TB
        FlaskAPI["Flask API Server (/change_leds)"]:::api
    end

    %% Serial Link
    Serial["Serial Link (9600bps)"]:::serial

    %% Device Layer - Arduino
    subgraph "Device: Arduino Uno (Hardware Driver Layer)"
        direction TB
        DemoSketch["Demo LED Sketch"]:::device
        SerialSketch["Serial LED Control Sketch"]:::device
    end

    %% Physical Layer
    Physical["Physical Visualization (LEDs + Fiber-Optic)"]:::physical

    %% Connections
    MLNotebooks -->|"(1) fit() & display_weights()"| RGBNNWrapper
    RGBNNWrapper -->|"(2) JSON POST /change_leds"| Network
    Network -->|"HTTP POST 5000"| FlaskAPI
    FlaskAPI -->|"(3) pySerial.write()"| Serial
    Serial -.->|"ASCII Commands"| SerialSketch
    SerialSketch -->|"FastLED/analogWrite"| Physical
    DemoSketch -->|"Demo Mode"| Physical

    %% Click Events
    click MLNotebooks "https://github.com/zackakil/rgb-neural-net/blob/master/neural-network/FINAL RGB NN with synthetic data.ipynb"
    click JupyterExamples "https://github.com/zackakil/rgb-neural-net/blob/master/neural-network/RGB NN API.ipynb"
    click JupyterExamples "https://github.com/zackakil/rgb-neural-net/blob/master/neural-network/rgb api test.ipynb"
    click RGBNNClient "https://github.com/zackakil/rgb-neural-net/blob/master/neural-network/led_api/led_api.py"
    click RGBNNWrapper "https://github.com/zackakil/rgb-neural-net/blob/master/neural-network/rgb_nn.py"
    click LedMap "https://github.com/zackakil/rgb-neural-net/blob/master/neural-network/led_map.py"
    click FlaskAPI "https://github.com/zackakil/rgb-neural-net/blob/master/raspberry-pi/led_server.py"
    click SerialSketch "https://github.com/zackakil/rgb-neural-net/blob/master/arduino/led_strip_serial_control/led_strip_serial_control.ino"
    click DemoSketch "https://github.com/zackakil/rgb-neural-net/blob/master/arduino/led_strip_hello_world/led_strip_hello_world.ino"
    click Physical "https://github.com/zackakil/rgb-neural-net/tree/master/images/"

    %% Styles
    classDef host fill:#D0E7FF,stroke:#0366D6,color:#0366D6
    classDef network fill:#E6FFED,stroke:#28A745,color:#28A745
    classDef api fill:#FFEFD5,stroke:#FF8C00,color:#FF8C00
    classDef serial fill:#F3E6FF,stroke:#800080,color:#800080
    classDef device fill:#FFECEC,stroke:#D73A49,color:#D73A49
    classDef physical fill:#FFF8DC,stroke:#DAA520,color:#DAA520
```
