WebSocket

FitOSC exposes a read-only WebSocket server that broadcasts live treadmill telemetry and app state. External tools and overlays can connect to consume this data in real time.

The WebSocket server must be enabled in Integrations settings before it can be used.

Connecting

ws://localhost:6547

The server listens on port 6547 by default. The port can be changed in the Integrations settings. All messages are JSON with properties serialized in camelCase.

Message Format

Every message from the server follows this envelope:

{
  "type": "string",
  "data": {}
}

Field	Type	Description
`type`	`string`	The message type: `state`, `pong`, or `error`.
`data`	`object`	The payload. Structure varies by type.

Commands

Clients can send commands to the server as JSON.

ping

{ "command": "ping" }

Server responds with:

{
  "type": "pong",
  "data": { "timestamp": 1700000000000 }
}

getstate

{ "command": "getstate" }

Server responds with a state message containing the current full app state.

Server Messages

state

Broadcast to all connected clients when state changes, and returned in response to getstate.

{
  "type": "state",
  "data": {
    "deviceName": "My Treadmill",
    "treadmillState": "Running",
    "unitSystem": "metric",
    "connections": {
      "bluetooth": "Connected",
      "vr": "Disconnected",
      "pulsoid": "Connected",
      "osc": "Disconnected"
    },
    "configuration": {
      "maxSpeed": 23.15,
      "minSpeed": 3.46,
      "speedIncrement": 0.58,
      "maxIncline": 9,
      "minIncline": 0,
      "inclineIncrement": 1,
      "speedUnit": "KPH"
    },
    "metrics": {
      "speed": { "value": 3.21, "unit": "KPH", "enabled": true },
      "avgSpeed": { "value": 3.10, "unit": "KPH", "enabled": true },
      "distance": { "value": 0.42, "unit": "KILOMETERS", "enabled": true },
      "incline": { "value": 1.0, "unit": "%", "enabled": true },
      "heartRate": { "value": 82, "unit": "BPM", "enabled": true },
      "elapsedTime": { "value": 480, "unit": "SECS", "enabled": true }
    },
    "walking": {
      "mode": "Dynamic",
      "velocity": 0.45,
      "horizontal": 0,
      "vertical": 0.45,
      "isManualOverride": false,
      "config": {
        "maxSpeed": 4.0,
        "walkingTrim": 1.25,
        "smoothingFactor": 0.8,
        "maxTurnAngle": 80,
        "updateIntervalMs": 12,
        "thumbstickRampSpeed": 0.05,
        "overrideSpeeds": [0, 0.25, 0.5, 0.75, 1],
        "currentOverrideIndex": 0
      }
    }
  }
}

Top-level Fields

Field	Type	Description
`deviceName`	`string \| null`	BLE device name of the connected treadmill. `null` when no device is connected.
`treadmillState`	`string`	Current treadmill state. See Treadmill States.
`unitSystem`	`string`	Unit system applied to all values in this payload. Either `"metric"` or `"imperial"`.
`connections`	`object`	Connection status for each integration. See Connections.
`configuration`	`object \| null`	Hardware limits reported by the treadmill. `null` when disconnected. See Configuration.
`metrics`	`object`	Live telemetry in the user's preferred unit system. See Metrics.
`walking`	`object`	Walking mode state and configuration. See Walking.

Treadmill States

Value	Description
`"Unknown"`	State cannot be determined.
`"Stopped"`	Treadmill is stopped.
`"Running"`	Treadmill belt is active.
`"Paused"`	Treadmill is paused.

Connections

Each key in connections is one of the following string values:

Value	Description
`"Disconnected"`	Not connected.
`"Connecting"`	Connection in progress.
`"Connected"`	Successfully connected.

Field	Description
`bluetooth`	BLE treadmill connection status.
`vr`	OpenVR/SteamVR runtime connection status.
`pulsoid`	Pulsoid heart rate monitor connection status.
`osc`	VRChat OSC connection status.

Configuration

Hardware limits as reported by the treadmill over BLE. This field is null when no device is connected.

Field	Type	Description
`maxSpeed`	`number`	Maximum supported belt speed.
`minSpeed`	`number`	Minimum supported belt speed.
`speedIncrement`	`number`	Speed adjustment step size.
`maxIncline`	`number`	Maximum incline level (%).
`minIncline`	`number`	Minimum incline level (%).
`inclineIncrement`	`number`	Incline adjustment step size (%).
`speedUnit`	`string`	Speed unit for this payload. Either `"KPH"` or `"MPH"`.

metrics is a flat object where each key is a named metric. All values are already converted to the user's preferred unit system (as indicated by unitSystem). A metric is null if the connected device does not support it.

Each metric has the following shape:

Field	Type	Description
`value`	`number`	Current reading.
`unit`	`string`	Unit label (e.g. `"KPH"`, `"BPM"`, `"KCAL"`).
`enabled`	`boolean`	Whether the device actively reports this metric.

Key	Unit (Metric)	Unit (Imperial)	Description
`speed`	`KPH`	`MPH`	Instantaneous belt speed.
`avgSpeed`	`KPH`	`MPH`	Session average speed.
`distance`	`KILOMETERS`	`MILES`	Total distance traveled.
`incline`	`%`	`%`	Current incline grade.
`rampAngle`	`%`	`%`	Ramp angle.
`elevationGain`	`METERS`	`FEET`	Cumulative elevation gained.
`pace`	`PACE`	`PACE`	Instantaneous pace.
`avgPace`	`PACE`	`PACE`	Session average pace.
`calories`	`KCAL`	`KCAL`	Estimated calories burned.
`heartRate`	`BPM`	`BPM`	Heart rate.
`met`	`MET`	`MET`	Metabolic equivalent.
`elapsedTime`	`SECS`	`SECS`	Session duration in seconds.
`remainingTime`	`SECS`	`SECS`	Remaining time in seconds (if set on treadmill).
`forceOnBelt`	`NEWTONS`	`NEWTONS`	Force applied to the belt.
`power`	`WATTS`	`WATTS`	Power output.
`stepCount`	`STEPS`	`STEPS`	Total step count.

Walking

Field	Type	Description
`mode`	`string`	Active walking mode: `"Disabled"`, `"Dynamic"`, or `"Override"`.
`velocity`	`number`	Combined locomotion magnitude sent to VRChat (`0.0` to `1.0`).
`horizontal`	`number`	Horizontal (strafe) locomotion component (`-1.0` to `1.0`).
`vertical`	`number`	Forward/backward locomotion component (`0.0` to `1.0`).
`isManualOverride`	`boolean`	`true` when a manual speed override is active.
`config`	`object`	Active walking configuration. See below.

Walking Config

Field	Type	Description
`maxSpeed`	`number`	Reference speed used for locomotion normalization.
`walkingTrim`	`number`	Speed multiplier applied to normalized output (`0.0`–`2.0`).
`smoothingFactor`	`number`	Locomotion output smoothing factor (`0.0`–`1.0`).
`maxTurnAngle`	`number`	Maximum yaw angle before direction adjusts (degrees).
`updateIntervalMs`	`number`	OSC update interval in milliseconds.
`thumbstickRampSpeed`	`number`	Thumbstick speed ramp rate (`0.01`–`0.5`).
`overrideSpeeds`	`number[]`	Preset speeds for Override mode (`0.0`–`1.0`).
`currentOverrideIndex`	`number`	Index of the active preset in `overrideSpeeds`.

On this page