Runs, vehicles and incidents
A run is one flight or bench run of one vehicle, built from the files that recorded it. Vehicles hold what those files say about each platform, and an incident is a window of a run under investigation.
Foxborne organizes evidence into three kinds of object. Runs hold the files, vehicles hold what the files say about each platform and incidents hold the investigation.
Runs#
A run is one flight or bench run of one vehicle, built from the files that recorded it. It can hold four kinds of source:
| Source | Recorded by | Format |
|---|---|---|
| Flight log | The flight controller | PX4 ULog |
| Companion journal | systemd on the companion computer | journalctl JSON export |
| Process samples | The Foxborne collector on the companion computer | Collector JSONL |
| Ground receive log | The MAVLink receiver at range control | Receiver JSONL |
Files reach a run by two paths. Import files builds one run from the files you add together, and connected sources match new files to runs by vehicle and time. The vehicle comes from the MAVLink system ID in each flight log, or from the vehicle part of a file pattern.
Each run records how its files arrived, such as Manual upload or Assembled from 3 sources. Parsing then follows one fixed job:
- 01ValidateType, size and schema. A .ulg must carry the ULog magic bytes.
- 02HashSHA-256 of every original, stored unmodified.
- 03ParseFlight log topics, journal entries, samples and receipts become events with stable IDs.
- 04AlignEach source gets its clock, its anchor and an error bound.
- 05Run rulesDeterministic rules produce findings that cite the events they read.
The job is deterministic: the same files and parser versions give the same event IDs. On a run's page, Import job opens each step with its time. For R-0931 in the example dataset:
| Step | Time |
|---|---|
| Validate type, size and schema | 0.4 s |
| Hash originals (SHA-256) | 1.2 s |
| Parse flight log, 11 of 13 topics | 38.1 s |
| Parse journal and samples | 2.6 s |
| Align clocks | 0.3 s |
| Run 13 rules | 0.9 s |
Run statuses#
| Status | What it means |
|---|---|
| Parsing | The import job is running. The run's page shows the current step and its progress. |
| Complete | Every file parsed and the rules ran. The Clock chip reports alignment separately. |
| Partial | A source is missing, such as "No companion journal for this run". Findings that depend on it are not produced, and reports list the gap under Limitations. |
| Quarantined | A file is damaged, such as a flight log truncated inside a data message. Nothing from it is shown as complete. |
| Rejected | A file cannot be used, such as an encrypted flight log. Foxborne does not decrypt logs. |
The runs list groups Quarantined and Rejected under Needs attention, and both offer Replace the file. See Import statuses and fixes.
The clock chip#
Runs and incidents share one Clock chip, which sums up how the sources line up:
| Chip | What it means |
|---|---|
| Aligned ±46 ms | Every source is anchored to UTC. The value is the widest combined bound between two sources. |
| Manual ±1.09 s | A companion clock was aligned by hand, and the value includes the manual bound. |
| Not aligned | The companion clock has no anchor, so its evidence stays on its own axis. |
| Elapsed time only | The flight log has no GPS fix, so times run from log start. |
| Pending | The run has not finished parsing. |
The values are from the example dataset. Clocks, anchors and error bounds explains where each bound comes from.
Vehicles#
A vehicle in Foxborne is what its files say about it, and nothing more. The Vehicles page says so: "Nothing here is live: it is read from the files you import."
Under Where each source is recorded, the page shows a line drawing of the platform and tags each part with the source that records it. For the two platforms in the example dataset:
| Part | Tag on the drawing |
|---|---|
| Flight controller | Flight log |
| Companion computer | Journal, Process samples |
| GNSS receiver | Via the flight log |
| Battery | Via the flight log |
| Depth camera, Q4 recon quad | Via the flight log |
| Lidar, T4 tracked UGV | Via the journal |
| Mesh radio | Keeps no log |
| Range control | Receive log |
The radio is the gap that matters. It keeps no log Foxborne can read, so during an incident its box can read State not observed. Nothing on the vehicle recorded what it did.
Vehicle parts and their logs lists every part, how it is wired and which log carries its data.
Foxborne also reads failsafe parameters from each flight log's header and compares them run to run. It reads COM_DL_LOSS_T, NAV_DLL_ACT, COM_FAIL_ACT_T, COM_OF_LOSS_T, COM_OBL_RC_ACT, SYS_HAS_NUM_GNSS, COM_GNSSLOSS_ACT and, for the quad, COM_POS_FS_EPH.
Failsafe parameters shows the values from a named run, and Changes between runs, opened from its header, lists what moved. On UGV-05 in the example dataset it reads NAV_DLL_ACT 0 (Disabled) to 1 (Hold) in R-0924. See Vehicles and parameter drift and PX4 parameters Foxborne reads.
Incidents#
An incident is one failure under investigation. An investigator opens it on a window of a run where findings appear. The incident keeps that run, that window and everything written about it.
INC-0142 in the example dataset was opened on the window 14:31:53 to 14:32:16 of run R-0931, after the rules produced six findings there. Each incident names an owner and a reviewer, and its work sits in four tabs:
| Tab | What it holds |
|---|---|
| Reconstruction | The timeline of every source, the map, the vehicle drawing and the events in view. |
| Sources | The run's files, with their clocks, bounds, hashes and the ordering bounds between them. |
| Report | The finding, sequence, evidence, limitations, open questions and next check. |
| Activity | What happened on the incident, from assembly and rule results to status changes and exports. |
Admins and investigators open and edit incidents. Reviewers read everything an investigator can, comment and approve reports.
Incident status and report state#
An incident's status tracks the investigation, and its report's state tracks the review. The two move separately: changing an incident's status does not change its report.
- Incident status: Open, In review or Closed, set from the status button in the incident's header. The incidents list opens on Active, which shows every incident that is not closed.
- Report state: Draft, In review or Approved. The incident's reviewer approves the report. See Reports and case files.
Each status change is recorded in the incident's Activity tab and in the audit log.
Related#
- Check a run reads a run's sources, clocks and import job.
- Import statuses and fixes fixes truncated, encrypted and missing files.
- Work an incident goes from an incident's timeline to its report.
- Statuses and states lists every status in one place.