TCP Sockets: Get Data from a Scorelink

Legacy protocol notice

TCP socket access is maintained for backward compatibility.
For new implementations, use MQTT instead.

  • New integrations should follow: MQTT: Get Data from a Scorelink
  • TCP clients may require more state handling and are easier to misconfigure in cloud mode.

Overview

This page documents the legacy TCP socket flow to consume scoreboard data from:

  • Sportzcast cloud cluster
  • ScoreConnect III (local)
  • Scorelink+ (local)

TCP communication uses port 1402 and command/response messages over a raw socket.

Before you start

Cloud prerequisites

  1. Active user account in www.sportzcast.net
  2. User email and access token
  3. Active license
  4. Bot(s) assigned to your account

Local prerequisites

  1. Client and local BotServer are on the same network
  2. TCP port 1402 is reachable
  3. Local BotServer service is running

Protocol basics

  • Commands are ASCII strings (no delimiter required).
  • BotServer responses are framed with:
    • STX at start (0x02)
    • ETX at end (0x03)
  • Always strip STX/ETX and parse only payload content.
  • Most response payloads are pipe-separated (|) fields.

Connection flow (legacy state machine)

Typical cloud flow:

  1. GT authenticate and receive connection token
  2. FB resolve the current bot node in the cluster
  3. ST/XB/JB request stream from that node
  4. EX disconnect when done

For local deployments, implementations may connect directly to the local BotServer and stream data without cloud node lookup, depending on environment configuration.

Step 1: Authenticate (GT)

Connect to cloud entrypoint (or local BotServer) on port 1402, then send:

GT <email> <userToken>

Expected response is pipe-separated. Important fields:

  • Position 1: authentication valid (1 or 0)
  • Position 3: connection token (used in stream request)

If auth fails due to credentials/license, stop and correct account state before retrying.

Step 2: Find bot node (FB)

Send bot lookup command (5-digit, zero-padded bot id):

FB<botNumber>

Example:

FB05083

Results:

  • DNS/IP of node serving the bot (success)
  • ERR if bot is unavailable/not found

If you receive ERR, wait at least 10 seconds before retrying.

Step 3: Request stream (ST/XB/JB)

Open a socket to the node returned in Step 2 and send:

<DataType><Bot5Digits><Delay5Digits><Channel>~<ConnectionToken>

Field details:

  • DataType
    • ST = SB Data
    • XB = XML
    • JB = JSON
  • Bot5Digits: zero-padded (e.g. bot 23 -> 00023)
  • Delay5Digits: delay in ms, zero-padded (00000 for no delay)
  • Channel: one digit, usually 0
  • ~: separator
  • ConnectionToken: token returned by GT

Example:

ST00023000000~D1E77615B10F92F9033

Then keep socket open and continuously frame payloads by STX/ETX.

Step 4: Disconnect (EX)

When finished, send:

EX

Socket should close shortly after.

Netcat examples (Linux/macOS)

Authenticate:

echo -n "GT your-email@domain.com your-token" | nc scorebot.sportzcast.net 1402

Find bot:

echo -n "FB05083" | nc scorebot.sportzcast.net 1402

Start stream (example):

echo -n "ST05083000000~YourConnectionToken" | nc <resolved-node-hostname> 1402

Operational cautions

  • Do not repeatedly retry failed commands in short intervals.
  • After FB returns ERR, wait at least 10 seconds before reattempt.
  • Rapid repeated stream requests can lead to temporary IP blacklisting.
  • If stream command fails, bot may have moved nodes; repeat FB and reconnect.

Why MQTT is preferred

TCP socket integration remains available for compatibility, but MQTT is the recommended interface for ongoing development:

  • Simpler connection model
  • Better ecosystem support in modern client libraries
  • Cleaner subscription semantics for multi-bot/multi-format consumption
  • Better long-term support path

Use MQTT documentation for all greenfield integrations: MQTT: Get Data from a Scorelink