README
moonbit-canbus
Pure MoonBit CAN 2.0/CAN-FD frames, codecs, filters, and deterministic virtual bus
can
can-fd
automotive
simulation
protocol
Author
Version
0.2.4
License
Apache-2.0
Repository
Last updated
2 months ago
Downloads
47
#moonbit-canbus
Pure MoonBit building blocks for CAN 2.0 and CAN-FD protocol modeling,
deterministic simulation, signal packing, trace replay, and bus diagnostics.
The library is designed for protocol experiments, regression suites,
teaching material, and hardware-adapter development where reproducible
behavior matters more than a connection to a particular controller.
#What it provides
- Validated 11-bit standard and 29-bit extended identifiers.
- Classic CAN and CAN-FD data, remote, and error frame models.
- DLC mapping, canonical bit encoding, CRC, bit stuffing, strict decoding, wire-length inspection, and checked bit cursors.
- Composable receive rules and ordered filter sets.
- Bounded FIFO queues, priority arbitration, logical timestamps, node mailboxes, deterministic error injection, and bounded virtual-bus runs.
- JSON, CSV, and append-friendly NDJSON event logs.
- Typed signal definitions for little-/big-endian fields, signed values, scaling, offsets, physical ranges, batch message layouts, and registries.
- Trace selection, replay schedules/cursors, wire statistics, health assessment, thresholds, and per-node/identifier diagnostics.
#Scope and safety boundary
The core is hardware-independent and does not access SocketCAN, USB devices,
operating-system sockets, or real-time controller peripherals. It models
protocol and simulation semantics; it is not a certified automotive stack,
hardware driver, safety mechanism, or real-time guarantee. DBC parsing, UDS,
J1939, CANopen, and hardware adapters are intentionally separate future
integration areas.
#Quick start
Install MoonBit, clone the repository, and run the deterministic example:
moon run cmd/can-demoThe example creates a controller and logger node, sends a standard frame,
applies an exact-ID filter, advances one arbitration step, and prints a
versioned JSON event. A repeatable benchmark harness is available with:
moon run cmd/can-benchThe benchmark reports measured microseconds for frame round trips, signal
pack/unpack, JSON round trips, and virtual-bus steps. It is a local diagnostic,
not a portable performance promise; see the recorded run in
docs/benchmarks/2026-08-22.md.
#Using the packages
The module path is fuyun-2026/moonbit-canbus. Add the package you need to a
moon.pkg import block:
import {
"fuyun-2026/moonbit-canbus/src/frame"
"fuyun-2026/moonbit-canbus/src/sim"
}The package boundaries are deliberately small:
| Package | Responsibility |
|---|---|
| src/frame | identifiers, frame kinds, payload validation, metadata |
| src/codec | DLC, bits, CRC, stuffing, wire codec and wire statistics |
| src/filter | exact, masked, kind, prefix and ordered filter matching |
| src/sim | queues, arbitration, nodes, bus events, schedules and recording |
| src/log | JSON, CSV, NDJSON, event batches and log queries |
| src/signal | checked signal conversion, layouts and registries |
| src/replay | selectors, schedules, replay results and cursors |
| src/diagnostic | reports, windows, health and threshold analysis |
| src/trace | trace selection, summaries, windows and analytics |
#Verification
The repository uses the current stable MoonBit installer in GitHub Actions on
Ubuntu, macOS, and Windows. Run the same core checks locally:
moon version --all
moon update
moon fmt --check
moon check --deny-warn --fmt --target all
moon info --target all
moon test --deny-warn --target all
moon run cmd/can-demo
moon run cmd/can-benchmoon info is followed by a clean-tree check in CI so generated interfaces
cannot drift silently. Native benchmark execution is additionally exercised
in CI where the runner's MoonBit runtime supports the target.
The CI matrix verifies all targets on Ubuntu, macOS, and Windows; the Windows
job prepares an MSYS2 native toolchain before running the full test matrix.
#Compatibility
The project uses the modern moon.mod/moon.pkg layout and checks all targets
supported by the installed toolchain. The public API is regenerated with
moon info; intentional interface changes are reviewed with the source diff.
#Roadmap
- Improve adapter-facing frame transport interfaces without coupling the core to one operating system.
- Add an independently licensed DBC integration when the parser boundary and redistribution terms are clear.
- Build optional UDS, J1939, and CANopen layers on the stable frame and bus primitives.
#Contributing
Keep changes package-local, add a focused test for every behavior change, run
moon fmt, and include reproducible commands for examples or benchmarks.
Please keep hardware-specific code and third-party sources in clearly marked
integration packages with their own provenance and license information.
#Provenance and license
The implementation in this repository is written for this module in MoonBit;
no third-party implementation source is copied into the core. Ecosystem scope
checks and external workflow references are recorded in
docs/ecosystem.md and the release checklist.
Licensed under Apache-2.0.
Install
Download zipPure MoonBit CAN 2.0/CAN-FD frames, codecs, filters, and deterministic virtual bus
cancan-fdautomotivesimulationprotocol
Apache-2.0
Updated 2 months ago
47 downloads