How zackakil/rgb-neural-net works
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).