Project Charter¶

This charter is the canonical statement of intent for schoolbus.

Identity¶

schoolbus is a pedagogical inspection library for machine communication protocols. It exists to make the communication systems behind vehicles, aircraft, industrial machines, marine systems, spacecraft, sensors, ECUs, embedded controllers, avionics computers, field devices, and safety-critical systems legible to capable software and systems engineers.

The project treats machine protocols as observable systems, executable artifacts, engineering tradeoffs, timing systems, authority structures, and operational interfaces.

The project is intentionally:

• pedagogical
• inspection-oriented
• source-grounded
• simulation-friendly
• explanation-heavy
• explicit about uncertainty and simplification

The project is intentionally not:

• a production-certified stack
• a standards-conformance suite
• a vendor SDK replacement
• a vehicle exploitation toolkit
• a reverse-engineering piracy archive
• a complete implementation of every protocol

Design Philosophy¶

Concrete first. Abstractions emerge from repeated implementation pressure.

Prefer explicit data models, readable field extraction, inspectable bit operations, deterministic examples, transparent simplifications, and educational clarity.

Avoid ceremonial architecture, speculative abstraction, universal protocol inheritance trees, enterprise-framework aesthetics, excessive plugin systems, and early over-generalization.

The ideal interaction pattern is:

thing = Thing.from_raw(...)
thing.show_fields()
thing.explain()

Not:

GlobalFactoryRegistryProvider(...)

Pedagogical Ladder¶

The project is organized around this conceptual ladder:

All major protocol work should map onto this ladder where possible. Not every protocol uses every layer.

Examples:

Protocol Taxonomy¶

Documentation and code should distinguish these categories clearly:

Do not present electrical signaling, framing, semantic dictionaries, capture formats, and full application protocols as if they were the same kind of object.

Source Policy¶

Public documentation must stand on public source metadata, official public material, tooling references, and clearly marked synthetic artifacts. Private research notes are not shipped and cannot serve as reader-verifiable authority.

The repository may include metadata, canonical URLs, public summaries, public tutorials, open-source implementation references, generated examples, and synthetic traces.

The repository must not include pirated standards PDFs, scraped proprietary content, or vendor IP copied into source code, tests, docs, notebooks, or samples.

Pedagogical simplifications must be named in comments, docs, or explanations when they could otherwise be mistaken for full conformance.

Explainability Contract¶

Every major protocol object should implement:

explain() -> str

Every major protocol object should also expose important decoded values through:

show_fields()

Good explanations teach, contextualize, identify assumptions, avoid unexplained acronyms, and make uncertainty visible.

Bad:

PGN 61444, SPN 190.

Good:

This J1939 identifier carries EEC1 (Electronic Engine Controller 1), which commonly
includes engine speed information.

Safety Policy¶

schoolbus is educational. It should avoid unsafe operational attack tooling, real exploit walkthroughs, bypass tooling, unauthorized ECU manipulation guidance, and examples that transmit against real vehicles, aircraft, vessels, industrial systems, or embedded targets.

Security discussion should focus on trust assumptions, observability, stale or impossible state, replay concepts, protocol-era threat models, and synthetic lab examples.

Documentation And Testing Expectations¶

Documentation is a first-class deliverable. It should optimize for readability, rigor, explicit assumptions, educational sequencing, and executable examples.

Tests should verify field extraction, bit ordering, parity, checksums, arbitration behavior, transaction decoding, explainability output stability, documentation examples, atlas loading, and sample-trace decoding where those surfaces exist.

Extensibility Rules¶

Protocol packages should expose transport units, field extraction, encoding or decoding where appropriate, explainability, toy simulation, offline sample fixtures, and passive observer examples.

Protocols should remain mostly independent. Avoid forcing incompatible protocols into identical interfaces. Do not introduce UniversalProtocol, AbstractTransportLayerFactory, GenericBusManager, or giant plugin registries until repeated implementation pressure justifies them.

Shared contracts should be structural capabilities, not mandatory base classes. The protocol catalog may advertise capabilities such as explainability, field inspection, arbitration, framing, transactions, signals, and observations. Tutorial factories should create deterministic synthetic examples for learning, not auto-detect or decode arbitrary operational traffic.