dbc_parse/lib.rs
1//! DBC file parser — CAN message definitions, signal layout
2//! (bit-offset/length/endianness/scaling), value tables, extended
3//! multiplexing.
4//!
5//! `dbc-parse` is the estate's **L0 leaf** for Vector DBC databases: a
6//! total, zero-dependency parser for the `BO_`/`SG_`/`CM_`/`VAL_`/`BA_`/
7//! `NS_` grammar, plus correct bit coding for both signal byte orders.
8//!
9//! # The Motorola bit-numbering problem
10//!
11//! DBC bit numbering runs per byte, LSB-first; the two byte orders differ
12//! in what [`Signal::start_bit`] names and the direction of travel:
13//!
14//! * **Intel (`@1`)** — little-endian, linear: `start_bit` is the LSB, bits
15//! ascend straight through byte boundaries.
16//! * **Motorola (`@0`)** — big-endian, the classic "sawtooth":
17//! `start_bit` is the MSB; extraction descends within each byte and
18//! jumps from bit 0 of one byte to bit 7 of the next (`+15` in DBC
19//! numbering). A `39|16@0+` signal is a big-endian `u16` across bytes
20//! 4–5; a `0|12@0-` signal straddles three bytes.
21//!
22//! [`crate::bits`] documents and implements both; the property tests pin
23//! encode/decode round-trips against known-good examples.
24//!
25//! # Example
26//!
27//! ```
28//! use dbc_parse::{ByteOrder, Dbc, MultiplexingInfo};
29//!
30//! let dbc = Dbc::parse(r#"
31//! BO_ 496 ExampleMessage: 8 PCM1
32//! SG_ Temperature : 0|12@0- (0.01,250) [229.52|270.47] "degK" PCM1,FOO
33//! SG_ Enable : 7|1@0+ (1,0) [0|0] "-" Vector__XXX
34//! "#)?;
35//!
36//! let message = &dbc.messages[0];
37//! assert_eq!(message.name, "ExampleMessage");
38//! let temperature = &message.signals[0];
39//! assert_eq!(temperature.byte_order, ByteOrder::Motorola);
40//! assert!(temperature.is_signed);
41//!
42//! // The canonical motohawk pattern: 0x01A1 in bytes 0-1 decodes to 242.4 K.
43//! let values = message.unpack(&[0x01, 0xA1, 0x02, 0x1A, 0xF8, 0x80, 0x00, 0x00]);
44//! let (name, value) = (&values[0].0.name, values[0].1);
45//! assert_eq!(name, "Temperature");
46//! assert!((value - 242.4).abs() < 1e-9, "{value}");
47//! assert!(matches!(
48//! message.signals[1].multiplexing_info,
49//! MultiplexingInfo::None
50//! ));
51//! # Ok::<(), dbc_parse::DbcError>(())
52//! ```
53//!
54//! # Scope
55//!
56//! * Parsed and retained: `VERSION`, `BU_` nodes, `BO_`/`SG_` (incl. `M`,
57//! `m<N>`, `m<N>M`), `VAL_`, `VAL_TABLE_`, `BA_` values, `SG_MUL_VAL_`.
58//! * Parsed and skipped: `NS_`, `BS_`, `CM_` comments, `BA_DEF_` /
59//! `BA_DEF_DEF_` schemas, unknown vendor keywords.
60//! * `dbc-parse` carries its own minimal [`CanId`] — L0 crates have zero
61//! runtime estate dependencies, so `can-core` cannot be a dependency.
62//!
63//! # `no_std`
64//!
65//! `no_std` + `alloc`: builds for embedded targets
66//! (`thumbv7em-none-eabihf` is exercised in CI) with zero runtime
67//! dependencies of any kind.
68
69#![no_std]
70extern crate alloc;
71
72pub mod bits;
73mod error;
74mod model;
75mod parser;
76
77pub use error::DbcError;
78pub use model::{
79 Attribute, AttributeObject, AttributeValue, ByteOrder, CanId, Dbc, ExtendedMux, Message,
80 MultiplexingInfo, Node, Signal, ValueTable, EXTENDED_ID_MAX, STANDARD_ID_MAX,
81};
82pub use parser::parse;