Purpose

Standardize how the DJ controller communicates with:

• Cloud services (telemetry, stats, remote config)
• Connected PC (DAW, MIDI, GUI applications)
• Connected accessories (fader modules, jog wheels, extension PCBs)

Core Principles

• Simple, human-readable message format (JSON) with optional binary extension
• Explicit handshake: Exchange of Serial Number (SN) and Model Number (MN). Missing either allows usage — but with warning
• All cloud connections encrypted (minimum TLS 1.3). Sensitive data only transmitted pseudonymized
• Versioning and compatibility checks before executing critical commands

Actors

Supported Transport Layers

Principles

• Every unit has: serial_number (globally unique), model_number, firmware_version (semver)
• Handshake always at session start (e.g., after USB connect or TCP connect)
• If SN or MN is missing, handshake still proceeds — but the other side receives compatibility_warning

Handshake Sequence

{
  "type": "HELLO",
  "payload": {
    "serial_number": "MXR-20250701-000123",
    "model_number": "MXR-DJCTRL-v2",
    "firmware_version": "1.3.0",
    "protocol_version": "1.0"
  }
}

{
  "type": "HELLO_ACK",
  "payload": {
    "accepted": true,
    "compatibility": "FULL", // FULL | PARTIAL | UNKNOWN
    "warnings": [],
    "server_time": "2025-12-08T15:42:00Z"
  }
}

Extended Authentication (Cloud)

Controller ↔ Cloud: After HELLO, use mTLS (client cert) or JWT-based auth.

Recommendation: Mutual TLS with device client certificate (provisioned in production). Fallback: token-based with rotating keys via PKI.

Base Format

{
  "id": "uuid-v4",
  "type": "EVENT" | "CMD" | "REQ" | "RESP" | "HEARTBEAT",
  "ts": "2025-12-08T15:42:01Z",
  "from": {"role":"controller","serial":"..."},
  "to": {"role":"cloud"|"pc"|"accessory","serial":"..."},
  "payload": { ... }
}

Message Types

Framing / Binary

• Local (Serial): length-prefixed JSON recommended (4-byte length + payload)
• High performance: CBOR/MsgPack optional, but JSON as baseline

Compatibility Levels

When Serial Number is Missing

• Functionality: Full operation possible (if no security-critical functions)
• Policy: User-visible warning; cloud telemetry tagged serial_missing
• Reasoning: Allows developer boards & third-party accessories but retains traceability

When Model Number is Incompatible

• If critical mismatch (e.g., incompatible protocol version for motor control) → disable those features
• Otherwise → operate with reduced functionality

Warning Codes

Minimal Telemetry Event

{
  "type": "TELEMETRY",
  "payload": {
    "device": {
      "serial": "MXR-...",
      "model": "MXR-DJCTRL-v2",
      "fw": "1.3.0"
    },
    "uptime_seconds": 3600,
    "events": {
      "fader_moves": 1234,
      "cpu_temp_c": 52.3
    },
    "health": {
      "battery": 98,
      "errors": []
    }
  }
}

Standard Error Envelope

{ "code": 4001, "message": "MISSING_SERIAL", "fatal": false }

Fader board → Controller:

{
  "type": "EVENT",
  "payload": {"event": "FADER_MOVE", "chan": 3, "pos": 0.734}
}

Controller processes and forwards to PC GUI and (sampled) to Cloud:

{
  "type": "TELEMETRY",
  "payload": {
    "events": [{"event": "FADER_MOVE", "chan": 3, "pos": 0.734, "ts": "..."}]
  }
}

Controller sends HELLO:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "type": "HELLO",
  "ts": "2025-12-08T15:42:01Z",
  "from": {"role": "controller", "serial": "MXR-20250701-000123"},
  "to": {"role": "accessory"},
  "payload": {
    "model_number": "MXR-DJCTRL-v2",
    "firmware_version": "1.3.0",
    "protocol_version": "1.0",
    "feature_flags": ["motorized_faders", "ota"]
  }
}

Accessory responds HELLO_ACK (with missing serial):

{
  "id": "...",
  "type": "HELLO_ACK",
  "ts": "2025-12-08T15:42:01Z",
  "payload": {
    "accepted": true,
    "compatibility": "PARTIAL",
    "warnings": [{"code": "W001", "message": "serial_missing"}]
  }
}

Connection

// Node.js
const net = require('net');
const socket = new net.Socket();
socket.connect(5555, 'localhost');
socket.setNoDelay(true); // Always enable TCP_NODELAY

// Browser (via WebSocket bridge)
const ws = new WebSocket('ws://localhost:5556');

Message Format

All messages are JSON terminated with \n:

// Send command
socket.write('play 0\n');

// Receive event
// {"event":"deck_status","data":{...}}

Core Commands

List Tracks

// Request first 50 tracks
socket.write("cloud_list_tracks 50 0\n");

// Response event:
{"event":"cloud_tracks_list","data":{"tracks":[
  {"id":"track-123","title":"My Track","artist":"DJ Name",
   "duration":240,"bpm":128.0,"key":"Am","genre":"Techno",
   "fileSize":8388608,"format":"mp3"}
],"count":1}}

Get Metadata

socket.write("cloud_get_metadata track-123\n");

{"event":"cloud_track_metadata","data":{
  "id":"track-123","title":"My Track","bpm":128.0,
  "key":"Am","cuePoints":[{"time":0},{"time":32.5}],
  "loops":[{"start":0,"end":8.0}]
}}

Search Tracks

// cloud_search_tracks <query> <genre> <bpmMin> <bpmMax> <limit>
socket.write("cloud_search_tracks house Techno 120 135 20\n");

Command

// load_cloud_track <deck> <trackId>
socket.write("load_cloud_track 0 67980ec71648c734b60d9c06\n");

Event Flow

Setup

# Install DEMUCS
pip install demucs

# GPU acceleration (10-20x faster)
pip install demucs torch --index-url https://download.pytorch.org/whl/cu121

# Verify
python -m demucs --help

IPC Commands

Events

Processing Performance

Command

// Syntax: set_log <type> <0|1>
// Types: audio, effects, hardware, analysis, all

socket.write('set_log all 0\n');        // Silence everything
socket.write('set_log analysis 1\n');   // Only show BPM/key results
socket.write('set_log audio 1\n');      // Debug audio events
socket.write('set_log hardware 1\n');   // Debug hardware input

Default State

Register Device

POST /api/devices/register
X-Session-Token: <token>

{"serialNumber":"MXR-20250122-000001","modelNumber":"MXR-CTRL-ONE",
 "purchaseDate":"2025-01-22","nickname":"Studio Controller"}

Device Cloud Access (OCP Headers)

GET /api/device/cloud/tracks
X-OCP-Session: <session_id>
X-OCP-Token:   <device_token>
X-Device-Serial: MXR-20250122-000001

Cloud Endpoints (Device → Cloud)