analyze-wpilog

name	analyze-wpilog
description	Analyze WPILOG log files from FRC robots using the wpilog-parser library with TypeScript.
license	MIT

wpilog-parser

WPILOG is the standard format used by FRC loggers — the 2026-Spectrum robot logs via DogLog (frc.spectrumLib.telemetry.Telemetry extends DogLog), so robots publish topics like Swerve/State/Pose, Swerve/SystemState, Sim/RobotPose3d, Sim/Fuel. The wpilog-parser library makes it easy to read and analyze the log files using TS/JS.

Upstream repo: https://github.com/jonahsnider/wpilog-parser/. Logs saved as .wpilog (see simulation/ and robot/ output dirs).

Creating a project

1. Init a project using bun init or similar

2. Add wpilog-parser as a dependency

3. Create a .ts file for cataloging the records in the WPILOG file

   import { readFile } from 'node:fs/promises';
   import { readRecords, catalogEntries } from 'wpilog-parser';
   
   const bytes = await readFile('./example.wpilog');
   
   for (const catalogEntry of catalogEntries(readRecords(bytes))) {
     console.log(catalogEntry);
     // {
     //   entryId: 3,
     //   name: "/Robot/DogLog/Options",
     //   type: "string",
     //   metadata: "{\"source\":\"DogLog\"}",
     // }
   }
   

Analyzing logs

Use decodeRecords to parse record contents. Filter by name and narrow on type:

import { readFile } from 'node:fs/promises';
import { readRecords, decodeRecords, isDataRecord, RecordType } from 'wpilog-parser';

const bytes = await readFile('./example.wpilog');

for (const record of decodeRecords(readRecords(bytes))) {
  if (!isDataRecord(record)) continue;

  if (record.name === '/Robot/Intake/Voltage' && record.type === RecordType.Double) {
    console.log(record.timestamp, record.payload);
  }
}

Decoding structs

import { structPayloadToJson, RecordType } from 'wpilog-parser';

for (const record of decodeRecords(readRecords(bytes))) {
  if (record.type === RecordType.Struct && record.name === '/Robot/Localization/EstimatedPose') {
    console.log(record.timestamp, structPayloadToJson(record.payload));
    // 18688018n {
    //   translation: { x: 10.289, y: 0.47 },
    //   rotation: { value: 1.5707961072652017 },
    // }
  }
}

Strict mode

for (const record of decodeRecords(readRecords(bytes), { strict: true })) {
  // throws on orphan data records instead of skipping
}

Robot state cheatsheet

When DriverStation logging is on, every WPILOG has these boolean entries:

Entry	Meaning
/DS:enabled	true while the robot is enabled (any mode).
/DS:autonomous	true during autonomous. false means teleop (unless /DS:test).
/DS:test	true during test mode.
/DS:estop	true if e-stopped.

The mode flags (autonomous, test) reflect what the DS would run if enabled, so check /DS:enabled together with them. Timestamps are microseconds (bigint).

Tracking enable/mode durations

import { readRecords, decodeRecords, isDataRecord, RecordType } from 'wpilog-parser';

type Mode = 'auto' | 'teleop' | 'test';
function modeOf(auto: boolean, test: boolean): Mode {
  if (test) return 'test';
  if (auto) return 'auto';
  return 'teleop';
}

let enabled = false;
let auto = false;
let test = false;
let enabledSince: bigint | null = null;
let lastTimestamp: bigint = 0n;
const totals = { auto: 0n, teleop: 0n, test: 0n };

for (const r of decodeRecords(readRecords(bytes))) {
  lastTimestamp = r.timestamp;

  if (!isDataRecord(r) || r. !== .) ;

   wasEnabled = enabled;
   prevMode = (auto, test);

   (r. === ) enabled = r.;
    (r. === ) auto = r.;
    (r. === ) test = r.;
   ;

   (wasEnabled && (!enabled || (auto, test) !== prevMode)) {
    totals[prevMode] += r. - (enabledSince ?? r.);
    enabledSince = enabled ? r. : ;
  }   (!wasEnabled && enabled) {
    enabledSince = r.;
  }
}


 (enabled && enabledSince !== ) {
  totals[(auto, test)] += lastTimestamp - enabledSince;
}


.(totals);