Merge pull request #31 from constructive-io/feat/osc-debug-logging

feat(osc): DEBUG_OSC logging flag + default BEYOND port to 7001

Author: pyramation

packages/osc/README.md

@@ -30,7 +30,7 @@ const receiver = new Receiver({
   input: new WebSocketInput({ url: 'ws://192.168.1.50:3000' }),
   output: new BeyondOscOutput({
     host: '192.168.50.10',
-    port: 9000,
+    port: 7001,
     projectorMap: { 0: 0, 1: 1, 2: 2 }
   })
 });
@@ -59,7 +59,7 @@ receiver.start();
 ```json
 {
   "targets": {
-    "beyond-a": { "type": "beyond", "host": "192.168.50.10", "port": 9000 },
+    "beyond-a": { "type": "beyond", "host": "192.168.50.10", "port": 7001 },
     "fb4-b":    { "type": "fb4",    "host": "192.168.50.20", "port": 8000 }
   },
   "flushHz": 30,

packages/osc/src/index.ts

@@ -13,6 +13,7 @@ export type {
 } from './osc-adapters';
 export {
   BeyondOscOutput,
+  DEBUG_OSC,
   FB4OscOutput,
   RoutedOscOutput,
   createRoutedOutput,

packages/osc/src/osc-adapters.ts

@@ -16,6 +16,9 @@ import { CannonState, OutputAdapter } from 'wavegrid';
 
 import { hsbToRgb100, hsbToRgb255 } from './color';
 
+/** When true, log every OSC message sent. Set via DEBUG_OSC=1 env var. */
+export const DEBUG_OSC = !!process.env.DEBUG_OSC;
+
 // ═══════════════════════════════════════════════════
 // Types
 // ═══════════════════════════════════════════════════
@@ -103,6 +106,13 @@ export class BeyondOscOutput implements OutputAdapter {
     if (!this.client) return;
 
     const messages = encodeBeyondMessages(grid, this.config.projectorMap);
+    if (DEBUG_OSC && messages.length > 0) {
+      const sample = messages.slice(0, 4);
+      const lines = sample.map(m => `    ${m.address} = ${m.value}`);
+      console.log(`  [OSC→BEYOND] frame ${this.frameCount} | ${messages.length} msgs to ${this.config.host}:${this.config.port}`);
+      for (const line of lines) console.log(line);
+      if (messages.length > 4) console.log(`    ... +${messages.length - 4} more`);
+    }
     for (const msg of messages) {
       this.client.send(msg.address, msg.value);
     }
@@ -188,6 +198,13 @@ export class FB4OscOutput implements OutputAdapter {
     if (!this.client) return;
 
     const messages = encodeFB4Messages(grid, this.config.serialMap);
+    if (DEBUG_OSC && messages.length > 0) {
+      const sample = messages.slice(0, 3);
+      const lines = sample.map(m => `    ${m.address} = ${m.value}`);
+      console.log(`  [OSC→FB4] frame ${this.frameCount} | ${messages.length} msgs to ${this.config.host}:${this.config.port}`);
+      for (const line of lines) console.log(line);
+      if (messages.length > 3) console.log(`    ... +${messages.length - 3} more`);
+    }
     for (const msg of messages) {
       this.client.send(msg.address, msg.value);
     }

packages/receiver/README.md

@@ -72,7 +72,8 @@ receiver.start();
 | `GRID_COLUMNS` | `7` | Number of columns in the grid |
 | `ROUTING_CONFIG` | — | Path to JSON routing config (enables OSC) |
 | `BEYOND_HOST` | — | Quick single-target BEYOND OSC host |
-| `BEYOND_PORT` | `9000` | BEYOND OSC port |
+| `BEYOND_PORT` | `7001` | BEYOND OSC port |
+| `DEBUG_OSC` | — | Set to `1` to log all OSC messages |
 | `FB4_HOST` | — | Quick single-target FB4 OSC host |
 | `FB4_PORT` | `8000` | FB4 OSC port |
 

packages/receiver/src/main.ts

@@ -61,7 +61,7 @@ if (hasOscConfig) {
 
     if (process.env.BEYOND_HOST) {
       const host = process.env.BEYOND_HOST;
-      const port = parseInt(process.env.BEYOND_PORT || '9000', 10);
+      const port = parseInt(process.env.BEYOND_PORT || '7001', 10);
       const projectorMap: Record<number, number> = {};
       for (let i = 0; i < NUM_CANNONS; i++) projectorMap[i] = i;
       const beyond = new osc.BeyondOscOutput({ host, port, projectorMap });
@@ -116,6 +116,7 @@ console.log(`  → Output: ${outputLabels.join(' + ')}`);
 console.log(`  → Alpha: ${ALPHA}  Fallback delay: ${FALLBACK_DELAY}ms`);
 console.log(`  → Grid: ${NUM_CANNONS} cannons (${GRID_COLUMNS} columns)`);
 console.log(`  → Shard: ${shard ? `cannons ${shard.start}–${shard.end} (${shard.end - shard.start + 1} of ${NUM_CANNONS})` : `all cannons (no shard)`}`);
+if (process.env.DEBUG_OSC) console.log('  → DEBUG_OSC: enabled (logging all OSC messages)');
 console.log('');
 
 receiver.start();