Using the library
TRaceBoxClient events, the TRaceBoxSample record, sessions and CSV columns.
Connecting and downloading
uses RaceBox.Protocol, RaceBox.Session, RaceBox.BLE;
FClient := TRaceBoxClient.Create;
FClient.OnDeviceFound := DeviceFound; // (Index, Name, Address, Rssi)
FClient.OnConnected := Connected;
FClient.OnLiveSample := LiveSample; // TRaceBoxSample, 25 Hz
FClient.OnDownloadComplete := DownloadDone;
FClient.StartScan;
...
FClient.Connect(Index); // returns at once, connects in the background
FClient.Unlock(123456); // only if memory security is on
FClient.StartDownload;
...
procedure TForm1.DownloadDone(Sender: TObject; Cancelled: Boolean);
var Sessions: TRaceBoxSessionList;
begin
Sessions := FClient.ExtractSessions; // you own the list now
RaceBoxSaveSessionsCsv('C:\RaceBox', Sessions);
end;
Events run on the main thread, so you can update the user interface from them. OnStateChanged fires
whenever State changes (scanning, connecting, connected and so on). ConnectTimeoutMs (default 30000)
sets how long a connection attempt may take.
TRaceBoxSample
| Field | Unit |
|---|---|
UtcTime, UnixTimeMs, TimeValid |
UTC TDateTime, milliseconds since 1970 |
Latitude, Longitude |
degrees |
AltitudeMSL, AltitudeWGS |
metres |
Speed / SpeedKmh |
m/s / km/h |
Heading |
degrees, 0 = north |
GForceX / Y / Z |
g (X front/back, Y right/left, Z up/down) |
GyroX / Y / Z |
degrees/s (roll, pitch, yaw) |
FixStatus, NumSV, PDOP, HorizAccuracy … |
fix quality |
HasGoodFix |
3D fix with the valid-fix flag set; ignore positions when False |
Sessions
The device stores everything in one memory and writes a state-change record when recording starts, stops
or pauses, so a new session begins at each recording start. As a fallback, a gap of more than
MaxGapSeconds (default 300 s) between samples also starts a new session; set it to 0 to turn that off.
CSV columns
utc_time, unix_ms, itow_ms, latitude, longitude, alt_msl_m, alt_wgs_m, speed_kmh, speed_ms, heading_deg, fix, fix_ok, sats, pdop, h_acc_m, v_acc_m, speed_acc_ms, heading_acc_deg, g_x, g_y, g_z, gyro_x_dps, gyro_y_dps, gyro_z_dps, battery_raw, fix_flags, latlon_flags
The decimal point is always . and times are UTC. unix_ms is the easiest column for lining the data up
with other logs.
Protocol
The library implements the RaceBox BLE protocol documentation, revision 9.