Refactor codebase with clean library architecture and comprehensive API documentation

- Separate core libraries from examples in both implementations
- Create modular library structure (src/lib/) for Arduino/Node.js and Raspberry Pi
- Add complete API documentation (arduino-api.md, raspberry-pi-api.md)
- Remove all commented-out code from Arduino firmware
- Improve Python utilities with proper docstrings and structure
- Fix threading.Event() bug in Raspberry Pi display code
- Update configuration to use library modules
- Move old implementations to to-sort/ for backup

Author: MissCrispenCakes

docs/api/arduino-api.md

@@ -1,7 +1,4 @@
 #include <SoftwareSerial.h>
-//#include <OSCBundle.h>
-//#include <SLIPEncodedSerial.h>
-//SLIPEncodedSerial SLIPSerial(Serial);
 #include <stdlib.h>
 #include <stdio.h>
 
@@ -12,19 +9,14 @@ void print_time(unsigned long time_millis);
 
 char c=' '; 
 
-// RX, TX LEDs
-// UNO: SoftwareSerial Bluetooth( 8, 7 ); 
-// LILY: SoftwareSerial Bluetooth( 1, 0 ); ( 17, 16 ); 
-SoftwareSerial Bluetooth( 17, 16 ); //(7->RXblue , 8->TXblue
-//SLIPEncodedSerial SLIPSerial(SoftwareSerial);
+// Bluetooth serial communication (RX=17, TX=16)
+SoftwareSerial Bluetooth(17, 16);
 
 // the on-board LED
 int LED = 13;// Arduino pin numbers
 
-// the haptic-LEDs
-// UNO: PWM- int LEDPins[] = { 3, 5, 6, 9, 10, 11 };
-// LILY: PWM- int LEDPins[] = { 5, 6, 9, 10, 11 };
-int LEDPins[ ] = { 5, 6, 9, 10, 11 };
+// Haptic motor PWM pins
+int LEDPins[] = { 5, 6, 9, 10, 11 };
 
 int FrontLeft = 5;
 int FrontRight = 11;
@@ -35,11 +27,9 @@ int Center = 9;
 int CW[ ] = { Center, SideLeft, FrontLeft, FrontRight, SideRight, Center }; //3
 int CCW[ ] =  { Center, SideRight, FrontRight, FrontLeft, SideLeft, Center }; //4
 int PULSE[ ] = { Center, SideLeft, FrontLeft, Center, SideRight, FrontRight }; //7
-int PULSX[ ] = { Center, SideRight, FrontRight, Center, SideLeft, FrontLeft }; //7
+int PULSX[] = { Center, SideRight, FrontRight, Center, SideLeft, FrontLeft };
 
-// Pedro add -- wants pattern 1: C | 2: C-SL|SR-C | 3: C-SL|SR-FL|FR-SL|SR-C  // combo all together into pattern 4
-
-int FRONT[ ] = { 5, 6 };
+int FRONT[] = { 5, 6 };
 int BACK[ ] = { 10, 11, 9 };
 
 int FL[ ] = { 5, 5 }; // 5, 13
@@ -65,8 +55,7 @@ int numC;
 int freqC;
 int buzzC;
 
