aliro_lab.py
Aliro Lab: score a captured reader serial log.
Overview
Aliro Lab: score a captured reader serial log.
Usage: python3 tools/aliro_lab.py [--cir <taps.csv>] <capture.log> [report.html]
Parses the structured "[ALAB] t=<us> ev=..." trace lines the firmware emits when CONFIG_WOZ_ALIRO_LAB is enabled (see modules/woz_aliro/src/aliro_lab.h), groups them into walk-up transactions, and reports phase timings, the flow taken (fast vs standard), and pass/warn/fail invariant checks — to the terminal and as a self-contained HTML report (default: <capture.log>.html).
With --cir, the windowed-CIR taps (ev=uwb.cir, channel-impulse Stage 1) are also written to a CSV (t_us,n,i,re,im,mag2) for offline inside/outside labeling and analysis; the scoring/report output is unchanged.
Every check encodes an invariant of this repo's reader implementation (see internal notes in the check text), nothing else. Exit status: 0 = no failing check, 1 = at least one FAIL, 2 = usage/input error.
used by aliro_gait.py
API
Fsdu_label(ev)
Human name for an rtx/rrx event, e.g. "rtx M1".
Captures from firmware before the id-based latency stamping carry no
proto, and there the id alone is ambiguous; those render as "rrx id=1".
render_html, render_terminalCclass Event
A timestamped firmware trace event: monotonic microsecond offset from capture start, event name, attributes dictionary, and source line number in the firmware log. Constructed by the parser; used to build transactions and compute timing deltas.
parse_eventsFEvent.__init__(self, t_us, name, attrs, line_no)
Initialize an Event with its timestamp in microseconds, symbolic name, attribute dictionary (typically containing proto/id/len/payload keys), and line number in the source trace.
Cclass Transaction
One walk-up: the events between a session.start and its session.end.
split_transactionsFTransaction.__init__(self, index)
Initialize a Transaction with a unique walk-up index, an empty event list, and the open flag set (no session.end seen yet).
FTransaction.finish(self)
Sort events by timestamp, extract phase markers (ph.* names, first occurrence only, tracking duplicates), infer flow type (fast or standard) from flow.* markers, and collect trusted range samples (cm values from range events). Skip reason "incomplete" set until flow type is determined.
split_transactions · calls Transaction.hasFTransaction.has(self, name)
Return true if the transaction contains at least one event with the given symbolic name; false otherwise. Used to check for required or optional milestones in the walk-up sequence.
Transaction.finish, run_checksFTransaction.first(self, name)
Return the first event in this transaction matching the given symbolic name, or None if no such event exists. Used to locate anchor events like session.start or connect for timestamp calculations.
Transaction.t0FTransaction.named(self, name)
Return a list of all events in this transaction with the given symbolic name.
render_approach_svg, run_checksFTransaction.t0(self)
Walk-up zero: the connect stamp, else the session.start line.
Transaction.offset_ms, render_approach_svg, render_html, render_terminal, run_checks · calls Transaction.firstFTransaction.offset_ms(self, key)
Compute the millisecond offset from the walk-up zero (connect or session start) to a given phase key. Divide microsecond delta by 1000.
run_checks · calls Transaction.t0FTransaction.last_phase(self)
Return the key of the last phase (in PHASES order) that was observed in this transaction, or None if no phases are present.
run_checksFparse_events(text)
Parse firmware log text line-by-line, extracting Aliro Lab events via regex (timestamp, event name, attribute key=value pairs). Return a list of Event objects sorted by line number.
main · calls EventFcir_rows(events)
Windowed-CIR taps as (t_us, n, i, re, im, mag2), in capture order. One row per ev=uwb.cir line with the full i/re/im set; magnitude-squared is precomputed for convenience. Works on the raw event stream, so taps are kept even outside a walk-up session (idle-ranging captures).
write_cir_csvFwrite_cir_csv(events, path)
Write the CIR taps to a CSV; return the row count.
main · calls cir_rowsFsplit_transactions(events)
Group by session boundaries in LINE order (the ph.* dump lines carry historical timestamps, so t order can't delimit walk-ups).
main · calls Transaction, Transaction.finishFrun_checks(txn)
Invariant checks; each returns (id, class, status, detail) with class the worst it can score (fail/warn) and status pass/warn/fail/n-a.
main · calls Transaction.has, Transaction.last_phase, Transaction.named, Transaction.offset_ms, Transaction.t0, addFadd(cid, cls, ok, detail, applicable=True)
Append a check result (id, class, status, detail) to results. Status is "n/a" if not applicable, "pass" if ok is true, otherwise the class string (warn or fail).
run_checksFworst_status(all_checks)
Return the worst (most critical) status among all checks across all transactions: "fail" if any check failed, else "warn" if any warned, else "pass".
main, render_html, render_terminalFfmt_ms(us_delta)
Format a microsecond delta as milliseconds (one decimal place).
render_html, render_terminalFrender_terminal(name, txns, checks_by_txn, use_color)
Render transaction summary, phase timeline, approach ranges, and check results as colored terminal output (ANSI colors if stdout is a TTY).
main · calls Transaction.t0, fmt_ms, paint, sdu_label, worst_statusFpaint(status, text)
Wrap text in ANSI color code if use_color is true, otherwise return unchanged. Codes: "32" for green, "33" for yellow, "31" for red.
render_terminalFrender_approach_svg(txn)
Distance-over-time chart of the approach: one dot per trusted range, dashed markers at grant/bolt/relock. Inline SVG, themed via the CSS vars.
render_html · calls Transaction.named, Transaction.t0, sx, syFsx(x)
Compute the screen x-coordinate (pixels) for a data value x in the range [xmin, xmax], scaling to the plot width minus left/right padding.
render_approach_svgFsy(y)
Map a y-coordinate to SVG pixel space, scaling from data range [ymin, ymax] into the chart's vertical span minus padding.
render_approach_svgFrender_html(name, txns, checks_by_txn)
Render a transaction log and check results as a self-contained HTML document with styling, phase timeline, ranging approach chart, and tabular check details.
main · calls Transaction.t0, fmt_ms, render_approach_svg, sdu_label, worst_statusFmain(argv)
Parse command-line arguments, read firmware trace log, extract walk-up transactions and run checks, optionally export CIR tap data to CSV, emit terminal and HTML reports, return exit code based on check results.
parse_events, render_html, render_terminal, run_checks, split_transactions, worst_status, write_cir_csv