Motion Grid Stream - WebSocket Integration Guide

This guide describes how to integrate Motion Grid Stream with your external applications using WebSocket communication.

Quick Start

1. Connect to WebSocket

ws://127.0.0.1:12349

2. Client Authorization (Optional)

If authorization is enabled in MotionCube Player settings, the client must send an authorization message within 5 seconds of connecting:

ℹ️ Authorization is disabled by default. It can be enabled in MotionCube Player settings, where you can also configure the auth_key.

{
  "command": "AUTH_REQUEST",
  "auth_key": "YOUR_AUTH_KEY"
}

Success response:

{
  "type": "AUTH_COMPLETED"
}

⚠️ If authorization is enabled and the client fails to send a valid AUTH_REQUEST within 5 seconds, the connection will be closed.

ℹ️ Authorization can be enabled/disabled in MotionCube Player settings, where you can also configure the auth_key.

3. Wait for Ready Signal

After connecting, wait for the server to send:

{
  "status": "ready",
  "setting": "grid",
  "data": {
    "columns": 32,
    "rows": 24
  }
}

This message contains the current grid configuration from the server.

⚠️ Do not send commands before receiving this message.

4. Start Streaming

Send start command with grid dimensions:

{"command": "start", "params": {"cols": 32, "rows": 24}}

5. Receive Frame Data

Server streams data in this format:

{
  "frame": 1,
  "timestamp": 1737654321000,
  "indexes": [0, 5, 12, 47]
}

Index calculation:

index = row * cols + col

6. Stop Streaming

{"command": "stop"}

Message Reference

Client → Server

Server → Client

Example (Pseudocode)

ws = WebSocket.connect("ws://127.0.0.1:12351")
gridCols = 0
gridRows = 0

on ws.open:
    // Send authorization if enabled in MotionCube Player
    ws.send({"command": "AUTH_REQUEST", "auth_key": "YOUR_AUTH_KEY"})

on ws.message(data):
    msg = JSON.parse(data)

    if msg.type == "AUTH_COMPLETED":
        // Authorization successful, wait for ready signal
        return

    if msg.status == "ready":
        gridCols = msg.data.columns
        gridRows = msg.data.rows
        ws.send({"command": "start", "params": {"cols": gridCols, "rows": gridRows}})

    if msg.frame != null:
        for index in msg.indexes:
            col = index % gridCols
            row = index / gridCols
            // Handle active cell at (col, row)

on ws.close:
    // Handle disconnection