-void LED_wave( int PINS[ ], int PINlength, int count, int freq) {
-  //Bluetooth.println( "Testing LED array..." );
+void LED_wave( int PINS[], int PINlength, int count, int freq) {
   Serial.println("\nlights on");
   int delayTime = freq*100;
   Serial.print(delayTime);
@@ -84,28 +73,23 @@ void LED_wave( int PINS[ ], int PINlength, int count, int freq) {
 }
 
 void setup() {
-  Bluetooth.begin( 57600 ); //57600 115200
-  //SLIPSerial.begin( 115200 );
-  Serial.begin( 57600 );
+  Bluetooth.begin(57600);
+  Serial.begin(57600);
   pinMode( LED, OUTPUT );
   for ( index = 0; index <= 5; index++ ) {
     pinMode( LEDPins[ index ], OUTPUT );
   }
 }
 
-void loop() { 
-  //OSCBundle bundleIN;
+void loop() {
   int size;
-  int data = 4;;
+  int data = 4;
   delay(500);
-  if( (size=Bluetooth.available()) > 0 ) {
+  if ((size = Bluetooth.available()) > 0) {
     lights = false;
     Serial.println(data);
-    //Serial.println('\n');
-    while(size--) {
-      //Serial.println(data);
-      //int in = 0;
-      if (full==false) {
+    while (size--) {
+      if (full == false) {
         bundleIN[i] = Bluetooth.read();
         i++;
         if(i==data) {
@@ -187,66 +171,35 @@ void loop() {
           newIN = false;
         } else if (bundleIN[1]=='2') {
           for ( jindex = 0; jindex < numC; jindex++ ) {
-            digitalWrite(9, HIGH);   
+            digitalWrite(9, HIGH);
             delay(freqC*25);
-            digitalWrite(9, LOW);   
-            //delay(freqC*25);
-            //digitalWrite(9, HIGH);   
-            //delay(freqC*100);
-            //digitalWrite(9, LOW);
-            digitalWrite(6, HIGH);   
+            digitalWrite(9, LOW);
+            digitalWrite(6, HIGH);
             digitalWrite(10, HIGH);
-            delay(freqC*25);    
+            delay(freqC*25);
             digitalWrite(10, LOW);
-            digitalWrite(6, LOW);   
-            //digitalWrite(9, HIGH);
+            digitalWrite(6, LOW);
             delay(freqC*25);
-            //digitalWrite(9, LOW);          
-            //delay(freqC*50);
            }
           lights = true;
           newIN = false;
         } else if (bundleIN[1]=='3') {
           for ( jindex = 0; jindex < numC; jindex++ ) {
-            digitalWrite(9, HIGH);   
+            digitalWrite(9, HIGH);
             delay(freqC*25);
-            digitalWrite(9, LOW);   
+            digitalWrite(9, LOW);
             delay(freqC*25);
-            //digitalWrite(9, HIGH);   
-            //delay(freqC*50);
-            //digitalWrite(9, LOW);
-            digitalWrite(6, HIGH);   
+            digitalWrite(6, HIGH);
             digitalWrite(10, HIGH);
-            delay(freqC*25);    
+            delay(freqC*25);
             digitalWrite(10, LOW);
-            digitalWrite(6, LOW);   
+            digitalWrite(6, LOW);
             digitalWrite(11, HIGH);
             digitalWrite(5, HIGH);
             delay(freqC*25);
-            //digitalWrite(9, LOW);          
-            //delay(freqC*50);
-            //digitalWrite(9, HIGH);   
-            //delay(freqC*50);
-            //digitalWrite(9, LOW);
-            //digitalWrite(6, HIGH);   
-            //digitalWrite(10, HIGH);
-            //delay(freqC*50);    
-            //digitalWrite(6, LOW);   
-            //digitalWrite(10, LOW);
             digitalWrite(5, LOW);
             digitalWrite(11, LOW);
             delay(freqC*25);
-            //digitalWrite(5, LOW);   
-            //digitalWrite(11, LOW);
-            //digitalWrite(6, HIGH);
-            //digitalWrite(10, HIGH);
-            //delay(freqC*25); 
-            //digitalWrite(10, LOW);
-            //digitalWrite(6, LOW);   
-            //digitalWrite(9, HIGH);
-            //delay(freqC*25);
-            //digitalWrite(9, LOW);
-            //delay(freqC*100);
           }
           lights = true;
           newIN = false;
@@ -268,6 +221,5 @@ void loop() {
         newIN = false;      
       }
     }
-    //Serial.println('\n');
   }
 } 

docs/api/raspberry-pi-api.md

@@ -0,0 +1,155 @@
+# Arduino Bluetooth Server Examples
+
+This directory contains example implementations showing different ways to use the On-Body Haptics system.
+
+## Examples Overview
+
+### 1. send-pattern.js - Basic OSC Pattern Sender
+
+**What it does:** Sends a simple haptic pattern every second via OSC protocol
+
+**Use case:** Testing the system, learning the OSC message format
+
+**Usage:**
+```bash
+node examples/send-pattern.js
+```
+
+**Configuration:**
+- Update `remoteAddress` to point to your haptic server's IP
+- Update `remotePort` to match your haptic server's OSC port (default: 9998)
+
+### 2. websocket-server.js - WebSocket to OSC Bridge
+
+**What it does:** Creates a WebSocket server that receives messages from web clients and forwards them as OSC commands to the haptic server
+
+**Use case:** Web-based applications, browser-based controls, VR web apps
+
+**Usage:**
+```bash
+node examples/websocket-server.js
+```
+
+**Configuration:**
+- `WS_PORT`: WebSocket server port (default: 8080)
+- `OSC_REMOTE_ADDRESS`: IP of your haptic server
+- `OSC_REMOTE_PORT`: OSC port of your haptic server (default: 9998)
+
+**Client Usage:**
+Connect to the WebSocket server and send the string `"sendHaptics"` to trigger a pattern
+
+Example client code:
+```javascript
+const ws = new WebSocket('ws://localhost:8080');
+ws.onopen = () => {
+    ws.send('sendHaptics');
+};
+```
+
+### 3. threejs-vr-client.js - VR Head Tracking Integration
+
+**What it does:** Demonstrates how to integrate haptic feedback with Three.js VR applications using head/gaze tracking
+
+**Use case:** WebXR applications, VR experiences, interactive 3D environments
+
+**Usage:**
+Include this module in your Three.js VR application and call `intersectHead()` in your render loop
+
+**Integration:**
+```javascript
+import { intersectHead } from './threejs-vr-client.js';
+
+let raycaster = new THREE.Raycaster();
+let websocket = new WebSocket('ws://localhost:8080');
+
+function render() {
+    intersectHead(raycaster, camera, userObject, websocket);
+    renderer.render(scene, camera);
+}
+```
+
+## Example Integration Workflow
+
+1. **Start the haptic server:**
+   ```bash
+   node src/index.js 0.0.0.0 9998
+   ```
+
+2. **Start the WebSocket bridge (if needed):**
+   ```bash
+   node examples/websocket-server.js
+   ```
+
+3. **Test with pattern sender:**
+   ```bash
+   node examples/send-pattern.js
+   ```
+
+## Dependencies
+
+All examples require the `osc` package:
+```bash
+npm install osc
+```
+
+The WebSocket example also requires:
+```bash
+npm install ws
+```
+
+The Three.js example requires Three.js in your web application:
+```bash
+npm install three
+```
+
+## Custom Examples
+
+These examples serve as starting points. You can:
+
+- Modify the OSC message format to target different belts/buzzers
+- Change pattern parameters (repetitions, frequency)
+- Create custom WebSocket message protocols
+- Integrate with other 3D libraries or frameworks
+- Build custom UIs for haptic control
+
+## OSC Message Format
+
+All examples use the standard OSC format:
+
+**Buzzer control:**
+```
+/belt_{1-6}/buzzer_{1-5}/frequency
+Arguments: [repetitions, frequency]
+```
+
+**Pattern control:**
+```
+/belt_{1-6}/pattern_{1-4}/frequency
+Arguments: [repetitions, frequency]
+```
+
+**Belt 6 = All belts** (broadcasts to all configured devices)
+
+## Troubleshooting
+
+**"Cannot connect to server"**
+- Verify the haptic server is running
+- Check IP addresses and ports in your config
+- Ensure firewall allows UDP (OSC) and TCP (WebSocket) connections
+
+**"WebSocket connection refused"**
+- Ensure websocket-server.js is running
+- Check the WebSocket port (default: 8080)
+- Verify client is connecting to correct address
+
+**"No haptic feedback"**
+- Check Bluetooth connections to Arduino devices
+- Verify MAC addresses in `config/default.json`
+- Check server console for error messages
+- Ensure Arduino firmware is uploaded and running
+
+## Additional Resources
+
+- [OSC Protocol Specification](../../../docs/api/osc-protocol.md)
+- [Arduino API Documentation](../../../docs/api/arduino-api.md)
+- [Integration Guides](../../../docs/integration/)