feat: OSC debugger in Advanced, a doctor probe that can actually fail, and BEYOND on 8000

README.md

@@ -165,7 +165,7 @@ When the UI/Server run on a cloud server and the laser hardware is on-site:
 │  Server (:3000)     ◄─────────────┼──────────────┼──  Receiver                  │
 │  UI (:3003)                       │              │       │                      │
 │                                   │              │       ▼ OSC/UDP (localhost)  │
-│  Artists connect via browser      │              │    BEYOND (:7001)            │
+│  Artists connect via browser      │              │    BEYOND (:8000)            │
 └───────────────────────────────────┘              └──────────────────────────────┘
 ```
 
@@ -184,7 +184,7 @@ PowerShell:
 ```powershell
 $env:SIMULATOR_URL = "ws://203.0.113.50:3000"
 $env:BEYOND_HOST = "127.0.0.1"
-$env:BEYOND_PORT = "7001"
+$env:BEYOND_PORT = "8000"
 $env:SHARD_START = "0"
 $env:SHARD_END = "23"
 $env:DEBUG_OSC = "1"
@@ -195,7 +195,7 @@ Bash (Linux/macOS):
 ```sh
 SIMULATOR_URL=ws://203.0.113.50:3000 \
 BEYOND_HOST=127.0.0.1 \
-BEYOND_PORT=7001 \
+BEYOND_PORT=8000 \
 SHARD_START=0 \
 SHARD_END=23 \
 DEBUG_OSC=1 \
@@ -223,7 +223,7 @@ When a single BEYOND PC can't handle all 49 zones, split the grid across multipl
           ▼                   ▼
   ┌──────────────┐    ┌──────────────┐
   │  BEYOND A    │    │  BEYOND B    │
-  │  .1.68:7001  │    │  .1.69:7001  │
+  │  .1.68:8000  │    │  .1.69:8000  │
   │  zones 0–23  │    │  zones 0–24  │
   └──────────────┘    └──────────────┘
 ```
