Skip to main content

Crate sae_j1939_rs

Crate sae_j1939_rs 

Source
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

ModuleJ1939 partWhat it covers
id, pgn, frameJ1939-21The 29-bit identifier, parameter groups, single frames
tpJ1939-21Transport protocol: BAM and RTS/CTS, up to 1785 bytes
etpJ1939-21Extended transport protocol: up to 117 MB
nameJ1939-81The 64-bit ECU NAME
address_claimJ1939-81Claiming, defending, and relocating an address
diagnosticsJ1939-73DM1/DM2 trouble codes and lamp status
fault_logJ1939-73The fault state an ECU reports about itself
schedule—Periodic transmission, and DM13 broadcast control
memory_accessJ1939-73DM14/DM15/DM16 memory read, write, and data transfer
identificationJ1939-71Software, ECU, and component identification
spnJ1939-71Suspect Parameter Numbers: payload bytes to engineering units
proprietaryJ1939-21Manufacturer-specific Proprietary A and B groups
iso11783ISO 11783Tractor/implement auxiliary and general purpose valves
requestJ1939-21The 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_can traits.
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 Id and 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 crate Error.