Revlog v2

CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+## 2.0.0
+
+- Reads REVLOG format version 2: microsecond timestamps, multiple CAN buses named in entry paths (`REV/CAN_S0/Spark-3/...`), CAN FD frame lengths, A301 firmware versions, Driver Station state (`DS:controlWord/enabled`, `DS:controlWord/robotMode`), match information (`DS:matchInfo/...`), logger events (`REV/StatusLogger/Event`) and dropped frames (`REV/StatusLogger/<bus>/DroppedFrames`)
+- Rejects files with a newer major format version, with a message to update the converter
+- Adds `--stats` (and `analyzeREVLOG` / `formatStats`) to summarize a REVLOG and flag known problems
+- Fixes firmware versions being written on every firmware table; each `FIRMWARE` entry is now written when it changes. Logs from REVLib 2027 alphas convert to far smaller WPILOGs (277 MB to about 6 MB in one case)
+- Fixes Servo Hub firmware versions (for example `25.1.2` instead of `2.1.6400`)
+- Frames from non-REV manufacturers are no longer decoded with the SPARK DBC
+- Decodes A301 status frames (`REV/<bus>/A301-<number>/...`) and firmware versions
+- Version 1 status signals convert exactly as in 1.0.5
+- Major version: new entry names for version 2 files, so AdvantageScope must update its dependency (`^1.0.5`) to pick this up
+
+## 1.0.5
+
+- Lower memory use, progress bar, faster conversion

README.md

@@ -2,7 +2,27 @@
 
 A lightweight, robust Node.js utility for converting REV Robotics binary log files (`.revlog`) into the WPILOG format (`.wpilog`).
 
-This tool allows you to take raw CAN bus logs from valid REV devices (Spark Max, Spark Flex, Servo Hub) and view them in standard FRC analysis tools like AdvantageScope.
+This tool allows you to take raw CAN bus logs from REV devices (SPARK MAX, SPARK Flex, Servo Hub, detached encoders and the A301) and view them in standard FRC analysis tools like AdvantageScope.
+
+It reads both REVLOG formats written by REVLib's `StatusLogger`:
+
+* **Version 1**, written by REVLib 2025 through 2027.0.0-alpha-8
+* **Version 2**, written by later releases
+
+Files using a newer major version are rejected with a message to update the converter.
+
+## Output
+
+| REVLOG data | WPILOG entries |
+| --- | --- |
+| Status frame signals | Version 2: `REV/<bus>/<device>-<number>/<signal>`, for example `REV/CAN_S0/Spark-3/APPLIED_OUTPUT`. Version 1: `REV/<device>-<number>/<signal>`. Faults and warnings go in `FAULT/` and `WARNING/` subfolders |
+| Firmware versions | `.../FIRMWARE` (string), written when the version changes |
+| Driver Station state (version 2) | `DS:controlWord/enabled` (boolean) and `DS:controlWord/robotMode` (string). AdvantageScope uses these to line the log up with other logs and to shade enabled periods |
+| Match information (version 2) | `DS:matchInfo/eventName`, `DS:matchInfo/matchType`, `DS:matchInfo/matchNumber` |
+| Logger events (version 2) | `REV/StatusLogger/Event` (`started`, `capturing`, `stopped`, `resumed`, `usb-removed`, `directory-changed`) |
+| Dropped frames (version 2) | `REV/StatusLogger/<bus>/DroppedFrames` (running total) |
+
+Devices are `Spark`, `ServoHub`, `Encoder` and `A301`.
 
 ## Usage
 
@@ -31,8 +51,11 @@ The tool supports Unix-style piping. You can pipe a binary file into the convert
 #### Options
 
   * `-o, --output <file>`: Specify the output filename. If omitted (and not piping to a file), the binary data is written to `stdout`.
+  * `--stats`: Print a summary of the REVLOG instead of converting it: format version, record counts and sizes, time span, frames per device, logger events, and known problems (for example timestamps from REVLib 2027 alphas, or a file that is mostly repeated firmware tables).
   * `-h, --help`: Display the help message.
 
+`revlog-converter --stats input.revlog`
+
 -----
 
 ### Library Usage (Node.js & TypeScript)
@@ -59,3 +82,19 @@ async function convertFile() {
     console.error('Conversion failed:', err);
   }
 }
+```
+
+#### 2\. Summarizing a REVLOG
+
+```typescript
+import { readFileSync } from 'fs';
+import { analyzeREVLOG, formatStats } from '@rev-robotics/revlog-converter';
+
+const stats = analyzeREVLOG(readFileSync('./match.revlog'));
+console.log(formatStats(stats)); // or inspect stats.warnings, stats.devices, ...
+```
+
+## Development
+
+* `npm test` runs the tests. `test/fixtures/v1-baseline.json` holds the output of converter 1.0.5 for a version 1 file; signal output for version 1 files must keep matching it.
+* `npm run lint:check` and `npm run format:check` run the same checks as publishing.

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rev-robotics/revlog-converter",
-  "version": "1.0.5",
+  "version": "2.0.0",
   "author": "REV Robotics",
   "license": "BSD-3-Clause",
   "description": "Tool to parse and convert .revlog files produced by REVLib's StatusLogger to .wpilog files",
@@ -33,7 +33,8 @@
     "lint:check": "eslint 'src/**/*.ts'",
     "format": "prettier --write 'src/**/*.ts'",
     "format:check": "prettier --check 'src/**/*.ts'",
-    "dev": "tsx src/cli.ts"
+    "dev": "tsx src/cli.ts",
+    "test": "node --import tsx --test test/*.test.ts"
   },
   "devDependencies": {
     "@types/node": "^20.19.37",

src/cli.ts

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 
 import { parseREVLOG } from './lib/revlogParser.js';
+import { analyzeREVLOG, formatStats } from './lib/revlogStats.js';
 import { Readable, Writable, Transform } from 'stream';
 import fs from 'fs';
 
@@ -23,11 +24,31 @@ Arguments:
 Options:
   -o, --output     The path to the output .wpilog file.
                    If not provided, the output will be piped directly to stdout.
+  --stats          Print a summary of the REVLOG (records, devices, time
+                   span, logger events) and any known problems, instead
+                   of converting it.
   -h, --help       Show this help message.
     `);
     return;
   }
 
+  if (args.includes('--stats')) {
+    const files = args.filter((arg) => !arg.startsWith('-'));
+    let input: Buffer;
+    if (files.length === 1) {
+      input = fs.readFileSync(files[0]);
+    } else if (files.length === 0 && !process.stdin.isTTY) {
+      const chunks: Buffer[] = [];
+      for await (const chunk of process.stdin) chunks.push(chunk as Buffer);
+      input = Buffer.concat(chunks);
+    } else {
+      console.error('Error: --stats needs exactly one input file or stdin.');
+      process.exit(1);
+    }
+    process.stdout.write(formatStats(analyzeREVLOG(input)));
+    return;
+  }
+
   let rawStream: Readable;
   let totalBytes: number | null = null;
   let outputTarget: string | Writable | undefined = undefined;

src/index.ts

@@ -1,2 +1,4 @@
 // Re-export the parseREVLOG function to make it a top-level export.
 export { parseREVLOG } from './lib/revlogParser.js';
+export { analyzeREVLOG, formatStats } from './lib/revlogStats.js';
+export type { RevlogStats } from './lib/revlogStats.js';