Expand description
§sae-j1939-rs
A no_std-first SAE J1939 protocol stack in Rust — the CAN-based
protocol used across trucks, agricultural equipment, construction
machinery, and marine engines.
This core crate is transport-agnostic and allocation-free: it decodes and
encodes the 29-bit J1939 identifier, models parameter groups, and (as the
stack grows) drives the transport, network management, and diagnostic
layers. It is designed to run unchanged on a bare-metal ECU and on a host
(Linux/SocketCAN) via the companion sae-j1939-host crate.
CAN frames are represented through the embedded_can traits, so any
controller or socket that implements them can carry J1939 traffic.
§Example: decode a frame off the bus
use sae_j1939_rs::{pgn, Address, Id, Priority};
// A DM1 (active diagnostic trouble codes) broadcast from ECU 0x80.
let id = Id::new(0x18FECA80).unwrap();
assert_eq!(id.pgn(), pgn::DM1);
assert_eq!(id.priority(), Priority::DEFAULT);
assert_eq!(id.source_address(), Address::new(0x80));
assert!(id.is_broadcast());
// DM1 is a PDU2 parameter group, so it has no destination address —
// every ECU on the bus should process it.
assert_eq!(id.destination_address(), None);
assert!(id.is_addressed_to(Address::new(0x27)));§Example: address a request to one ECU
use sae_j1939_rs::{pgn, Address, Id, Priority};
// Request the Software Identification PGN from ECU 0x90.
let id = Id::from_parts(
Priority::DEFAULT,
pgn::REQUEST,
Address::new(0x90),
Address::new(0x80),
)
.unwrap();
assert_eq!(id.as_u32(), 0x18EA9080);§Example: reassemble a multi-packet message
Messages longer than eight bytes arrive as a sequence of transport-protocol
frames. Reassembler puts them back together, bounded by
a buffer size you choose so an MCU can never be overrun.
use sae_j1939_rs::tp::{Reassembler, Rx, TpCm, TpDt};
use sae_j1939_rs::{pgn, Address};
let mut rx = Reassembler::<256>::new();
let sender = Address::new(0x80);
rx.on_tp_cm(sender, &TpCm::bam(12, pgn::DM1).unwrap());
rx.on_tp_dt(sender, &TpDt::new(1, &[1, 2, 3, 4, 5, 6, 7]));
if let Rx::Message { pgn, data, .. } = rx.on_tp_dt(sender, &TpDt::new(2, &[8, 9, 10, 11, 12])) {
assert_eq!(pgn, pgn::DM1);
assert_eq!(data, &[1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12]);
}§Module map
| Module | J1939 part | What it covers |
|---|---|---|
id, pgn, frame | J1939-21 | The 29-bit identifier, parameter groups, single frames |
tp | J1939-21 | Transport protocol: BAM and RTS/CTS, up to 1785 bytes |
etp | J1939-21 | Extended transport protocol: up to 117 MB |
name | J1939-81 | The 64-bit ECU NAME |
address_claim | J1939-81 | Claiming, defending, and relocating an address |
diagnostics | J1939-73 | DM1/DM2 trouble codes and lamp status |
fault_log | J1939-73 | The fault state an ECU reports about itself |
schedule | — | Periodic transmission, and DM13 broadcast control |
memory_access | J1939-73 | DM14/DM15/DM16 memory read, write, and data transfer |
identification | J1939-71 | Software, ECU, and component identification |
spn | J1939-71 | Suspect Parameter Numbers: payload bytes to engineering units |
proprietary | J1939-21 | Manufacturer-specific Proprietary A and B groups |
iso11783 | ISO 11783 | Tractor/implement auxiliary and general purpose valves |
request | J1939-21 | The Request and Acknowledgement parameter groups |
node | — | A whole ECU: claiming, reassembly, and dispatch in one type |
can | — | Bridge to the embedded_can traits |
Note that can — not transport — holds the CAN frame bridge, because in
J1939 “transport protocol” means tp specifically.
§Status
Early development. The API will change. The identifier, PGN, transport
protocol, NAME, address-claiming, diagnostic, identification, and ISO 11783
valve layers are implemented and tested against known-good frames. A broader
PGN/SPN parameter database is next — see the roadmap in the workspace
README.md.
Re-exports§
pub use address_claim::AddressClaimer;pub use address_claim::ClaimState;pub use frame::Frame;pub use id::Id;pub use name::Name;pub use node::Node;pub use pgn::Pgn;pub use request::Acknowledgement;pub use request::Request;pub use types::Address;pub use types::Error;pub use types::Priority;pub use types::Result;
Modules§
- address_
claim - J1939-81 network management: claiming and defending an ECU address.
- can
- Bridging J1939 frames to the
embedded_cantraits. - diagnostics
- J1939-73 diagnostics: trouble codes, lamps, and readiness.
- etp
- The Extended Transport Protocol: messages beyond 1785 bytes.
- fault_
log - The fault state an ECU reports about itself (J1939-73).
- frame
- A single J1939 CAN frame: a decoded
Idand up to eight payload bytes. - id
- The 29-bit J1939 CAN identifier.
- identification
- J1939-71 identification: who and what an ECU says it is.
- iso11783
- ISO 11783 (ISOBUS): agricultural tractors and their implements.
- memory_
access - J1939-73 memory access: DM14, DM15, and DM16.
- name
- The J1939-81 NAME: the 64-bit identity of an ECU.
- node
- A whole ECU in one type: address claiming, reassembly, and dispatch.
- pgn
- Parameter Group Numbers (PGNs).
- proprietary
- Proprietary A and B: manufacturer-specific parameter groups.
- request
- J1939-21 Request and Acknowledgement.
- schedule
- Periodic transmission: the thing a J1939 ECU spends most of its life doing.
- spn
- Suspect Parameter Numbers: turning payload bytes into engineering units.
- tp
- The J1939-21 Transport Protocol: multi-packet messages up to 1785 bytes.
- types
- Core J1939 value types:
Address,Priority, and the crateError.