Working BLE on S3

.gitignore

@@ -0,0 +1,27 @@
+# PlatformIO
+.pio/
+.pioenvs/
+.piolibdeps/
+lib/readme.txt
+
+# Python Virtual Environments
+venv/
+env/
+.venv/
+__pycache__/
+*.pyc
+
+# IDEs and Editors
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS Generated Files
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db

gemini.md

@@ -75,9 +75,9 @@ STEP_ANGLE    = 360/2048 ≈ 0.17578125 °/step
 ### UUIDs (must be identical in firmware AND `web/js/ble.js`)
 
 ```
-Service:  a0b1c2d3-e4f5-6789-abcd-ef0123456700
+Service:  18f3b235-9831-4c75-8ec0-210469b820a0
-Command:  a0b1c2d3-e4f5-6789-abcd-ef0123456701   (WRITE | WRITE_NR)
+Command:  cd083b06-4447-4cf3-a7c3-322ecf802ce4   (WRITE)
-Status:   a0b1c2d3-e4f5-6789-abcd-ef0123456702   (NOTIFY)
+Status:   82e38c5b-d3ab-41d1-861c-b84dc6bb1e03   (NOTIFY)
 Name:     WijiBoard
 ```
 
@@ -127,19 +127,8 @@ esp32s3-wiji/
 
 ### Module loading (index.html)
 
-All ES modules are loaded with a **cache-buster** to prevent stale code on refresh:
+All ES modules are loaded with static imports in `index.html`. 
-
+**CRITICAL**: Do NOT use dynamic cache-busting imports (e.g. `import('./ble.js?v=123')`) for the BLE module. Doing so causes the browser to instantiate multiple copies of the `BLE` singleton, breaking the event emitter (UI will not update when BLE connects).
-```javascript
-const V = Date.now();
-const { default: Router }         = await import(`./web/js/router.js?v=${V}`);
-const { default: BLE }            = await import(`./web/js/ble.js?v=${V}`);
-const { default: UI }             = await import(`./web/js/ui.js?v=${V}`);
-const { default: HomeSection }    = await import(`./web/js/sections/home.js?v=${V}`);
-const { default: StepperSection } = await import(`./web/js/sections/stepper-test.js?v=${V}`);
-```
-
-> The `?v=${V}` suffix on ES module imports is mandatory. Without it, browsers aggressively
-> cache modules and you will see stale code running despite file changes.
 
 ---
 
@@ -414,6 +403,8 @@ To add a new section:
 | **M1 at +d2, M2 at -d2** | This is the PositionControl.cpp convention. Reversing it causes visual arm crossing. Verified by tracing `xmd = x - d2` (offset from +d2 pivot) and `xpd = x + d2` (offset from -d2 pivot). |
 | **`forward()` picks upward EE** | Two circle-circle intersections exist; the mechanism always operates in the "above" configuration. The lower solution is physically blocked by the board. |
 | **`armsCrossed()` guard** | Prevents IK moves that would drive an elbow into the mechanism housing from the wrong side. Tunable via `LIMITS.ELBOW_BOX_X_INNER` and `ELBOW_BOX_Y_MAX`. |
+| **Linux/BlueZ stability** | `pAdv->setMaxPreferred(0x0C)` is mandatory in firmware. Without it, Linux/ChromeOS will drop the connection immediately after the handshake. |
+| **No dynamic BLE imports**| `index.html` must import `ble.js` via static `import`. Dynamic cache-busters create multiple instances of the BLE singleton, isolating UI event listeners! |
 | **`fivebarIKGame.js` is reference only** | The original site's game uses a different angle convention (absolute degrees, different home, with `ikElbowSigns` tracking). We use the C++ IK formula instead because it directly produces step deltas from home. `fivebarIKGame.js` is kept in the repo for reference and understanding, not imported. |
 | **Hash-based routing** | Keeps the SPA working from `file://` and simple static servers without needing a history API setup |
 

index.html

@@ -121,12 +121,11 @@
 
   <!-- ── App bootstrap (ES module entry point) ─────────────────── -->
   <script type="module">
-    const V = Date.now(); // cache-buster – ensures fresh module load on every page refresh
+    import Router from './web/js/router.js';
-    const { default: Router } = await import(`./web/js/router.js?v=${V}`);
+    import BLE from './web/js/ble.js';
-    const { default: BLE } = await import(`./web/js/ble.js?v=${V}`);
+    import UI from './web/js/ui.js';
-    const { default: UI } = await import(`./web/js/ui.js?v=${V}`);
+    import HomeSection from './web/js/sections/home.js';
-    const { default: HomeSection } = await import(`./web/js/sections/home.js?v=${V}`);
+    import StepperSection from './web/js/sections/stepper-test.js';
-    const { default: StepperSection } = await import(`./web/js/sections/stepper-test.js?v=${V}`);
 
     // ── Register routes ────────────────────────────────────────────
     Router.register('home', HomeSection);