@@ -233,8 +233,8 @@ Create a `routing.json` file (see `examples/routing-two-beyond.json` for a full
 ```json
 {
   "targets": {
-    "beyond-a": { "type": "beyond", "host": "192.168.1.68", "port": 7001 },
-    "beyond-b": { "type": "beyond", "host": "192.168.1.69", "port": 7001 }
+    "beyond-a": { "type": "beyond", "host": "192.168.1.68", "port": 8000 },
+    "beyond-b": { "type": "beyond", "host": "192.168.1.69", "port": 8000 }
   },
   "flushHz": 30,
   "cannons": [
@@ -315,7 +315,7 @@ Project config lives in the store (`wavegrid projects config`) — env vars are
 | `WG_RECEIVER_KEY` | store value | Receiver auth key (override to share across laptops) |
 | `SIMULATOR_URL` | `ws://localhost:3000` | WebSocket upstream for the receiver |
 | `BEYOND_HOST` | — | BEYOND PC IP (enables OSC output) |
-| `BEYOND_PORT` | `7001` | BEYOND OSC receive port |
+| `BEYOND_PORT` | `8000` | BEYOND OSC receive port |
 | `BEYOND_GRID_ORDER` | `row` | Grid-to-zone mapping: `row` or `column` |
 | `SHARD_START` / `SHARD_END` | — | Cannon index range for this receiver |
 | `DEBUG_OSC` | — | Set to `1` to log every OSC message |

deploy/.env.example

@@ -53,7 +53,7 @@ SIM_PORT=3000
 
 # OSC output — pick ONE: a single BEYOND target, or a routing config file.
 # BEYOND_HOST=127.0.0.1
-# BEYOND_PORT=7001
+# BEYOND_PORT=8000
 # BEYOND_GRID_ORDER=row        # "row" or "column"
 
 # Multi-target routing: generate deploy/routing.json with

deploy/README.md

@@ -79,7 +79,7 @@ Configure OSC output in `deploy\.env` — either a single BEYOND target
 | `SIMULATOR_URL`             | pangolin| `ws://CLOUD_IP:SIM_PORT` | receiver → server (derived) |
 | `RECEIVER_ALPHA`            | pangolin| `0.06`           | smoothing                           |
 | `FALLBACK_DELAY`            | pangolin| `3000`           | ms before sine fallback             |
-| `BEYOND_HOST`/`BEYOND_PORT` | pangolin| — / `7001`       | single BEYOND OSC target            |
+| `BEYOND_HOST`/`BEYOND_PORT` | pangolin| — / `8000`       | single BEYOND OSC target            |
 | `BEYOND_GRID_ORDER`         | pangolin| `row`            | `row` or `column`                   |
 | `ROUTING_CONFIG`            | pangolin| —                | JSON routing file (multi-target)    |
 | `DEBUG_OSC`                 | pangolin| —                | set to `1` to log all OSC           |

deploy/gen-config.js

@@ -123,7 +123,7 @@ async function main() {
     cloudIp: args['cloud-ip'] || existing.cloudIp || env.CLOUD_IP || '',
     beyondA: args['beyond-a'] || (exTargets['beyond-a'] && exTargets['beyond-a'].host) || env.BEYOND_A_HOST || '192.168.1.68',
     beyondB: args['beyond-b'] || (exTargets['beyond-b'] && exTargets['beyond-b'].host) || env.BEYOND_B_HOST || '192.168.1.69',
-    port: parseInt(args.port || env.BEYOND_PORT || (exTargets['beyond-a'] && exTargets['beyond-a'].port) || '7001', 10),
+    port: parseInt(args.port || env.BEYOND_PORT || (exTargets['beyond-a'] && exTargets['beyond-a'].port) || '8000', 10),
     flushHz: parseInt(args['flush-hz'] || existing.flushHz || '30', 10),
     cannons: parseInt(args.cannons || env.NUM_CANNONS || '49', 10),
     columns: parseInt(args.columns || env.GRID_COLUMNS || '7', 10),

docs/event-deployment.md

@@ -14,12 +14,12 @@ graph LR
 
     subgraph PangolinPC["🖥️ Pangolin PC (Windows, on-site)"]
         RX["Receiver"]
-        BEYOND["BEYOND :7001"]
+        BEYOND["BEYOND :8000"]
     end
 
     BROWSER -- "http + ws @ ‹CLOUD_IP›:3000" --> SIM
     SIM -- "ws://‹CLOUD_IP›:3000" --> RX
-    RX -- "OSC/UDP localhost:7001" --> BEYOND
+    RX -- "OSC/UDP localhost:8000" --> BEYOND
 ```
 
 **Three devices, three roles:**
@@ -52,7 +52,7 @@ Open **http://‹CLOUD_IP›:3000** in the browser (the browser derives its WebS
 ```powershell
 $env:SIMULATOR_URL = "ws://<CLOUD_IP>:3000"
 $env:BEYOND_HOST = "127.0.0.1"
-$env:BEYOND_PORT = "7001"
+$env:BEYOND_PORT = "8000"
 $env:SHARD_START = "0"
 $env:SHARD_END = "23"
 $env:DEBUG_OSC = "1"
@@ -66,8 +66,8 @@ Use a routing config instead of `BEYOND_HOST`. Save `routing.json` in the repo r
 ```json
 {
   "targets": {
-    "beyond-a": { "type": "beyond", "host": "<BEYOND_A_IP>", "port": 7001 },
-    "beyond-b": { "type": "beyond", "host": "<BEYOND_B_IP>", "port": 7001 }
+    "beyond-a": { "type": "beyond", "host": "<BEYOND_A_IP>", "port": 8000 },
+    "beyond-b": { "type": "beyond", "host": "<BEYOND_B_IP>", "port": 8000 }
   },
   "flushHz": 30,
   "cannons": [
@@ -134,10 +134,15 @@ graph TD
 
 ## Troubleshooting
 
+Advanced → OSC in the desktop app is the fastest first look: it shows the
+resolved target and port, probes it, reads BEYOND.ini where BEYOND is installed
+locally, sends blackout / full white / full amber (one zone or all) and tails
+every message in and out.
+
 | Symptom | Fix |
 |---------|-----|
 | UI loads but painting does nothing | The browser's WebSocket is same-origin — make sure you opened the UI at the server's real host:port (not localhost) and port 3000 is reachable |
-| Receiver connects but no laser response | Verify BEYOND's OSC server is on port 7001, and "Show R-G-B-A panel" is enabled in BEYOND settings |
+| Receiver connects but no laser response | Verify BEYOND's OSC server is on port 8000, and "Show R-G-B-A panel" is enabled in BEYOND settings |
 | Colors wrong in `rgb` mode | Confirm `alpha` is being sent (check `DEBUG_OSC=1` output for `/livecontrol/alpha 255`) |
 | Receiver can't connect to server | Check cloud firewall allows inbound on port 3000 |
 | White shows as red | Ensure BEYOND's RGBA panel is enabled: Settings → Configuration → Live Control → Extra Controls → "Show R-G-B-A panel" |

examples/routing-two-beyond.json

@@ -3,12 +3,12 @@
     "beyond-a": {
       "type": "beyond",
       "host": "192.168.1.68",
-      "port": 7001
+      "port": 8000
     },
     "beyond-b": {
       "type": "beyond",
       "host": "192.168.1.69",
-      "port": 7001
+      "port": 8000
     }
   },
   "flushHz": 30,

packages/cli/README.md

@@ -106,7 +106,7 @@ hand, over the project's configured OSC target (or `--host` / `--port`):
 ```sh
 wavegrid signals send /beyond/zone/0/livecontrol/red 255   # one message
 wavegrid signals probe --zones 0-11 --hold 500             # light one zone at a time
-wavegrid signals listen --port 7001                        # print what arrives
+wavegrid signals listen --port 8000                        # print what arrives
 ```
 
 `send` arguments are floats unless tagged (`i:3` integer, `s:text` string), since
@@ -116,8 +116,9 @@ binds a port, so pointing the show at `--host 127.0.0.1 --port <n>` shows the
 exact stream the hardware would receive.
 
 For BEYOND to act on any of it, its OSC server must be enabled (BEYOND's
-settings — check the port there rather than assuming; `projects osc` defaults to
-7001 for BEYOND, 8000 for FB4) and the zone has to be under live control.
+settings — `[OSC] PortIn` in BEYOND.ini is the value it actually binds; `projects
+osc` defaults to 8000, BEYOND's factory port) and the zone has to be under live
+control.
 
 This is aimed output on a configured target, unrelated to
 [`tools/traffic`](../../tools/traffic), which stays passive — it observes

packages/cli/__tests__/osc-signals.test.ts

@@ -20,10 +20,12 @@ describe('resolveTarget', () => {
 
   it('prefers flags over config, and defaults the port per kind', () => {
     const config = { osc: { beyond: { host: '192.168.1.50', port: 7001 } } };
+    // A --host makes the target explicit, so the port is BEYOND's default, not
+    // the configured project's.
     expect(resolveTarget({ host: '127.0.0.1' }, config)).toMatchObject({
       kind: 'beyond',
       host: '127.0.0.1',
-      port: 7001,
+      port: 8000,
       origin: 'flags'
     });
     expect(resolveTarget({ host: '127.0.0.1', kind: 'fb4' }, config)).toMatchObject({

packages/cli/__tests__/osc.test.ts

@@ -39,7 +39,7 @@ describe('runOscSetup', () => {
     await runOscSetup('beyond', { host: '192.168.1.50' });
 
     expect(store.getProjectConfig('ring-demo')?.osc).toEqual({
-      beyond: { host: '192.168.1.50', port: 7001, gridOrder: 'row' }
+      beyond: { host: '192.168.1.50', port: 8000, gridOrder: 'row' }
     });
   });
 

packages/cli/src/cli.ts

@@ -72,7 +72,7 @@ ${c.bold('Run')}
 ${c.bold('Signals')} — hand-driven OSC for debugging Pangolin
   signals send <addr> [args]    Send one OSC message to the configured target
   signals probe [--zones 0-11]  Light one zone/fixture at a time, to find the mapping
-  signals listen [--port 7001]  Print every OSC message arriving on a port
+  signals listen [--port 8000]  Print every OSC message arriving on a port
 
 ${c.bold('Receiver options')}
   --server <ws-url>   Brain to connect to (e.g. ws://192.168.1.42:3333)

packages/cli/src/commands/osc-signals.ts

@@ -10,7 +10,7 @@
  * Aiming: the project's configured OSC target by default (so this debugs the
  * same path the show uses), or `--host/--port` for a one-off.
  */
-import { loadWavegridConfig } from '@wavegrid/layout';
+import { DEFAULT_BEYOND_PORT, DEFAULT_FB4_PORT, loadWavegridConfig } from '@wavegrid/layout';
 import {
   BeyondOscOutput,
   type CannonState,
@@ -31,11 +31,11 @@ export const SIGNALS_USAGE = [
   '    wavegrid signals send /beyond/zone/0/livecontrol/red 255',
   '    wavegrid signals send /FB4-12345/color_red 100 --host 192.168.1.50 --port 8000',
   '    wavegrid signals probe [--zones 0-11] [--hold 500] [--hue 40]',
-  '    wavegrid signals listen [--port 7001]',
+  `    wavegrid signals listen [--port ${DEFAULT_BEYOND_PORT}]`,
   '',
   '  Options:',
   '    --host <ip>      Override the project\'s OSC host',
-  '    --port <n>       Override the port (BEYOND 7001, FB4 8000)',
+  `    --port <n>       Override the port (BEYOND ${DEFAULT_BEYOND_PORT}, FB4 ${DEFAULT_FB4_PORT})`,
   '    --dry-run        Print what would be sent, send nothing',
   '',
   '  Arguments are floats unless tagged: `i:3` integer, `s:text` string.',
@@ -74,7 +74,12 @@ export function resolveTarget(flags: Flags, config: { osc: { beyond?: { host: st
 
   if (host) {
     const kind = kindFlag === 'fb4' ? 'fb4' : 'beyond';
-    return { kind, host, port: port ?? (kind === 'fb4' ? 8000 : 7001), origin: 'flags' };
+    return {
+      kind,
+      host,
+      port: port ?? (kind === 'fb4' ? DEFAULT_FB4_PORT : DEFAULT_BEYOND_PORT),
+      origin: 'flags'
+    };
   }
   if (config.osc.beyond) {
     return {
@@ -88,7 +93,7 @@ export function resolveTarget(flags: Flags, config: { osc: { beyond?: { host: st
     return {
       kind: 'fb4',
       host: config.osc.fb4.host,
-      port: port ?? config.osc.fb4.port ?? 8000,
+      port: port ?? config.osc.fb4.port ?? DEFAULT_FB4_PORT,
       origin: 'project config (FB4)'
     };
   }
@@ -218,7 +223,7 @@ export async function runSignalsProbe(flags: Flags): Promise<void> {
 
 /** Sit on a port and print what arrives. Ctrl-C to stop. */
 export async function runSignalsListen(flags: Flags): Promise<void> {
-  const port = num(flags, 'port') ?? 7001;
+  const port = num(flags, 'port') ?? DEFAULT_BEYOND_PORT;
   const host = str(flags, 'host') ?? '0.0.0.0';
   let seen = 0;
 

packages/cli/src/commands/osc.ts

@@ -1,4 +1,11 @@
-import { LOOPBACK_HOST, normalizeOscHost, type OscConfig, type WavegridConfig } from '@wavegrid/layout';
+import {
+  DEFAULT_BEYOND_PORT,
+  DEFAULT_FB4_PORT,
+  LOOPBACK_HOST,
+  normalizeOscHost,
+  type OscConfig,
+  type WavegridConfig
+} from '@wavegrid/layout';
 import type { Inquirerer, Question } from 'inquirerer';
 import c from 'yanse';
 
@@ -31,8 +38,8 @@ function confirm(project: string, osc: OscConfig | undefined): void {
 const USAGE = [
   '  Usage:',
   '    wavegrid projects osc                      (interactive wizard)',
-  '    wavegrid projects osc beyond --host <ip> [--port 7001] [--grid-order row|column]',
-  '    wavegrid projects osc fb4 --host <ip> [--port 8000]',
+  `    wavegrid projects osc beyond --host <ip> [--port ${DEFAULT_BEYOND_PORT}] [--grid-order row|column]`,
+  `    wavegrid projects osc fb4 --host <ip> [--port ${DEFAULT_FB4_PORT}]`,
   '    wavegrid projects osc routing --file <path-to-routing.json>',
   '    wavegrid projects osc show',
   '    wavegrid projects osc clear'
@@ -55,7 +62,7 @@ function applyFromFlags(flags: Flags, kind: string): boolean {
   if (kind === 'beyond') {
     const host = normalizeOscHost(str(flags, 'host') ?? '');
     if (!host) return false;
-    const port = num(flags, 'port') ?? 7001;
+    const port = num(flags, 'port') ?? DEFAULT_BEYOND_PORT;
     const gridOrder = str(flags, 'grid-order') === 'column' ? 'column' : 'row';
     const project = save(flags, (config) => {
       config.osc = { beyond: { host, port, gridOrder } };
@@ -66,7 +73,7 @@ function applyFromFlags(flags: Flags, kind: string): boolean {
   if (kind === 'fb4') {
     const host = normalizeOscHost(str(flags, 'host') ?? '');
     if (!host) return false;
-    const port = num(flags, 'port') ?? 8000;
+    const port = num(flags, 'port') ?? DEFAULT_FB4_PORT;
     const project = save(flags, (config) => {
       config.osc = { fb4: { host, port } };
     });
@@ -98,7 +105,7 @@ async function wizardBeyond(prompter: Inquirerer, current?: OscConfig): Promise<
       type: 'number',
       name: 'port',
       message: 'BEYOND OSC port',
-      default: current?.beyond?.port ?? 7001,
+      default: current?.beyond?.port ?? DEFAULT_BEYOND_PORT,
       required: true
     } as Question,
     {