> ## Documentation Index
> Fetch the complete documentation index at: https://playbook.smedleygroup.com/llms.txt
> Use this file to discover all available pages before exploring further.

# The STL Database and SimTelLab

> Where converted runs are filed, the folder structure SimTelLab expects, and how engineers get the database onto their own machine.

Both telemetry streams end in the same place. Converted DAQ runs and exported charging runs are filed into an **STL database** in the telemetry bucket, which engineers sync down and open in SimTelLab to review battery health and kart performance while out on track.

## The Structure

The STL database is a folder structure under the `STL-database/` prefix of the telemetry bucket. The layout is not an implementation detail: SimTelLab reads it directly, so it is effectively a contract.

| Data | Path |
| - | - |
| DAQ runs | `STL-database/{year}/{Race or Test}/{R or T}_{hub region}_{MM}_{DD}/RACING/OFFLOADED/EK{kart}/` |
| Charging runs | `STL-database/{year}/{Race or Test}/{R or T}_{hub region}_{MM}_{DD}/CHARGING/RT/{kart}/` |

Runs whose binary header reports hardware version 0.3 are filed under `RACING_v03` rather than `RACING`.

Each run is a pair of MATLAB files: `{runName}_Tel.mat` holding the channel data, and `{runName}_Info.mat` holding the run metadata.

> [!WARNING]
>
> For DAQ runs, the `Race` or `Test` segment comes from the `isRaceDay` answer that GKL API gives during conversion. If that answer is wrong, the run converts perfectly well and is then filed under the wrong event type, where nobody is looking for it. For charging runs the event type comes from the dashboard instead, and defaults to `Test`.

## Getting It Onto An Engineer's Machine

**1. Sync the database down**

The STL database is synced from S3 to the engineer's own machine with `aws s3 sync`. A helper script in the telemetry API repository does this a year at a time, in both directions.

**2. Open it in SimTelLab**

SimTelLab is an externally provided Windows application. It reads the `.mat` files straight from the synced folder structure.

> [!NOTE]
>
> The sync script has the year hard coded, so it needs editing at the turn of a year.

## Related Documentation

| Page | Relevance |
| - | - |
| [DAQ Upload and Conversion](/software/developer/estate/systems/telemetry/daq-pipeline) | How racing runs are converted and filed |
| [Charging Export](/software/developer/estate/systems/telemetry/charging-export) | How charging runs are exported and filed |
| [Timing and Lap Splitting](/software/developer/estate/systems/telemetry/timing-and-lap-splitting) | Why a run may be filed with no laps |

## Key Files

| File | Role |
| - | - |
| `telemetry/telemetry-api/src/services/io/stl_saving/s3_stl_saver_service.py` | Writes converted DAQ runs into the STL database |
| `telemetry/telemetry-api/src/offloaded/pipeline/telemetry_data_exporter.py` | Builds the DAQ folder path and file names |
| `telemetry/telemetry-api/src/services/telemetry_exporter_service.py` | Builds the charging folder path and writes those files |
| `telemetry/telemetry-api/scripts/upload_stl_db.bat` | Syncs the database between S3 and a local machine |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.