schoolbus¶
schoolbus teaches machine communication by passive inspection. Start with one synthetic artifact, decode only what is visible, add timing evidence, name the semantic authority, and keep uncertainty visible.
This is a working binder, not a standards mirror, vendor SDK, or operational guide. Examples are offline and synthetic so the reader can reason about evidence without receiving instructions for a live system.
It is the runnable companion to the six-part Reading Machine Buses series. The library and final-copy binder exemplars are usable now; other pages remain clearly marked as draft, field-note, or docs-only material. See support and maturity for the boundary.
Start With One Artifact¶
From a clean checkout, install the locked environment and explain the same synthetic CAN artifact used by the first workbook:
You need Git and
uv. The project requires
Python 3.11 or newer; uv selects or installs a compatible interpreter while it
synchronizes the locked environment.
git clone https://github.com/JLospinoso/schoolbus-reader.git
cd schoolbus-reader
uv sync --all-groups --frozen
uv run schoolbus explain can --id 0x123 --data 01020304
Expected output:
This is a Classical CAN data frame with a standard 11-bit identifier 0x123. Its DLC is 4, so it carries 01 02 03 04. Its arbitration priority depends on the captured identifier, frame format, and data-versus-remote arbitration bits.
That output establishes only frame facts. Payload meaning, sender identity, freshness, and physical truth still require evidence the frame does not contain.
Run the first workbook next. It reads the checked-in synthetic artifact rather than repeating the values in code:
uv run python docs/labs/first_workbook.py
Follow The Six-Part Path¶
Each series step has a concrete repository companion:
| Series step | Read next |
|---|---|
| The artifact is not the system | First workbook |
| Classical CAN | Classical CAN |
| DBC and semantic authority | DBC |
| UART and timing evidence | UART |
| Modbus RTU and reconstruction | Modbus RTU |
| MIL-STD-1553 and bus authority | MIL-STD-1553 |
Use the foundations as interludes when the artifact raises a question:
- Inspection ladder: how evidence becomes a cautious hypothesis.
- Semantic authority: why bytes need an external source before they become meaning.
- Timing and cadence: why freshness, gaps, and repetition change interpretation.
- Observer reconstruction: how missingness, stale evidence, and conflict stay explicit.
Explore Later¶
- Protocol Binder: protocol families, field notes, and draft Core Labs.
- Labs: a runnable first workbook and additional synthetic sample packs.
- Project Internals: governance, source policy, documentation standards, and reviewer material.
- Contributor policy: source, safety, and review expectations for project changes.
- Publication and release posture: maturity gates and actions reserved for the owner.