TFR V6
Binary Format
Specification

Python struct format

'<3sBBHBHIffBBHBBBBHHI26s'   # 64 bytes exactly

Session Type Codes

Example: Slot 0 — Max Verstappen, Red Bull Racing

Hex:  01 56 45 52 08 36 71 C6
      |  |  |  |  |  |  |  +-- B = 198
      |  |  |  |  |  |  +----- G = 113
      |  |  |  |  |  +-------- R = 54       (#3671C6 = Red Bull blue)
      |  |  |  |  +----------- team_id = 8
      |  +--+--+-------------- "VER"
      +----------------------- driver_number = 1

Example 2025 Team Palette

Secondary Colour Derivation

secondary_channel = primary_channel + (255 - primary_channel) * 0.4

Clamped to 255. Produces a lighter tint for accent/gradient animations on the LED strip.

Header Size Summary

Fixed Preamble     64 bytes   (offsets   0 -  63)
Driver Table      160 bytes   (offsets  64 - 223)   20 slots x 8 bytes
Team Colour Table  70 bytes   (offsets 224 - 293)   10 slots x 7 bytes
Reserved           18 bytes   (offsets 294 - 311)
                  ---------
TOTAL HEADER      312 bytes

Race Status Codes

LED Encoding Logic

if trackLeds[i] > 0 and pitLeds[i] == 255:
    # Driver is ON TRACK at LED position trackLeds[i]  (1-239)

elif trackLeds[i] == 0 and pitLeds[i] < 255:
    # Driver is IN PIT LANE at pit LED index pitLeds[i]  (0-39)

elif trackLeds[i] == 0 and pitLeds[i] == 255:
    # Driver is OFF-TRACK / no data — not displayed anywhere

239-LED Track Strip (Animated)

Each lit LED represents a driver position. Colors correspond to team colours. LEDs are 1-indexed (1–239).

Tyre Compound Codes

Frame Size Breakdown

Core Block:
  timestamp          4 bytes   (float32)
  lap                2 bytes   (uint16)
  race_status        1 byte    (uint8)
  trackLeds[20]     20 bytes   (uint8 x 20)
  positions[20]     20 bytes   (uint8 x 20)
  pitLeds[20]       20 bytes   (uint8 x 20)
                    --------
  Core subtotal     67 bytes

Extended Block:
  speed[20]         40 bytes   (uint16 x 20)
  drs[20]           20 bytes   (uint8 x 20)
  compound[20]      20 bytes   (uint8 x 20)
  tyreLife[20]      20 bytes   (uint8 x 20)
  gapToLeader[20]   80 bytes   (float32 x 20)
  interval[20]      80 bytes   (float32 x 20)
  bestLap[20]       80 bytes   (float32 x 20)
  lastLap[20]       80 bytes   (float32 x 20)
  lastS1[20]        80 bytes   (float32 x 20)
  lastS2[20]        80 bytes   (float32 x 20)
  lastS3[20]        80 bytes   (float32 x 20)
  currentLapTime    80 bytes   (float32 x 20)
  currentSectorTime 80 bytes   (float32 x 20)
  currentSector[20] 20 bytes   (uint8 x 20)
                    --------
  Extended subtotal 840 bytes

TOTAL FRAME SIZE:  907 bytes

Verification (Python)

import struct, zlib

def verify_tfr_crc(filepath):
    with open(filepath, 'rb') as f:
        f.seek(34)
        stored_crc = struct.unpack('<I', f.read(4))[0]
        if stored_crc == 0:
            return None  # CRC was not computed

        f.seek(30)
        header_size = struct.unpack('<H', f.read(2))[0]
        f.seek(32)
        frame_size = struct.unpack('<H', f.read(2))[0]

        f.seek(header_size)
        computed_crc = 0
        while True:
            chunk = f.read(frame_size)
            if not chunk:
                break
            computed_crc = zlib.crc32(chunk, computed_crc)
        computed_crc &= 0xFFFFFFFF

    return computed_crc == stored_crc

Firmware Usage Example

bool openRaceFile(const char* path) {
    File file = sd.open(path, O_READ);
    if (!file) return false;

    TFRHeader header;
    if (file.read(&header, sizeof(header)) != sizeof(header)) {
        file.close();
        return false;
    }

    // Validate magic bytes
    if (header.preamble.magic[0] != 'T' ||
        header.preamble.magic[1] != 'F' ||
        header.preamble.magic[2] != 'R') {
        file.close();
        return false;
    }

    // Validate version
    if (header.preamble.version != TFR_VERSION_6) {
        file.close();
        return false;
    }

    // Playback parameters
    uint32_t numFrames  = header.preamble.totalFrames;
    uint8_t  sampleRate = header.preamble.sampleRateHz;
    uint32_t interval_us = 1000000 / (sampleRate * speedMultiplier);

    // Load driver colours for LED rendering
    for (int i = 0; i < header.preamble.numDrivers; i++) {
        driverColors[i] = CRGB(
            header.drivers[i].colourR,
            header.drivers[i].colourG,
            header.drivers[i].colourB
        );
    }

    // Read and render frames
    TFRFrame frame;
    while (file.read(&frame, sizeof(frame)) == sizeof(frame)) {
        for (int i = 0; i < header.preamble.numDrivers; i++) {
            if (frame.trackLeds[i] > 0) {
                leds[frame.trackLeds[i] - 1] = driverColors[i];
            }
        }
        FastLED.show();
        delayMicroseconds(interval_us);
    }

    file.close();
    return true;
}

Detecting V5 vs V6

def detect_binary_version(filepath):
    with open(filepath, 'rb') as f:
        first_bytes = f.read(4)

    if first_bytes[:3] == b'TFR':
        version = first_bytes[3]
        with open(filepath, 'rb') as f:
            f.seek(30)
            header_size = struct.unpack('<H', f.read(2))[0]
            frame_size = struct.unpack('<H', f.read(2))[0]
        return (version, header_size, frame_size)
    elif first_bytes[0] == 5:
        return (5, 38, 907)    # V5: 38-byte header, same frame size
    else:
        raise ValueError(f"Unknown format: {first_bytes.hex()}")