Documentation
Tips
This documentation is under active development as we craft the best development experience possible for the motorsport industry.
All feedback is welcome to wes@volarehq.com!
Overview
Volare Realtime uses JSON messages passed through a WebSocket connection. Alternatively, a REST/JSON API is available for one-off commands.
This API is modeled after pub/sub and RPC-style calls to fit exiting industry patterns.
REST API
- Public:
https://realtime.volarehq.com - On-site:
http://local-ip-address:local-port
When working with realtime data, websockets are the way to go. For one-off requests or polling, the REST API may be useful.
Include your token in the query string for authenticated requests ?token=xyz.
// POST: /api/command?token=xyz
{ "cmd": "ping" }
WebSockets
Volare Realtime is accessible locally or, when allowed, from the public Internet via WebSockets.
- Public:
wss://realtime.volarehq.com - On-site:
ws://local-ip-address:local-port
Authentication
Upon connecting you must send an authentication token to stay connected.
{ "cmd": "authenticate", "token": "your-token-here", "name": "Optional client name" }
{ "cmd": "authenticate", "action": "success", "clientId": 1 }
{ "cmd": "authenticate", "action": "error", "details": "Account not found for token" }
Subscribe to Topics
Subscribe to topics you would like to follow. The response will include the topics you were successfully subscribed to.
Some topics, such as entries, will immediately send the current state upon subscribing. From there you can apply messages with add, update or remove to this list to stay in sync. You can always request list at any time to retrieve the full state of the topic.
To change your list of subscriptions, resend the subscribe command with a new list of topics.
{ "cmd": "subscribe", "topics": ["flag-state", "heartbeat", "invalid-topic"] }
{ "cmd": "subscribe", "topics": ["flag-state", "heartbeat"] }
Request IDs
Include the reqId numeric parameter to match of responses to your commands.
{ "reqId": 123, "cmd": "local-cmd:ping" }
{ "reqId": 123, "cmd":"pong", "ts": 1728692137368000 }
Errors
Error messages will be returned in response to any failing command.
{ "cmd": "error", "type": "local-disconnected", "details": "No local relays connected for volare-test-organization", "orig": { "your": "msg"} }
Creating Custom Topics
It is possible to register your own custom topics, see Custom Topics
Championship Topics
Subscribe to the championship topic
{ "cmd": "championship", "action": "list" }
{ "cmd": "championship", "action": "get", "id": 10 }
Custom Topics
Subscribe to the Custom topic for changes to the list.
- Register
- List (topic + actions)
- Deregister
- Publish
- Subscribe
Custom topics are prefixed with the pattern Custom.<Namespace>
Event/Session Topics
Announcement
Subscribe to the session.announcement topic
{ "cmd": "session.announcement", "action": "get", "id": 2 }
{ "cmd": "session.announcement", "action": "list", "from": 111, "to": 222, "limit": 10 }
Driver ID
Subscribe to the session.driver-id topic
Driver ID can be null if it is not set
{ "cmd": "session.driver-id", "action": "list" }
{ "cmd": "session.driver-id", "action": "set", "driverId": 1, "entryId": 2 }
{
"cmd": "session.driver-id",
"action": "create",
"data": {
"sessionId": 1,
"driverId": 1,
"entryId": 2,
"transponderId": 456456
},
"timestamp": 123123
}
Classes
Listing of all classes in a session
Subscribe to the session.classes topic
// Request
{ "cmd": "session.classes", "action": "list" }
// Response
{
"cmd": "session.classes",
"action": "list",
"items": [
{
"id": 10,
"name": "GT1",
"shortName": "GT1",
"foregroundColor": "#000000",
"backgroundColor": "#ffffff",
"darkForegroundColor": "#ffffff",
"darkBackgroundColor": "#000000"
}
]
}
Drivers
Listing of all drivers and driver ID pairings
Subscribe to the drivers topic
{ "cmd": "drivers", "action": "list" }
{
"cmd": "drivers",
"action": "update",
"items": [{
"id": 10,
"lastName": "Senna",
"custom": { "custom": "data" }
}]
}
{
"cmd": "drivers",
"action": "add",
"items": [{
"lastName": "Hamilton",
"custom": { "custom": "data" }
}]
}
{ "cmd": "drivers", "action": "remove", "items": [{ "id": 10 }] }
{ "cmd": "drivers", "action": "list|add|update|remove", "items": [{ "id": 10 }] }
Entry List
Subscribe to the entries topic
{ "cmd": "entries", "action": "list" }
{
"cmd": "entries",
"action": "update",
"items": [{
"id": 10,
"lastName": "Senna",
"custom": { "custom": "data" }
}]
}
{
"cmd": "entries",
"action": "add",
"items": [{
"lastName": "Hamilton",
"custom": { "custom": "data" }
}]
}
{ "cmd": "entries", "action": "remove", "items": [{ "id": 10 }] }
{ "cmd": "entries", "action": "list|add|update|remove", "items": [{ "id": 10 }] }
Heartbeat
Subscribe to the heartbeat topic
Lap
Subscribe to the session.lap topic
{ "cmd": "session.lap", "action": "list", "from": 111, "to": 222, "limit": 10 }
{ "cmd": "session.lap", "action": "get" }
{
"cmd": "session.lap",
"data": {
"sessionId": 1,
"number": "20",
"lapNumber": 2,
"lapTime": 123233,
"speed": 123.2,
"speedUnits": "kph",
"position": 1,
"classPosition": 1,
"driverId": 1,
"entryId": 2,
"timelineId": 1,
"inPit": true,
"invalid": true, // Invalidated are not eligibile for best times
"deleted": true // Deleted are duplicate crossings (spin on timing loop)
},
"timestamp": 123123
}
Sector
Subscribe to the session.sector topic
{
"cmd": "session.sector",
"action": "create",
"data": {
"sessionId": 1,
"invalid": true, // Only set if time is invalidated
"flag": "green",
"sessionId": 2,
"name": "S1",
"lapNumber": 2,
"number": "20",
"speed": 43.2,
"speedUnits": "kph",
"lapTime": 23123000, // In microseconds - 23.123 seconds
"position": 1,
"classPosition": 1,
"driverId": 1,
"entryId": 2
},
"timestamp": 123123123
}
Session Entries
Subscribe to the session.entry topic
{ "cmd": "session.entry", "action": "list" }
{ "cmd": "session.entry", "action": "set", "name": "New Competitor" }
{ "cmd": "session.entry", "action": "set", "id": 10, "name": "Updated Competitor" }
{ "cmd": "session.entry", "action": "delete", "id": 10 }
Session Status Information
Time of day, time/laps remaining and other session information
Subscribe to the session.status topic
{ "cmd": "session.status", "action": "list", "from": 111, "to": 222, "limit": 10 }
{ "cmd": "session.status", "action": "get" }
Session List
Subscribe to the session topic
{ "cmd": "session", "action": "list" }
{ "cmd": "session", "action": "get", "id": 10 }
{ "cmd": "session", "action": "set", "id": 10, "name": "GP", "type": "RACE" }
{ "cmd": "session", "action": "delete", "id": 10 }
Stints
Subscribe to the session.stint topic
{ "cmd": "session.stint", "action": "list", "from": 111, "to": 222, "limit": 10 }
{ "cmd": "session.stint", "action": "set", "id": 10, "driverId": 1, "entryId": 2 }
{
"cmd": "session.stint",
"action": "create",
"data": {
"openLapNumber": 1,
"closeLapNumber": 3,
"totalTime": 123123,
"sessionId": 1,
"entryId": 2,
"driverIdIn": 1,
"inAt": 123123123,
"driverIdOut": 1,
"outAt": 123123123,
"type": "pit" // or track
},
"timestamp": 123123123 // Time stint started
}
Flagging Topics
Full Course
Subscribe to the full-course-flag topic
{ "cmd": "full-course-flag", "action": "set", "flagId": 10 }
{ "cmd": "full-course-flag", "action": "get" }
{ "cmd": "full-course-flag", "action": "list", "from": 111, "to": 222, "limit": 10 }
Device Flag
Subscribe to the device-flag topic
{ "cmd": "device-flag", "action": "set", "sectorId": 2, "flagId": 10 }
{ "cmd": "device-flag", "action": "list" }
{ "cmd": "device-flag", "action": "list", "from": 111, "to": 222, "limit": 10 }
Sector
Subscribe to the sector-flag topic
{ "cmd": "sector-flag", "action": "set", "sectorId": 2, "flagId": 10 }
{ "cmd": "sector-flag", "action": "list" }
{ "cmd": "sector-flag", "action": "list", "from": 111, "to": 222, "limit": 10 }
System Topics
Alerts
Subscribe to the alert topic
{ "cmd": "alert", "action": "get", "id": 2 }
{ "cmd": "alert", "action": "list", "from": 111, "to": 222, "limit": 10 }
Key/Value Store
Subscribe to the store topic
The Key/Value Store allow you to persist static data such as shared configurations
Max size of payload is 32kb
{ "cmd": "store", "action": "list" }
{ "cmd": "store", "action": "get", "key": "my-config" }
{ "cmd": "store", "action": "set", "key": "my-config", "data": { "your": "payload" } }
{ "cmd": "store", "action": "delete", "key": "my-config" }
{
"cmd": "store",
"key": "my-config",
"data": { "your": "payload" },
"updatedAt": 123123123
}
Loops
Subscribe to the loop topic
{ "cmd": "loop", "action": "list" }
Ping
You can send a ping command to check cloud or local time of day. You may also include the userTs property with your local timestamp to judge latency.
{ "cmd": "ping", "userTs": 1728691937357000 }
{ "cmd": "local-cmd:ping", "userTs": 1728691937357000 }
{ "cmd":"pong", "ts": 1728692137368000, "usesrTs": 1728691937357000 }
Server
Subscribe to the Server.service topic
{
"cmd": "Server.service",
"action": "get",
"data": {
"id": "Server.service",
"name": "Server",
"state": "connected",
"message": "Service is connected",
"status": "green",
"services": [
"Http",
"Db",
"RaceAmericaFlagtronicsIntegration",
"Flagtronics",
"RaceAmerica",
"RMonitor",
"Multiloop",
"Entry",
"X2Link",
"VolareCloud",
"VolareRealtime",
"Server",
"Stints",
"Simulator",
"XmlOutput",
"X2"
]
},
"time": 123123123
}
Track
Subscribe to the track topic
{ "cmd": "track", "action": "list" }
{
"cmd": "track",
"action": "list",
"items": [{
{ "id": 10, "name": "Spa" }
}],
"id": 10,
"time": 123123123
}
{ "cmd": "track", "action": "select", "id": 10 }
{ "cmd": "track", "action": "select", "id": 10 }
{ "cmd": "track", "action": "get", "id": 10 }
{
"cmd": "track",
"action": "get",
"data": {
"id": 10,
"name": "NOLA Motorsports Park",
"tz": "America/Chicago",
"lengthMeters": 101.12,
"zones": [
{
"name": "Pit Lane",
"type": "pitlane",
"polygon": [
{ "lat": 1, "lon": 2 }
]
}
],
"lines": [
{
"name": "Finish Line",
"type": "lapcounter",
"line": [
{ "lat": 1, "lon": 2 },
{ "lat": 3, "lon": 4 }
]
},
{
"name": "Intermediate 1",
"type": "intermediate",
"line": [
{ "lat": 1, "lon": 2 },
{ "lat": 3, "lon": 4 }
]
},
{
"name": "Pit In",
"type": "pit-in",
"line": [
{ "lat": 1, "lon": 2 },
{ "lat": 3, "lon": 4 }
]
}
],
"sectors": [
{ "name": "S1", "inLine": "Finish line", "outLine": "Intermediate 1", "lengthMeter": 123 }
],
"paths": [
{
"name": "Track",
"type": "track",
"widthMeter": 10,
"isClosed": true,
"line": [
{ "lat": 1, "lon": 2 },
{ "lat": 3, "lon": 4 },
{ "lat": 5, "lon": 5 }
]
}
],
}
}
{
"cmd": "track",
"action": "list",
"items": [{
{ "id": 10, "name": "Spa" }
}],
"time": 123123123
}
{ "cmd": "track", "action": "select" }
{ "cmd": "track", "action": "set", "id": 10, "data": { "name": "Spa" } } }
{ "cmd": "track", "action": "delete", "id": 10 }
Welcome
Sent upon connecting to the server
{ "cmd": "welcome" }
{ "cmd": "welcome", "version": 1, "time": 123123, "clientId": 1 }
Telemetry Topics
CANBUS
Subscribe to the canbus topic
{ "cmd": "canbus", "action": "list" }
{ "cmd": "canbus", "action": "list", "from": 111, "to": 222, "limit": 10 }
{ "cmd": "canbus", "action": "send", "id": 218000, "canId": 100, "data": [1, 123], "rtr": true }
{
"cmd": "canbus",
"data": {
"id": 456456,
"canId": 100,
"data": [1, 123],
"time": 123123123,
"parsed": {
"connected": true,
"pedalPct": 48,
}
}
}
Positions
Subscribe to the position topic
{ "cmd": "position", "action": "list" }
{ "cmd": "position", "action": "list", "from": 111, "to": 222, "limit": 10 }
{ "cmd": "position", "action": "create", "id": 218000, "lat": 11.123, /* ...rest */ }
{
"cmd": "position",
"data": {
"lat": 11.123,
"lon": 142.123,
"time": 123123123,
"kph": 123,
"dop": 123,
"id": 456456,
"entryId": 2 // Optional if an entry is found
}
}
Line crossings
Subscribe to the crossing topic
{ "cmd": "crossing", "action": "list", "from": 111, "to": 222, "limit": 10 }
{
"cmd": "crossing",
"data": {
"lineId": 1,
"lineName": "SF",
"time": 123123123,
"id": 456456,
"driverId": 1
}
}
Transponders
Subscribe to the transponder topic
{ "cmd": "transponder", "action": "list" }
{
"cmd": "transponder",
"data": {
"id": 1,
"time": 123123123,
"batteryPct": 88
}
}
Triggers
Subscribe to the trigger topic
{ "cmd": "trigger", "action": "list", "from": 111, "to": 222, "limit": 10 }
{
"cmd": "trigger",
"inputId": 1,
"time": 123123123,
"loopId": 2
}
Weather Topics
Environment
Subscribe to the weather topic
{ "cmd": "weather", "action": "get" }
{ "cmd": "weather", "action": "list", "from": 111, "to": 222, "limit": 10 }
{
"cmd": "weather:list",
"items": [{
{ "id": 123, "windSpeedKph": 12.2, "windDirectionDeg": 90, "humidityPct": 80, "tempInC": 24.23, "time": 123123123 }
}]
}
Track Temp
Subscribe to the loop-trigger topic
{ "cmd": "loop-trigger", "action": "list" }
{ "cmd": "loop-trigger", "action": "list", "from": 123123123, "limit": 10 }
{
"cmd": "loop-trigger:list",
"items": [{
{
"loopId": 123,
"tempInC": 24.23,
"loopName": "Test Loop",
"strength": -85,
"timestamp": 123123123,
}
}]
}
3rd Party Topics
RMonitor
Subscribe to the rmonitor or scoreboard topic
Multiloop
Subscribe to the Multiloop.raw topic
MyLaps X2Link
Subscribe to the x2link topic
// Request
{ "cmd": "x2link", "action": "send", "message": { /* message here */ } }
// Response
{ "cmd": "x2link", "message": { /* response here */ } }
MyLaps Orbits
Available topics
Orbits.serviceOrbits.configOrbits.flag
// Must be one of: green, yellow, red, checkered
// Request
{ "cmd": "Orbits.flag", "action": "set", "data": { "flag": "green" } }
// Response
{ "cmd": "Orbits.flag", "action": "get", "data": { "flag": "green" }, "time": 123123 }
MyLaps X2
Available topics
X2.loopX2.serviceX2.configX2.rawX2.statusX2.loop-triggerX2.io-eventX2.driver-idX2.crossingX2.applianceX2.available-serversX2.available-decodersX2.available-loops
// Request
{ "cmd": "X2.available-loops", "action": "list" }
// Response
{ "cmd": "X2.available-loops", "action": "list", "items": [ { "id": 2001, "name": "SF", "description": "", "timestamp": 1735498666136000, "isNoiseHighError": false, "isOnline": true, "isSyncOk": true, "twoWayId": 5, "hasDeviceErrors": false, "hasDeviceWarnings": false, "isInPit": false, "latitude": 214.7483647, "longitude": 214.7483647, "squelch": -90, "gateTime": 250, "isReconnecting": false, "noise": -99.5, "twowayNoise": -97 }] }
Flagtronics
Available topics
Flagtronics.device-statusFlagtronics.device-versionFlagtronics.driver-idFlagtronics.positionFlagtronics.track-statusFlagtronics.global-flagFlagtronics.sector-flagsFlagtronics.sector-flagFlagtronics.sector-statusFlagtronics.pit-timeFlagtronics.device-flagFlagtronics.available-serversFlagtronics.crossingFlagtronics.org-settingsFlagtronics.freeze-field-gpscoming soonFlagtronics.non-car-device-locationscoming soon
Device statuses
// Request
{ "cmd": "Flagtronics.device-status", "action": "list" }
// Response
{
"cmd": "Flagtronics.device-status",
"action": "list",
"items": [
{
"id": "10000126",
"flag": "green",
"batteryVoltage": 0,
"externalVoltage": 0,
"rssi": 18,
"temp": 0,
"time": 1729312903797000
}
]
}
Updated device status
{
"cmd": "Flagtronics.device-status",
"action": "update",
"data": {
"id": "10000126",
"flag": "blank",
"batteryVoltage": 0,
"externalVoltage": 0,
"rssi": 22,
"temp": 0,
"time": 1729312963614000
}
}
Global flag
// Request
{
"cmd": "Flagtronics.global-flag",
"action": "get"
}
// Response
{
"cmd": "Flagtronics.global-flag",
"action": "get",
"data": {
"flag": 66 // Flagtronics Flag ID
},
"time": 1729312963614000
}
// Request
{
"cmd": "Flagtronics.global-flag",
"action": "set",
"data": {
"flag": 66 // Flagtronics Flag ID
}
}
// Response
{
"cmd": "Flagtronics.global-flag",
"action": "set",
"data": {
"flag": 66 // Flagtronics Flag ID
},
"time": 1729312963614000
}
Sector flags
// Request
{
"cmd": "Flagtronics.sector-flags",
"action": "clear",
}
// Request
{
"cmd": "Flagtronics.sector-flags",
"action": "update",
"items": [
{ "id": 1, "flag": 8 } // Flagtronics Sector ID and Flag ID
]
}
// Response
{
"cmd": "Flagtronics.sector-flags",
"action": "update",
"items": [
{ "id": 1, "flag": 8 } // Flagtronics Sector ID and Flag ID
],
"time": 1729312963614000
}
// Request
{
"cmd": "Flagtronics.sector-flag",
"action": "set",
"data": {
"id": 1, // Flagtronics Sector ID
"flag": 66 // Flagtronics Flag ID
}
}
// Response
{
"cmd": "Flagtronics.sector-flag",
"action": "set",
"data": {
"id": 1, // Flagtronics Sector ID
"flag": 66 // Flagtronics Flag ID
},
"time": 1729312963614000
}
// Request
{
"cmd": "Flagtronics.sector-flag",
"action": "clear",
"data": {
"id": 1
}
}
// Response
{
"cmd": "Flagtronics.sector-flag",
"action": "clear",
"data": {
"id": 1
},
"time": 1729312963614000
}
Set device flag
// Request
// 0 = Clear, 1 = Black, 2 = Mechanical, 3 = Pit
{
"cmd": "Flagtronics.device-flag",
"action": "set",
"data": {
"id": 20000123,
"flag": 3 // Pit
}
}
// Response
{
"cmd": "Flagtronics.device-flag",
"action": "set",
"data": {
"id": 20000123,
"flag": 3
},
"time": 1731002958492000
}
Position Update
{
"cmd":"Flagtronics.position",
"action":"update",
"data":{
"type":"gps",
"id":"20000590",
"lat":33.84288024902344,
"lon":-117.5870590209961,
"kph":null,
"zone":255,
"timestamp":17512862,
"lastSeen":215,
"messageCount":2785864,
"t":1729313512647000
}
}
Pit Time Update
{
"cmd":"Flagtronics.pit-time",
"action":"update",
"data":{
"type":"pitTime",
"id": "20002139",
"pitInAt": 1733529611333000,
"pitOutAt": 1733529696333000,
"duration": 85000000
}
}
Race America
Available topics:
RaceAmerica.global-flagRaceAmerica.sector-flagRaceAmerica.sector-flagsRaceAmerica.connectRaceAmerica.disconnectRaceAmerica.brightnessRaceAmerica.sector-flagRaceAmerica.global-flag- Get State coming soon
- Set BF coming soon
Set global flag
// Request
{
"cmd": "RaceAmerica.global-flag",
"action": "set",
"data": {
"flag": 215 // Race America Flag ID
}
}
// Response
{
"cmd": "RaceAmerica.global-flag",
"action": "set",
"data": {
"flag": 215 // Race America Flag ID
},
"time": 1729312963614000
}
Set sector flag
// Request
{
"cmd": "RaceAmerica.sector-flag",
"action": "set",
"data": {
"sector": 1, // Race Ameria Sector ID
"flag": 215 // Race America Flag ID
}
}
// Response
{
"cmd": "RaceAmerica.sector-flag",
"action": "set",
"data": {
"sector": 1, // Race Ameria Sector ID
"flag": 215 // Race America Flag ID
},
"time": 1729312963614000
}
Get panel brightness
// Request
{ "cmd": "RaceAmerica.brightness", "action": "get" }
// Response
{
"cmd": "RaceAmerica.brightness",
"action": "get",
"data": {
"brightness": 2 // 1 = Brightest, 8 = Dimmest
}
}
Set panel brightness
// Request
{
"cmd": "RaceAmerica.brightness",
"action": "set",
"data": {
"brightness": 1 // 1 = Brightest, 8 = Dimmest
}
}
// Response
{
"cmd": "RaceAmerica.brightness",
"action": "set",
"data": {
"brightness": 1
},
"time": 1729313512647000
}
Race America to Flagtronics Integration
Available topics:
RaceAmericaFlagtronicsIntegration.config
Get configuration
// Request
{ "cmd": "RaceAmericaFlagtronicsIntegration.config", "action": "get" }
// Response
{
"cmd": "RaceAmericaFlagtronicsIntegration.config",
"action": "get",
"data": {
"enabled": true,
"SECTOR_MAPPING": [
{
"raceAmerica": 1, // ID in Race America
"flagtronics": 1 // ID in Flagtronics
}
]
}
}
Set configuration
// Request
{
"cmd": "RaceAmericaFlagtronicsIntegration.config",
"action": "set",
"data": {
"SECTOR_MAPPING": [
{
"raceAmerica": 1, // ID in Race America
"flagtronics": 3 // ID in Flagtronics
}
]
}
}
// Response
{
"cmd": "RaceAmericaFlagtronicsIntegration.config",
"action": "set",
"data": {
"enabled": true,
"SECTOR_MAPPING": [
{
"raceAmerica": 1, // ID in Race America
"flagtronics": 3 // ID in Flagtronics
}
]
}
}