can_tools/lib.rs
1//! # can_tools
2//!
3//! `can_tools` is a Rust library for parsing [DBC files](https://en.wikipedia.org/wiki/DBC_(file_format))
4//! used in automotive applications to describe CAN network messages and signals.
5//!
6//! ## Features
7//! - Parses complete `.dbc` files into structured Rust types
8//! - Reads **messages**, **signals**, **nodes**, **comments**, and **value tables**
9//! - Case-insensitive search utilities for messages, signals, and nodes
10//! - Simple API: one call to [`parse`](crate::file::dbc::parse) produces a ready-to-use [`Database`](crate::models::database::Database)
11//!
12//! ## Example
13//! ```no_run
14//! use can_tools::file::dbc::parse;
15//!
16//! fn main() -> Result<(), String> {
17//! // Parse the DBC file
18//! let db = parse("path/to/file.dbc")?;
19//!
20//! println!("DBC Version: {}", db.version);
21//! println!("Messages: {}", db.messages.len());
22//!
23//! // Find a message by name
24//! if let Some(msg) = db.get_message_by_name("Motor_01") {
25//! println!("Message ID: {}", msg.id_hex);
26//! println!("Signals: {}", msg.signals.len());
27//! }
28//!
29//! Ok(())
30//! }
31//! ```
32//!
33//! ## Data Model
34//!
35//! ```text
36//! ┌───────────────────────────────────────┐
37//! │ Database │
38//! │───────────────────────────────────────│
39//! │ version: String │
40//! │ bit_timing: String │
41//! │ nodes: Vec<Node> │
42//! │ messages: Vec<Message> │
43//! └───────────────────────┬───────────────┘
44//! │
45//! ▼
46//! ┌───────────────────────────────────────┐
47//! │ Message │
48//! │───────────────────────────────────────│
49//! │ id: u64 │
50//! │ id_hex: String │
51//! │ name: String │
52//! │ byte_length: usize │
53//! │ sender_nodes: Vec<Node> │
54//! │ signals: Vec<Signal> │
55//! └───────────────────────┬───────────────┘
56//! │
57//! ▼
58//! ┌───────────────────────────────────────┐
59//! │ Signal │
60//! │───────────────────────────────────────│
61//! │ name: String │
62//! │ bit_start: usize │
63//! │ bit_length: usize │
64//! │ endian: usize │
65//! │ sign: usize │
66//! │ factor: f64 │
67//! │ offset: f64 │
68//! │ min: f64 │
69//! │ max: f64 │
70//! │ unit_of_measurement: String │
71//! │ receiver_nodes: Vec<Node> │
72//! │ value_table: HashMap<i32, String> │
73//! └───────────────────────────────────────┘
74//!
75//! Node: represents a CAN ECU (sender or receiver)
76//! ```
77//!
78//! ## Main Types
79//!
80//! - [`Database`](crate::models::database::Database):
81//! Holds the parsed DBC file structure, including version, bit timing,
82//! all [`Node`](crate::models::node::Node)s, and [`Message`](crate::models::message::Message)s.
83//!
84//! - [`Message`](crate::models::message::Message):
85//! Represents a CAN message. Contains message ID, name, sender nodes, and its list of [`Signal`](crate::models::signal::Signal)s.
86//!
87//! - [`Signal`](crate::models::signal::Signal):
88//! Represents a data field within a CAN message, including bit position, length,
89//! scaling factor, unit, receiver nodes, and optional value descriptions.
90//!
91//! - [`Node`](crate::models::node::Node):
92//! Represents a CAN network node (ECU) that can send or receive messages.
93//!
94//! ## When to Use
95//! Use `can_tools` when you need to:
96//! - Read `.dbc` files in Rust
97//! - Inspect messages, signals, and value tables
98//! - Integrate CAN signal definitions into automotive tools or simulations
99//!
100//! ## Related Standards
101//! - **DBC** format is a de-facto standard for describing CAN messages/signals
102//! - Compatible with tools like Vector CANdb++, CANalyzer, or open-source alternatives
103//!
104//! ## License
105//! Licensed under the [MIT License](https://opensource.org/licenses/MIT).
106
107pub mod file;
108pub mod models;