Skip to main content

sae_j1939_rs/
lib.rs

1// Copyright (c) 2026 Karpagam Karthikeyan
2// SPDX-License-Identifier: MIT OR Apache-2.0
3
4//! # sae-j1939-rs
5//!
6//! A `no_std`-first [SAE J1939] protocol stack in Rust — the CAN-based
7//! protocol used across trucks, agricultural equipment, construction
8//! machinery, and marine engines.
9//!
10//! This core crate is transport-agnostic and allocation-free: it decodes and
11//! encodes the 29-bit J1939 identifier, models parameter groups, and (as the
12//! stack grows) drives the transport, network management, and diagnostic
13//! layers. It is designed to run unchanged on a bare-metal ECU and on a host
14//! (Linux/SocketCAN) via the companion `sae-j1939-host` crate.
15//!
16//! CAN frames are represented through the [`embedded_can`] traits, so any
17//! controller or socket that implements them can carry J1939 traffic.
18//!
19//! # Example: decode a frame off the bus
20//!
21//! ```
22//! use sae_j1939_rs::{pgn, Address, Id, Priority};
23//!
24//! // A DM1 (active diagnostic trouble codes) broadcast from ECU 0x80.
25//! let id = Id::new(0x18FECA80).unwrap();
26//!
27//! assert_eq!(id.pgn(), pgn::DM1);
28//! assert_eq!(id.priority(), Priority::DEFAULT);
29//! assert_eq!(id.source_address(), Address::new(0x80));
30//! assert!(id.is_broadcast());
31//!
32//! // DM1 is a PDU2 parameter group, so it has no destination address —
33//! // every ECU on the bus should process it.
34//! assert_eq!(id.destination_address(), None);
35//! assert!(id.is_addressed_to(Address::new(0x27)));
36//! ```
37//!
38//! # Example: address a request to one ECU
39//!
40//! ```
41//! use sae_j1939_rs::{pgn, Address, Id, Priority};
42//!
43//! // Request the Software Identification PGN from ECU 0x90.
44//! let id = Id::from_parts(
45//!     Priority::DEFAULT,
46//!     pgn::REQUEST,
47//!     Address::new(0x90),
48//!     Address::new(0x80),
49//! )
50//! .unwrap();
51//!
52//! assert_eq!(id.as_u32(), 0x18EA9080);
53//! ```
54//!
55//! # Example: reassemble a multi-packet message
56//!
57//! Messages longer than eight bytes arrive as a sequence of transport-protocol
58//! frames. [`Reassembler`](tp::Reassembler) puts them back together, bounded by
59//! a buffer size you choose so an MCU can never be overrun.
60//!
61//! ```
62//! use sae_j1939_rs::tp::{Reassembler, Rx, TpCm, TpDt};
63//! use sae_j1939_rs::{pgn, Address};
64//!
65//! let mut rx = Reassembler::<256>::new();
66//! let sender = Address::new(0x80);
67//!
68//! rx.on_tp_cm(sender, &TpCm::bam(12, pgn::DM1).unwrap());
69//! rx.on_tp_dt(sender, &TpDt::new(1, &[1, 2, 3, 4, 5, 6, 7]));
70//!
71//! if let Rx::Message { pgn, data, .. } = rx.on_tp_dt(sender, &TpDt::new(2, &[8, 9, 10, 11, 12])) {
72//!     assert_eq!(pgn, pgn::DM1);
73//!     assert_eq!(data, &[1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12]);
74//! }
75//! ```
76//!
77//! ## Module map
78//!
79//! | Module | J1939 part | What it covers |
80//! |--------|-----------|----------------|
81//! | [`id`], [`pgn`], [`frame`] | J1939-21 | The 29-bit identifier, parameter groups, single frames |
82//! | [`tp`] | J1939-21 | Transport protocol: BAM and RTS/CTS, up to 1785 bytes |
83//! | [`etp`] | J1939-21 | Extended transport protocol: up to 117 MB |
84//! | [`name`] | J1939-81 | The 64-bit ECU NAME |
85//! | [`address_claim`] | J1939-81 | Claiming, defending, and relocating an address |
86//! | [`diagnostics`] | J1939-73 | DM1/DM2 trouble codes and lamp status |
87//! | [`fault_log`] | J1939-73 | The fault state an ECU reports about itself |
88//! | [`schedule`] | — | Periodic transmission, and DM13 broadcast control |
89//! | [`memory_access`] | J1939-73 | DM14/DM15/DM16 memory read, write, and data transfer |
90//! | [`identification`] | J1939-71 | Software, ECU, and component identification |
91//! | [`spn`] | J1939-71 | Suspect Parameter Numbers: payload bytes to engineering units |
92//! | [`proprietary`] | J1939-21 | Manufacturer-specific Proprietary A and B groups |
93//! | [`iso11783`] | ISO 11783 | Tractor/implement auxiliary and general purpose valves |
94//! | [`request`] | J1939-21 | The Request and Acknowledgement parameter groups |
95//! | [`node`] | — | A whole ECU: claiming, reassembly, and dispatch in one type |
96//! | [`can`] | — | Bridge to the [`embedded_can`] traits |
97//!
98//! Note that [`can`] — not `transport` — holds the CAN frame bridge, because in
99//! J1939 "transport protocol" means [`tp`] specifically.
100//!
101//! ## Status
102//!
103//! Early development. The API will change. The identifier, PGN, transport
104//! protocol, NAME, address-claiming, diagnostic, identification, and ISO 11783
105//! valve layers are implemented and tested against known-good frames. A broader
106//! PGN/SPN parameter database is next — see the roadmap in the workspace
107//! `README.md`.
108//!
109//! [SAE J1939]: https://www.sae.org/standards/development/ground-vehicle-standards/j1939
110#![no_std]
111#![deny(unsafe_code)]
112#![warn(missing_debug_implementations)]
113#![warn(missing_docs)]
114
115// `std` is available to the test harness regardless of the feature, so tests
116// may use `Vec` and friends while the library itself stays `no_std`.
117#[cfg(any(feature = "std", test))]
118extern crate std;
119
120pub mod address_claim;
121pub mod can;
122pub mod diagnostics;
123pub mod etp;
124pub mod fault_log;
125pub mod frame;
126pub mod id;
127pub mod identification;
128pub mod iso11783;
129pub mod memory_access;
130pub mod name;
131pub mod node;
132pub mod pgn;
133pub mod proprietary;
134pub mod request;
135pub mod schedule;
136pub mod spn;
137pub mod tp;
138pub mod types;
139
140pub use address_claim::{AddressClaimer, ClaimState};
141pub use frame::Frame;
142pub use id::Id;
143pub use name::Name;
144pub use node::Node;
145pub use pgn::Pgn;
146pub use request::{Acknowledgement, Request};
147pub use types::{Address, Error, Priority, Result};