AD Embedded Lab

Practical autonomous-driving and embedded-systems tools for engineers moving from device firmware into autonomy software.

The first utility is a dependency-free CAN log summarizer. It reads simple text CAN logs, groups frames by identifier, and reports message count, first/last timestamp, average/min/max period, jitter, rough frequency, and optional missing-frame warnings. This is useful when inspecting vehicle or bench logs before deeper perception, localization, planning, or control work.

Current Tools

• can-batch-summary: compare summary statistics across multiple CAN log files.
• can-batch-check: fail a run when batch summary metrics exceed configured thresholds.
• can-html-report: render a shareable HTML report from one or more CAN log files.
• can-log-summary: summarize timestamped CAN frames from a plain text log.
• can-parser-benchmark: run a small synthetic parser benchmark for maintainer checks.
• can-signal-extract: decode byte-aligned CAN signals from a small JSON spec without requiring a DBC parser.
• can-signal-report: render decoded signal metrics as a shareable HTML report.
• can-spec-validate: validate a JSON signal spec before using it in extraction workflows.

Quick Start

node src/can-log-summary.mjs examples/can-sample.log

Example output:

ID     Count  First(s)  Last(s)  AvgPeriod(ms)  Min(ms)  Max(ms)  Jitter(ms)  Freq(Hz)
0x180  4      0.000     0.030    10.000         10.000   10.000   0.000       100.00
0x1A0  3      0.005     0.025    10.000         10.000   10.000   0.000       100.00
0x220  2      0.010     0.040    30.000         30.000   30.000   0.000       33.33

CSV output:

node src/can-log-summary.mjs --format csv examples/can-sample.log

Batch summary across two logs:

node src/can-batch-summary.mjs examples/can-sample.log examples/can-sample-jitter.log

Shareable HTML report:

node src/can-html-report.mjs --title "Bench run" --max-jitter-ms 8 examples/can-sample.log examples/can-sample-jitter.log > report.html

CI-style threshold check:

node src/can-batch-check.mjs --max-jitter-ms 8 --min-frequency-hz 30 examples/can-sample.log examples/can-sample-jitter.log

Missing-frame check for a 100 Hz CAN id:

node src/can-log-summary.mjs --expect 0x180=100 examples/can-sample.log

Signal extraction:

node src/can-signal-extract.mjs --spec examples/signals-sample.json examples/can-signals-sample.log

Example output:

timestamp_s,id,message,signal,value,raw,unit
0.000,0x180,vehicle_status,speed_kph,10,1000,km/h
0.000,0x180,vehicle_status,steering_deg,-10,-100,deg

Big-endian bit numbering example:

node src/can-signal-extract.mjs --spec examples/signals-big-endian-sample.json examples/can-big-endian-sample.log

Decoded signal HTML report:

node src/can-signal-report.mjs --spec examples/signals-sample.json --title "Signal run" examples/can-signals-sample.log > signal-report.html

Signal spec validation:

node src/can-spec-validate.mjs examples/signals-sample.json

Parser benchmark:

node src/can-parser-benchmark.mjs --frames 1000 --ids 8

Log Format

Each non-empty line should contain:

timestamp_seconds can_id data_bytes...

Example:

0.000 0x180 11 22 33 44
0.010 0x180 12 22 33 44

Lines starting with # are ignored.

Malformed examples and expected errors are documented in Troubleshooting CAN Logs. Synthetic missing-frame and jitter examples are documented in Bench Debugging Scenarios. Parser benchmark usage is documented in Parser Benchmark.

Autonomy learning notes:

• Apollo/CyberRT Message Flow for Embedded Engineers
• Apollo/CyberRT Topic Debugging for Embedded Engineers

The maintenance process is documented in Maintainer Workflow.

Roadmap

• Add more Apollo/CyberRT learning notes and reproducible demos.
• Add more sample logs from common bench-debugging scenarios.
• Add filtering and threshold annotations to HTML reports.

Maintainer Notes

This repository is intended to become a real open-source maintenance target:

• Keep examples runnable without paid tools.
• Keep utilities dependency-free where practical.
• Prefer small, reviewable pull requests.
• Track planned work through GitHub Issues.
• Run the Node.js test suite and example smoke tests before each release.
• Follow MAINTAINERS.md, SUPPORT.md, and SECURITY.md for review, support, and security handling.

License

MIT