@@ -177,8 +176,9 @@
         BLE.disconnect();
       } else {
         BLE.connect().catch(e => {
-          if (!e.message?.includes('cancelled') && !e.name?.includes('NotFound')) {
+          console.error('[BLE Connect Error]', e);
-            UI.log(`Connect error: ${e.message}`, 'error');
+          if (!e.message?.includes('cancelled')) {
+            UI.log(`Connect error: ${e.message} (${e.name})`, 'error');
           }
         });
       }

platformio.ini

@@ -12,6 +12,9 @@ build_flags =
     -D ARDUINO_USB_MODE=1
     -D ARDUINO_USB_CDC_ON_BOOT=1
 
+board_upload.flash_size = 4MB
+board_build.partitions = default.csv
+
 ; Adjust to your COM port
 monitor_speed = 115200
 upload_protocol = esptool

src/main.cpp

@@ -26,12 +26,12 @@
  *   Status   : a0b1c2d3-e4f5-6789-abcd-ef0123456702
  */
 
-#include <Arduino.h>
 #include <AccelStepper.h>
+#include <Arduino.h>
+#include <BLE2902.h>
 #include <BLEDevice.h>
 #include <BLEServer.h>
 #include <BLEUtils.h>
-#include <BLE2902.h>
 
 // ─── Motor pin mapping (28BYJ-48 / ULN2003) ──────────────────────
 // Motor 1 – Shoulder
@@ -52,9 +52,9 @@
 #define DEFAULT_ACCEL 100.0f // steps/sec²
 
 // ─── BLE UUIDs ────────────────────────────────────────────────────
-#define SERVICE_UUID    "a0b1c2d3-e4f5-6789-abcd-ef0123456700"
+#define SERVICE_UUID "18f3b235-9831-4c75-8ec0-210469b820a0"
-#define CMD_UUID        "a0b1c2d3-e4f5-6789-abcd-ef0123456701"
+#define CMD_UUID "cd083b06-4447-4cf3-a7c3-322ecf802ce4"
-#define STATUS_UUID     "a0b1c2d3-e4f5-6789-abcd-ef0123456702"
+#define STATUS_UUID "82e38c5b-d3ab-41d1-861c-b84dc6bb1e03"
 #define DEVICE_NAME "WijiBoard"
 
 // ─── Stepper objects ──────────────────────────────────────────────
@@ -62,9 +62,9 @@ AccelStepper stepper1(AccelStepper::FULL4WIRE, M1_IN1, M1_IN2, M1_IN3, M1_IN4);
 AccelStepper stepper2(AccelStepper::FULL4WIRE, M2_IN1, M2_IN2, M2_IN3, M2_IN4);
 
 // ─── BLE globals ─────────────────────────────────────────────────
-BLEServer*         pServer     = nullptr;
+BLEServer *pServer = nullptr;
-BLECharacteristic* pCmdChar    = nullptr;
+BLECharacteristic *pCmdChar = nullptr;
-BLECharacteristic* pStatusChar = nullptr;
+BLECharacteristic *pStatusChar = nullptr;
 bool bleConnected = false;
 
 // ─── Status notify throttle ───────────────────────────────────────
@@ -72,7 +72,7 @@ unsigned long lastNotify = 0;
 const unsigned long NOTIFY_INTERVAL_MS = 200;
 
 // ─── Forward declarations ─────────────────────────────────────────
-void parseCommand(const String& cmd);
+void parseCommand(const String &cmd);
 void sendPosition();
 void performHomingAll();
 void performHoming1();
@@ -80,11 +80,11 @@ void performHoming2();
 
 // ─── BLE Server Callbacks ─────────────────────────────────────────
 class ServerCallbacks : public BLEServerCallbacks {
-    void onConnect(BLEServer*) override {
+  void onConnect(BLEServer *) override {
     bleConnected = true;
     Serial.println("[BLE] Client connected");
   }
-    void onDisconnect(BLEServer*) override {
+  void onDisconnect(BLEServer *) override {
     bleConnected = false;
     Serial.println("[BLE] Client disconnected – restarting advertising");
     BLEDevice::startAdvertising();
@@ -93,20 +93,22 @@ class ServerCallbacks : public BLEServerCallbacks {
 
 // ─── Command Characteristic Callbacks ────────────────────────────
 class CmdCallbacks : public BLECharacteristicCallbacks {
-    void onWrite(BLECharacteristic* pChar) override {
+  void onWrite(BLECharacteristic *pChar) override {
     String val = pChar->getValue().c_str();
     val.trim();
-        if (val.length() == 0) return;
+    if (val.length() == 0)
+      return;
     Serial.printf("[CMD] Received: '%s'\n", val.c_str());
     parseCommand(val);
   }
 };
 
 // ─── Command parser ───────────────────────────────────────────────
-void parseCommand(const String& cmd) {
+void parseCommand(const String &cmd) {
   // S1+<n> or S1-<n>
   if (cmd.startsWith("S1") && cmd.length() > 2) {
-        long steps = cmd.substring(2).toInt();   // '+' or '-' prefix handled by toInt()
+    long steps =
+        cmd.substring(2).toInt(); // '+' or '-' prefix handled by toInt()
     stepper1.move(steps);
     Serial.printf("[S1] Move %+ld steps\n", steps);
     return;
@@ -165,9 +167,10 @@ void parseCommand(const String& cmd) {
 
 // ─── Send current positions via BLE NOTIFY ────────────────────────
 void sendPosition() {
-    if (!bleConnected || !pStatusChar) return;
+  if (!bleConnected || !pStatusChar)
-    String pos = "P:" + String(stepper1.currentPosition()) +
+    return;
-                 "," + String(stepper2.currentPosition());
+  String pos = "P:" + String(stepper1.currentPosition()) + "," +
+               String(stepper2.currentPosition());
   pStatusChar->setValue(pos.c_str());
   pStatusChar->notify();
   Serial.printf("[POS] %s\n", pos.c_str());
@@ -175,10 +178,9 @@ void sendPosition() {
 
 // ─── Setup ────────────────────────────────────────────────────────
 void setup() {
-    // Fix: zero TX buffer to eliminate CDC post-write stall
+  Serial.setTxTimeoutMs(0);
-    Serial.setTxBufferSize(0);
   Serial.begin(115200);
-    delay(500);
+  delay(1000); // Wait for USB CDC to enumerate
   Serial.println("\n[BOOT] WijiBoard Stepper Controller");
 
   // ── Init steppers ──────────────────────────────────────────
@@ -199,30 +201,27 @@ void setup() {
   pServer->setCallbacks(new ServerCallbacks());
 
   // Service
-    BLEService* pService = pServer->createService(SERVICE_UUID);
+  BLEService *pService = pServer->createService(SERVICE_UUID);
 
   // Command characteristic (Write without response)
-    pCmdChar = pService->createCharacteristic(
+  pCmdChar = pService->createCharacteristic(CMD_UUID,
-        CMD_UUID,
+                                            BLECharacteristic::PROPERTY_WRITE);
-        BLECharacteristic::PROPERTY_WRITE |
-        BLECharacteristic::PROPERTY_WRITE_NR
-    );
   pCmdChar->setCallbacks(new CmdCallbacks());
 
   // Status characteristic (Notify)
   pStatusChar = pService->createCharacteristic(
-        STATUS_UUID,
+      STATUS_UUID, BLECharacteristic::PROPERTY_NOTIFY);
-        BLECharacteristic::PROPERTY_NOTIFY
+  // pStatusChar->addDescriptor(new BLE2902()); // Removed due to
-    );
+  // deprecation/NimBLE conflicts
-    pStatusChar->addDescriptor(new BLE2902());
 
   pService->start();
 
   // Advertising
-    BLEAdvertising* pAdv = BLEDevice::getAdvertising();
+  BLEAdvertising *pAdv = BLEDevice::getAdvertising();
   pAdv->addServiceUUID(SERVICE_UUID);
   pAdv->setScanResponse(true);
-    pAdv->setMinPreferred(0x06);
+  pAdv->setMinPreferred(0x06); // 7.5ms
+  pAdv->setMaxPreferred(0x0C); // 15ms - CRITICAL for Linux/BlueZ stability
   BLEDevice::startAdvertising();
 
   Serial.printf("[BLE] Advertising as '%s' – ready!\n", DEVICE_NAME);

test_ble.py

@@ -0,0 +1,55 @@
+import asyncio
+import sys
+try:
+    from bleak import BleakScanner, BleakClient
+except ImportError:
+    print("Please install bleak first: pip install bleak")
+    sys.exit(1)
+
+DEVICE_NAME = "WijiBoard"
+SERVICE_UUID = "18f3b235-9831-4c75-8ec0-210469b820a0"
+CMD_UUID = "cd083b06-4447-4cf3-a7c3-322ecf802ce4"
+STATUS_UUID = "82e38c5b-d3ab-41d1-861c-b84dc6bb1e03"
+
+async def main():
+    print(f"Scanning for {DEVICE_NAME}...")
+    devices = await BleakScanner.discover(timeout=5.0)
+    
+    target_device = None
+    for d in devices:
+        if d.name == DEVICE_NAME:
+            target_device = d
+            break
+            
+    if not target_device:
+        print(f"Could not find {DEVICE_NAME}. Make sure it is powered on and advertising.")
+        return
+
+    print(f"Found {DEVICE_NAME} at {target_device.address}. Connecting...")
+    
+    async with BleakClient(target_device.address) as client:
+        print(f"Connected: {client.is_connected}")
+        
+        # Setup notifications
+        def notification_handler(sender, data):
+            print(f"[STATUS UPDATE] {data.decode('utf-8')}")
+            
+        print("Subscribing to status characteristic...")
+        try:
+            await client.start_notify(STATUS_UUID, notification_handler)
+            print("Successfully subscribed!")
+        except Exception as e:
+            print(f"Failed to subscribe: {e}")
+            
+        # Send a test command
+        test_cmd = "S1+100"
+        print(f"Sending test command: '{test_cmd}'...")
+        await client.write_gatt_char(CMD_UUID, test_cmd.encode('utf-8'), response=False)
+        
+        print("Waiting 5 seconds to receive any status updates...")
+        await asyncio.sleep(5.0)
+        
+        print("Disconnecting...")
+
+if __name__ == "__main__":
+    asyncio.run(main())

web/js/ble.js

@@ -25,9 +25,9 @@
  */
 
 // ── UUIDs – must match src/main.cpp exactly ──────────────────────
-const SERVICE_UUID  = 'a0b1c2d3-e4f5-6789-abcd-ef0123456700';
+const SERVICE_UUID = '18f3b235-9831-4c75-8ec0-210469b820a0';
-const CMD_UUID      = 'a0b1c2d3-e4f5-6789-abcd-ef0123456701';
+const CMD_UUID = 'cd083b06-4447-4cf3-a7c3-322ecf802ce4';
-const STATUS_UUID   = 'a0b1c2d3-e4f5-6789-abcd-ef0123456702';
+const STATUS_UUID = '82e38c5b-d3ab-41d1-861c-b84dc6bb1e03';
 const DEVICE_NAME = 'WijiBoard';
 
 const BLE = (() => {
@@ -75,34 +75,47 @@ const BLE = (() => {
 
   // ── connect() ───────────────────────────────────────────────
   async function connect() {
+    console.log('[BLE] connect() called');
     if (!navigator.bluetooth) {
       throw new Error('Web Bluetooth API not available. Use Chrome/Edge over HTTPS or localhost.');
     }
 
     emit('connecting');
 
+    console.log('[BLE] Requesting device...');
     device = await navigator.bluetooth.requestDevice({
       filters: [{ name: DEVICE_NAME }],
       optionalServices: [SERVICE_UUID],
     });
+    console.log('[BLE] Device selected:', device.name);
 
     device.addEventListener('gattserverdisconnected', onDisconnected);
 
+    console.log('[BLE] Connecting to GATT server...');
     server = await device.gatt.connect();
+    console.log('[BLE] GATT server connected');
 
+    console.log('[BLE] Getting primary service:', SERVICE_UUID);
     const service = await server.getPrimaryService(SERVICE_UUID);
+    console.log('[BLE] Primary service found');
 
+    console.log('[BLE] Getting command characteristic:', CMD_UUID);
     cmdChar = await service.getCharacteristic(CMD_UUID);
+    console.log('[BLE] Command characteristic found');
 
     // Status notifications (optional – firmware may not have this char yet)
     try {
+      console.log('[BLE] Getting status characteristic:', STATUS_UUID);
       statusChar = await service.getCharacteristic(STATUS_UUID);
+      console.log('[BLE] Starting notifications...');
       await statusChar.startNotifications();
       statusChar.addEventListener('characteristicvaluechanged', onStatusNotification);
-    } catch {
+      console.log('[BLE] Notifications started');
-      console.warn('[BLE] Status characteristic not available – notifications disabled');
+    } catch (err) {
+      console.warn('[BLE] Status characteristic not available – notifications disabled', err);
     }
 
+    console.log('[BLE] Connection fully established, emitting connected');
     emit('connected', device.name);
   }