machbus

machbus is a Rust library for building agricultural CAN and ISOBUS-style applications. It includes protocol codecs, protocol state machines, helper surfaces, examples, and C/Python bindings.

It is tested locally by a large suite of unit, fixture, integration, binding, trace, and fuzz-smoke checks. In plain words: machbus is not certified. It ships with no ISO, SAE, NMEA, or AEF certification. Certification and deployment approval still require the official standards, real hardware, and interoperability evidence.

Fast path

If you are new to the project, read in this order:

First, read conformity boundary material so every API example is interpreted inside the correct evidence and certification limits. Then learn ISOBUS basics, build your first node, and pick tutorial material for the role you are building.

1. Claim boundary
2. The standards, end to end — the story of how ISOBUS works, or ISOBUS in plain words for a quicker primer.
3. Build and verify
4. The session facade — the recommended API for new code.
5. Pick the tutorial for the role you are building.

The application surface

machbus gives you one application surface over the protocol codecs: the session facade (machbus::session). You compose a node from plugins, drive a pure sans-IO core, and use a driver/handle split. It is the recommended hosted API and the same feed/tick/drain shape is the embedded API. In hosted/default builds you also get the high-level plugin stack, C/Python bindings, virtual-bus adapters, and richer geo helpers. In embedded builds you disable defaults and use the no_std + alloc surface with board-owned time, CAN I/O, and storage. Every guided walkthrough and tutorial page teaches the hosted shape first; MCU users should also read no_std on microcontrollers.

What machbus gives you

• J1939 and ISOBUS-oriented CAN identifiers, address claiming, requests, and transport helpers.
• Higher-level services for Virtual Terminal, Task Controller, File Server, diagnostics, Sequence Control, tractor/implement facilities, GNSS, and NMEA.
• A session surface that lets multiple roles talk over a virtual bus or real SocketCAN endpoints.
• Rust APIs first, with C ABI and Python bindings for integration.

What you still own

• Choosing device identities and safe addresses for your machine.
• Testing with your actual CAN hardware and wiring.
• Validating behavior with real Virtual Terminals, Task Controllers, service tools, and other ECUs.
• Official conformance/certification work.

Where the old audit docs went

The previous audit-oriented documentation was moved to book/src/reference/audit/. Use it as a migration reference when maintaining the book, but write new user-facing content in this book/ mdBook.

Conformity and evidence

This book starts with conformity because agricultural networks are safety- and interoperability-sensitive. It is not enough for code to compile. Users need to know what was tested, what evidence exists, and where the boundary is.

In this book:

• Conformity means the implementation follows known protocol behavior and has local evidence.
• Certification means official or third-party validation. machbus does not claim that.

The rest of the book is practical. You will see tutorials and examples, but those tutorials should always be read with this boundary in mind.

Evidence categories

machbus uses several kinds of evidence:

Start with Claim boundary before using the protocol tutorials.

Claim boundary

machbus is a protocol implementation and development library. It is not an officially certified ISOBUS product. Put another way: machbus is not an officially certified ISOBUS product.

Safe wording

It is fine to say:

• machbus implements codecs and session behavior for many ISOBUS/J1939/NMEA workflows.
• machbus has local tests, fixtures, examples, and binding smoke tests.
• machbus is designed for agricultural CAN applications.

Do not say:

• machbus is ISO certified.
• machbus is AEF certified.
• machbus is guaranteed to work with every VT, TC, implement, or tractor.
• local unit tests are the same as formal conformance.

What local tests prove

Local tests prove that the checked code paths behave as expected for the fixtures, generated inputs, examples, and session scenarios in this repository.

They can catch:

• byte layout regressions
• malformed payload handling mistakes
• panics in public decode paths
• state-machine transition mistakes
• C/Python binding drift
• examples that no longer build

What local tests cannot prove

Local tests cannot prove:

• that all official standard requirements have been reviewed
• that every vendor device accepts the behavior
• that timing on real CAN hardware is always suitable
• that a machine is safe to deploy
• that AEF conformance has been achieved

Why standards text is not copied here

ISO 11783, SAE J1939, and NMEA 2000 are not fully public in the way normal open source documentation is public. This book teaches concepts and documents this library, but it does not reproduce normative standard text.

For product certification, use the official standards and the applicable AEF or vendor validation process.

Evidence model

machbus uses layered evidence. Each layer catches different failures.

Why standards-text review earns its own row

Every layer above it takes the implementation’s own assumptions as the baseline. Unit tests prove the code does what its author meant; fixtures pin the bytes it already produces; session tests run both halves of a conversation against each other. None of that can catch a wire rule that was reconstructed rather than read, because both sides of the test share the reconstruction.

That is not hypothetical. The standards-text audit found nine defects, seven of which only misbehave against a conformant peer — over-strict receive paths and uniform defaults where the standard varies. Testing a stack against itself could not have surfaced any of them.

The layer’s blind spot is the mirror image: it sees only what the documents write down. Much of ISO 11783 deliberately does not — PGN assignments, DDIs and NAMEs all live in the electronic database at isobus.net rather than in the standards, so no PGN constant in this crate is checkable this way.

Repository evidence map

• tests/protocol_fixtures.rs: protocol fixture checks.
• tests/standard/session_harness.rs: multi-node session integration behavior.
• examples/c_abi/: C ABI demos plus surface/layout checks (make c-demo / c-full-demo).
• examples/c_abi: C examples and layout probe.
• examples/python_binding: Python wheel/demo/regression smoke.
• tests/fuzz_targets.rs: bounded fuzz/property smoke.
• book/src/reference/audit/: previous audit evidence and rationale.
• book/src/reference/audit/standards-text-audit.md: what was checked against the ISO/AEF/NMEA text, what it found, and what it cannot show.

The new book should stay readable, but it should link back to evidence when a chapter makes a strong claim.

What is tested

The project currently verifies a broad local surface through make verify.

Major tested areas include:

• Address claim and NAME management.
• J1939 diagnostic messages and diagnostic request behavior.
• Transport Protocol and Extended Transport Protocol boundaries.
• NMEA 2000 Fast Packet and NMEA 0183 serial GNSS parsing.
• Virtual Terminal client/server handshake, object pool transfer, typed object bodies, updates, and server-side semantic state cache.
• Task Controller client/server workflows, DDOP parsing/helpers, process data, measurement triggers, and TC-GEO helpers.
• File Server client/server operations.
• Sequence Control master/client workflows.
• Tractor, implement, guidance, powertrain, and facility helpers.
• Rust session presets and plugins.
• C ABI and Python bindings.

For exact rows and evidence links, see Protocol matrix.

What is not certified

machbus does not include an official certificate for:

• ISO 11783
• SAE J1939
• NMEA 2000
• AEF ISOBUS conformance

The code can be useful before certification. It can help build prototypes, tools, tests, simulators, gateways, and product code. But shipping on real machines requires a separate validation process.

Treat these as open deployment responsibilities

• Run with the actual CAN interface and bitrate.
• Test against the actual VT, TC, service tool, and peer ECUs.
• Capture and review traces.
• Validate machine safety behavior.
• Use official standards and AEF processes where required.

The repository may contain external-oracle rows in its evidence matrix. Those rows mean “implemented locally but still needs external proof”, not “certified”.

Hardware and AEF path

The practical path from local tests to deployment usually looks like this:

1. Run make verify.
2. Run examples over a virtual CAN interface.
3. Capture and replay traffic with SocketCAN/candump.
4. Test with a small hardware bench.
5. Test with real VTs, TCs, service tools, tractors, and implements.
6. Compare traces against expected behavior.
7. Use official AEF or customer-required conformance processes.

Hardware evidence should record

• repository commit
• CAN interface
• bitrate
• device list
• test steps
• raw capture path
• expected result
• observed result
• pass/fail decision

Hardware tests should never be vague. If a trace is used as evidence, keep the trace and a short report with enough metadata that someone else can understand what was connected.

ISOBUS in plain words

ISOBUS is the agricultural-machine family of CAN-based communication built on SAE J1939 ideas and ISO 11783 application layers. A tractor, implement, Virtual Terminal, Task Controller, GNSS receiver, file server, service tool, and specialized controllers may all share the same physical network.

If you are new to it, do not start with the whole protocol surface. Start with the mental model:

1. every communicating role is a control function;
2. every control function has a stable NAME;
3. the NAME is used to claim a temporary source address;
4. normal traffic is grouped by PGN;
5. short payloads fit in one CAN frame;
6. long payloads use TP, ETP, or Fast Packet;
7. application services such as VT, TC, FS, SC, TIM, diagnostics, and GNSS build workflows on top of those lower layers.

machbus groups those layers into modules and stack helpers so application code can work with typed messages instead of raw bytes most of the time.

Mental model

Application role
  └─ machbus session/plugins
       └─ ISOBUS/J1939/NMEA services
            └─ transport protocols
                 └─ CAN frames

Two ways to look at the stack

From the bus upward:

From an application downward:

Where to go next

This page is the gentle on-ramp. For the full story — every part explained with diagrams and a path from concept to code — read The standards, end to end, which builds the picture from the wire up:

1. The networking foundation — CAN, J1939, NAME and address claim, and transport (the spine everything else stands on).
2. The Virtual Terminal — how an implement borrows the cab’s screen.
3. The Task Controller — documented work and the shared DDI vocabulary.
4. Application services — implement control, the tractor ECU, diagnostics, File Server, sequence control, and TIM.
5. Positioning: NMEA and GNSS — getting the fix onto the bus.

When you want to see this on a real bus, jump to Reading candump traces; for the source documents, see Further reading. When you are ready to build, start with The session facade.

What this section is not

This section is a practical orientation guide. It is not a copy of ISO 11783, and it does not replace official protocol documents or external certification work. The goal is to give you enough shape to understand the machbus API and to debug traces without drowning in every part of the standard on day one.

Reading candump traces

candump is the fastest way to see what actually crossed a SocketCAN interface. The text it prints is short, but every line packs a 29-bit identifier whose fields you have to take apart by hand before the bytes make sense. This page teaches you to read a line cold: which token is which, how to pull priority, PGN, source, and destination out of the hex identifier, and how to recognize the handful of traffic shapes you will see over and over. Every example line here is one we made up to illustrate the math — none is copied from a real capture.

Why this exists

When something on the bus misbehaves, the trace is the ground truth. A node that “isn’t responding” might be answering to the wrong destination; an upload that “hangs” might be stuck waiting for a clear-to-send. You cannot see any of that from the application side — you have to read the wire. Knowing how to decode a raw line turns a wall of hex into a conversation you can follow.

Anatomy of a candump line

A compact candump -L style line looks like this (illustrative):

(0.842301) can0 18EF2280#0102030405060708

Read it left to right:

The common bracketed format carries the same information differently:

(0.842301) can0  18EF2280  [8]  01 02 03 04 05 06 07 08

Here [8] is the DLC (data length code, the byte count), and the payload bytes are spaced out. Both shapes describe one frame; machbus’s candump_replay example parses either one.

A quick reflex: eight hex digits in the identifier means extended (29-bit), which is what ISOBUS and J1939 use. A two- or three-digit identifier is an 11-bit standard frame and is not ISOBUS/J1939 application traffic — the candump_replay example deliberately rejects those rather than guess at them.

Decoding the identifier by hand

The 29-bit identifier is not the PGN. It is a packed word, and the PGN is only part of it. The layout, most-significant bit first:

 bits 28..26 | 25  | 24 | 23..16 | 15..8 | 7..0
   priority  | EDP | DP |   PF   |  PS   |  SA

• priority (3 bits): lower number wins arbitration; it does not change meaning, only urgency.
• EDP / DP (2 bits): the data-page selectors. Together with PF and PS they form the 18-bit PGN.
• PF (PDU Format, 8 bits): the byte that decides PDU1 vs PDU2.
• PS (PDU Specific, 8 bits): either a destination address (PDU1) or a group extension that is part of the PGN (PDU2).
• SA (Source Address, 8 bits): who sent the frame.

The PF byte is the fork in the road:

• PF < 240 → PDU1 (destination-specific). PS is the destination address and is not part of the PGN. The PGN’s low byte is zero.
• PF ≥ 240 → PDU2 (broadcast). PS is part of the PGN (the group extension), and the frame has no single destination — it is for everyone.

Worked example: 18EF2280

Take the identifier 18EF2280 and write it as 32 bits, then drop the top three (only 29 are used):

hex   1    8    E    F    2    2    8    0
bits 0001 1000 1110 1111 0010 0010 1000 0000

Slice it along the field boundaries above:

PF is 0xEF = 239, which is below 240, so this is PDU1. That means:

• PGN = EDP·DP·PF·00 = 0x00EF00 (the PS byte is not in the PGN; the low byte is forced to zero).
• Destination = PS = 0x22.
• Source = SA = 0x80.
• Priority = 6.

So 18EF2280 is “node 0x80 sends a proprietary-A message to node 0x22 at priority 6.” If PF had been 0xF0 or higher, PS would have folded into the PGN and the frame would be a broadcast with no specific destination.

machbus does exactly this decode in net::Identifier: priority(), pgn(), source(), and destination() return the same fields, and is_pdu2() / is_broadcast() answer the PF≥240 question for you.

A few PGNs you can compute

You do not need a dictionary to read most traffic — compute the PGN from PF/PS and a short table covers the common cases. These values come from the machbus PGN helpers and are illustrative, not exhaustive:

Notice the pattern: PF below 0xF0 (EE, EA, E8, EC, EB) is PDU1, so the PS slot in the identifier is a destination, not part of the PGN. PF of 0xFE is PDU2, so PS (0xCA) is baked into the PGN and the frame goes to everyone.

Recognizing traffic on sight

After a little practice you can name most lines without decoding every bit.

Address claim. PF 0xEE, eight payload bytes — that payload is a 64-bit NAME. Seeing several EE00 frames right after power-up is normal: nodes are sorting out who owns which address. See NAME and address claim.

(0.010) can0 18EEFF80#00112233445566AA   ; node 0x80 claims, broadcast

A request. PF 0xEA, three payload bytes — those three bytes are the requested PGN, little-endian (low byte first). A request for PGN 0xEE00 (address claimed) shows up as payload 00 EE 00.

(0.020) can0 18EA80FF#00EE00            ; "everyone, please claim again"

A transport sequence. Watch for 0xEC (control) and 0xEB (data) between the same source/destination pair. A directed transfer runs:

(0.100) can0 1CEC2210#10 14 00 03 FF 00 EF 00   ; RTS: I have 0x14 bytes / 3 pkts, target PGN 0xEF00
(0.101) can0 1CEC1022#11 03 01 FF FF 00 EF 00   ; CTS: send 3 packets starting at 1
(0.102) can0 1CEB2210#01 ...                     ; DT packet 1
(0.103) can0 1CEB2210#02 ...                     ; DT packet 2
(0.104) can0 1CEB2210#03 ...                     ; DT packet 3
(0.105) can0 1CEC1022#13 14 00 03 FF 00 EF 00   ; EoMA: got all 0x14 bytes

The first payload byte of an EC00 frame is the control byte: 0x10 is RTS (request-to-send), 0x11 is CTS (clear-to-send), 0x13 is end-of-message ack, 0x20 is BAM (broadcast announce), and 0xFF is abort. The key insight: the PGN on the wire is the transport PGN, not the application PGN — the real target PGN rides inside the control message (the last three payload bytes of the RTS, little-endian). See Transport protocol.

A broadcast. PF 0xF0 or higher, or PDU1 sent to destination 0xFF. No reply is expected; the data is for whoever cares.

(0.200) can0 18FEF142#...                ; PDU2 broadcast from node 0x42

Tips for capturing and replaying

To capture on a live or virtual interface:

candump -td -L can0 > capture.candump      # -td: delta timestamps, -L: log format
candump -l can0                            # writes a timestamped candump-*.log file

To replay or summarize a capture with machbus, the candump_replay example parses each line, rebuilds the frame, rejects anything that is not a valid extended ISOBUS/J1939 shape, and prints a decoded one-liner per accepted frame:

cargo run --example candump_replay -- path/to/capture.candump

Each accepted line prints the raw identifier, the decoded PGN, source, destination, length, and payload — the same fields you sliced out by hand above — followed by a parsed/accepted/rejected summary. It accepts both the compact # form and the bracketed [8] form, and it ignores CAN FD, error, and flagged frames rather than guessing them into classic CAN. To push a real capture onto a vcan interface and watch a node react, see the SocketCAN replay tutorial.

Common confusions

• The hex identifier is not the PGN. 18EF2280 is the whole 29-bit word. The PGN (0xEF00 here) is only the EDP/DP/PF part — and for PDU1 the PS byte is a destination, not PGN content. Strip priority and source first.
• The PDU1 destination byte hides in the identifier. For PF < 240, the PS slot is the destination. If you compute the PGN with PS still in it, you will invent PGNs that do not exist and miss who the frame was addressed to.
• Byte order inside the payload. The PGN carried inside a request or a transport RTS is little-endian: low byte first. 00 EE 00 means PGN 0x00EE00, not 0x00EE00 read big-endian. The same applies to most multi-byte numeric fields.
• Standard vs extended. A short identifier (two or three hex digits) is an 11-bit standard frame and is not ISOBUS/J1939 application traffic. Do not decode it with the PF/PS/SA layout.
• DLC versus actual bytes. In the bracketed form, [8] is the declared length. If the spelled-out bytes do not match it, the line is malformed and machbus’s parser drops it instead of padding or truncating.

See also

• PGN, priority, source, destination — the field-by-field primer behind this decoding.
• CAN and J1939 — where the 29-bit identifier comes from.
• Transport protocol — the RTS/CTS/data dance you will see in traces.
• SocketCAN replay — capture and replay on a virtual bus, end to end.

This is a reading guide, not a conformance claim: machbus is not certified, and real deployment still needs official standards, hardware, and interoperability evidence.

Further reading

These public resources are useful while learning the concepts in this section. They are references for orientation, not a substitute for official protocol documents when building a product.

AgIsoStack++

The public AgIsoStack++ docs have a clear beginner path that influenced the shape of these chapters:

• Concepts overview: https://github.com/Open-Agriculture/AgIsoStack-plus-plus/blob/main/sphinx/source/Concepts.rst
• Tutorial index: https://github.com/Open-Agriculture/AgIsoStack-plus-plus/blob/main/sphinx/source/Tutorials.rst
• Hello world tutorial: https://github.com/Open-Agriculture/AgIsoStack-plus-plus/blob/main/sphinx/source/Tutorials/The%20ISOBUS%20Hello%20World.rst
• Adding a destination: https://github.com/Open-Agriculture/AgIsoStack-plus-plus/blob/main/sphinx/source/Tutorials/Adding%20a%20Destination.rst
• Receiving messages: https://github.com/Open-Agriculture/AgIsoStack-plus-plus/blob/main/sphinx/source/Tutorials/Receiving%20Messages.rst
• Transport layer: https://github.com/Open-Agriculture/AgIsoStack-plus-plus/blob/main/sphinx/source/Tutorials/Transport%20Layer.rst
• Virtual Terminal basics: https://github.com/Open-Agriculture/AgIsoStack-plus-plus/blob/main/sphinx/source/Tutorials/Virtual%20Terminal%20Basics.rst
• Task Controller basics/client docs: https://github.com/Open-Agriculture/AgIsoStack-plus-plus/tree/main/sphinx/source/Tutorials

Public lookup databases

• ISOBUS.net landing page and lookup categories: https://www.isobus.net/isobus/
• Manufacturer codes: https://www.isobus.net/isobus/manufacturerCode
• Device class/function: https://www.isobus.net/isobus/nameFunction
• Source addresses: https://www.isobus.net/isobus/sourceAddress
• PGN/SPN lookup: https://www.isobus.net/isobus/pGNAndSPN/?type=PGN
• Process Data DDI lookup: https://www.isobus.net/isobus/dDEntity

machbus reference pages

• Protocol coverage: book/src/reference/protocol-coverage.md
• Hardware evidence: book/src/reference/hardware-evidence.md
• Claim boundary: book/src/reference/audit/conformance.md
• Binding contracts: book/src/reference/audit/bindings.md

When a public resource and machbus behavior differ, trust the executable tests for what this repository currently does, and use the resource to decide what should be improved next.

The standards, end to end

This section is the story of how an ISOBUS machine works — not a clause-by-clause recital, but the narrative an engineer needs to hold in their head. By the end you should be able to look at any frame on a tractor bus and know which layer produced it, why, and what happens next.

We build the picture from the wire up: a single twisted pair, then the language spoken on it, then the agreement that lets a tractor and a stranger’s implement cooperate the first time they are bolted together.

Throughout, standards are named only at the part level — “ISO 11783-6 (Virtual Terminal)”, “SAE J1939”, “NMEA 2000”. The explanations are written from how machbus implements the behavior; consult the official documents for normative wording.

The one-paragraph version

A tractor and an implement are two computers that have never met. They share two copper wires. CAN lets them put bits on those wires without electrocuting each other’s messages. SAE J1939 turns those bits into named messages (PGNs) sent between addresses. ISO 11783 takes J1939 and adds everything farming needs: a way to claim an address by identity so two strange devices never collide, a way to move data bigger than 8 bytes, a screen-sharing protocol so an implement can draw its own controls on the tractor’s terminal, a job/data protocol so a field computer can run a prescription, plus diagnostics, files, guidance, and safety interlocks. AEF is the club that certifies all of this actually interoperates; NMEA 2000 is the cousin protocol that carries the GPS fix.

The layer cake

Everything below sits on the layer above’s shoulders. Read it bottom-to-top: each layer only worries about its own job and trusts the one beneath it.

   ┌────────────────────────────────────────────────────────────────────┐
   │ application services   VT · TC · File Server · Sequence Control ·  │
   │                        TIM · diagnostics · guidance · GNSS feed    │
   │                        (ISO 11783-6, -7, -9 … -14)                 │
   ├────────────────────────────────────────────────────────────────────┤
   │ messages & transport   PGN requests/acks · TP / ETP · Fast Packet ·│
   │                        interconnect routing                        │
   │                        (ISO 11783-3, -4 · SAE J1939)               │
   ├────────────────────────────────────────────────────────────────────┤
   │ identity & addressing  NAME · address claim · who-may-talk         │
   │                        (ISO 11783-5)                               │
   ├────────────────────────────────────────────────────────────────────┤
   │ naming                 29-bit ID = priority + PGN + source + dest  │
   │                        (SAE J1939)                                 │
   ├────────────────────────────────────────────────────────────────────┤
   │ wire                   250 kbit/s CAN, 29-bit extended frames      │
   │                        (ISO 11783-2, ISO 11898)                    │
   └────────────────────────────────────────────────────────────────────┘

For a one-screen index of every part — what it does, where machbus implements it, and which chapter covers it — see Standards capability map.

The deep-dive chapters in this section follow these bands:

• The networking foundation — the bottom four bands: CAN, J1939 naming, address claiming, and transport. This is the spine; nothing else works until a node has claimed an address and can move data.
• The Virtual Terminal — ISO 11783-6, the screen-sharing protocol and the most elaborate application service.
• The Task Controller and the data dictionary — ISO 11783-10 and -11: documented work, process data, and the DDI vocabulary.
• Implement control, the tractor ECU, and the rest — ISO 11783-7/-9 plus diagnostics (-12), File Server (-13), Sequence Control (-14), and TIM.
• Positioning: NMEA and GNSS — how the fix gets onto the bus.

Who is on the bus

A useful mental model before the protocols: an ISOBUS network is a small town of control functions (CFs). Each CF is one participant with one job and one identity. A physical box (an ECU) may host several CFs. The cast of characters on a typical tractor-plus-implement bus:

   The bus — control functions side by side:

   ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
   │ Tractor         │ │ Virtual         │ │ Task            │ │ Implement       │ │ GNSS            │
   │ ECU (TECU)      │ │ Terminal        │ │ Controller      │ │ ECU             │ │ receiver        │
   │ speed · hitch   │ │ the screen,     │ │ runs the job,   │ │ VT + TC client, │ │ position,       │
   │ PTO · GNSS      │ │ soft keys       │ │ logs work       │ │ the actuators   │ │ COG / SOG       │
   └─────────────────┘ └─────────────────┘ └─────────────────┘ └─────────────────┘ └─────────────────┘

The tractor side mostly serves (it has the screen, the speed, the hitch). The implement side mostly requests (it borrows the screen, asks for the job, reports what it did). Many roles come in client/server pairs — a VT server (the terminal) and VT clients (each implement), a TC server and TC clients. machbus implements both halves of each pair.

A machine waking up: the first ten seconds

The single most important sequence to internalize is what happens when you turn the key. Every protocol above the wire depends on it.

 t0  Power on. The CF has a NAME (its 64-bit identity) and a *preferred* address,
     but is not yet allowed to send application traffic.

 t1  It broadcasts an Address Claim for its preferred address, putting its NAME
     on the wire as the tie-breaker.

 t2  Silence for the contention window?  → the address is ours. Claimed.
     Someone else claims the same address? → the *lower NAME wins*. The loser
     either grabs another address (if self-configurable) or goes quiet.

 t3  Now addressed, the CF starts its periodic chores: a TECU broadcasts wheel
     speed and hitch state; a CF may begin its heartbeat.

 t4  An implement's VT client goes looking for a terminal: "any VT out there?"
     It discovers the VT's address and version.

 t5  The VT client uploads its *object pool* — the entire description of its UI —
     in one big transport-protocol transfer, then asks the VT to activate it.

 t6  In parallel, the TC client uploads its *device description* (the DDOP) to the
     Task Controller and the two begin trading process data.

 t7  Steady state: status broadcasts tick along, the operator presses soft keys,
     setpoints flow down, as-applied values flow up, and the GNSS receiver feeds
     position the whole time.

machbus mirrors exactly this order. In the session facade you plug the subsystems you need, start() the claim, and drive poll(); address claim runs first and the application plugins only act once an address is held. See The session facade.

Why identity-based addressing is the clever bit

J1939 alone assigns addresses more or less by convention. That is fine for a truck built by one manufacturer. It falls apart the moment a random implement from a different manufacturer is hitched to a tractor it has never seen — both might want the same address.

ISO 11783-5 (network management) solves this with NAME-based arbitration. Every CF carries a 64-bit NAME encoding what it is (manufacturer, device class, function, instance, and a self-configurable flag), not where it sits. When two CFs want the same address, the numerically lower NAME wins the address and the other moves. Because NAMEs are unique by construction, the network always converges — no human, no DIP switches, no central authority. This is the property that makes “hitch any implement to any tractor” actually work, and it is why address claim is the first thing every node does.

   Conflict on address 0x80:

   CF-A  NAME = 0x00A0_0000_0000_1234   ─┐
   CF-B  NAME = 0x00C0_0000_0000_5678   ─┤  compare NAMEs
                                          ▼
                 0x00A0… < 0x00C0…  →  CF-A keeps 0x80
                 CF-B is self-configurable → claims 0x81 instead

Two sizes of message, and why transport exists

A raw CAN frame carries at most 8 bytes. Plenty for “engine speed = 1500 rpm”; hopeless for “here is a 40 KB object pool describing my user interface.” ISO 11783 inherits J1939’s answer and extends it:

• Single frame — ≤ 8 bytes, one shot.
• Transport Protocol (TP) — up to 1785 bytes, broken into 7-byte packets with flow control (a destination can say “send me packets 1–16, then pause”).
• Extended Transport Protocol (ETP) — megabyte-scale transfers for big object pools and files.
• Fast Packet — NMEA 2000’s lighter multi-frame scheme for things like a GNSS position record.

The deep dive covers the handshakes. The key idea: every layer above transport gets to pretend messages are arbitrarily large; transport quietly chops and reassembles.

The application services, in one breath

Once a node can claim an address and move data, the farming-specific services are just well-defined conversations on top:

Each has a dedicated codec and a session plugin in machbus. The deep-dive chapters tell each story properly.

Where AEF and NMEA fit

• AEF (Agricultural Industry Electronics Foundation) does not invent wire formats; it defines functionalities and a certification process that proves two vendors’ boxes actually interoperate. TIM (Tractor Implement Management) is an AEF-driven capability layered on the ISO messages. machbus models the functionality advertisement and the TIM authority guard, but ships no certification — see Conformity first.
• NMEA 2000 is a separate but CAN-compatible standard. On an ISOBUS machine it is how the GNSS receiver publishes position, course, speed, and attitude. machbus decodes the relevant PGNs so guidance and TC-GEO have a fix to work with.

How to read the rest of this section

The four deep-dive chapters are written to be read in order but stand alone. Each follows the same arc: the field problem, the mental model, the message anatomy, the lifecycle (with diagrams), how machbus expresses it, and the failure modes that bite in practice.

• The networking foundation
• The Virtual Terminal
• The Task Controller and the data dictionary
• Implement control, the tractor ECU, and the rest
• Positioning: NMEA and GNSS

If you would rather learn by building, jump to The session facade and come back here when a frame surprises you.

Standards capability map

The narrative chapters tell the story; this page is the map. Every standard that matters to an ISOBUS machine has a row here: what it does in one line, where machbus implements it, and which deep-dive chapter (or concept primer) covers it. Use it to jump straight to what you need, or to confirm that a given standard area exists in machbus at all.

Standards are named at the part level only. “Where in machbus” points at the source module and, where it exists, the session-facade plugin; “Read more” points at the chapter that explains the behavior.

The foundation

ISO 11783 — the ISOBUS parts

AEF and certified capabilities

The supporting cast (ISOBUS/J1939 services)

These are smaller but real parts of a working node, each an machbus plugin:

Suggested reading order

1. The standards, end to end — the landscape and the wake-up timeline.
2. The networking foundation — until this clicks, nothing above it makes sense.
3. The service you are building: VT, TC, or implement & the rest.
4. Positioning if guidance or TC-GEO is in scope.
5. Then build: The session facade.

For where each part lives in code, see the Crate map; for exactly which messages are implemented and tested, see Protocol coverage.

The networking foundation

Before any implement can borrow a screen or report a sprayed litre, four things must already work: the wire must carry bits, those bits must form named messages, the node must own an address, and it must be able to move data larger than one frame. That spine is ISO 11783 parts 1–5 standing on SAE J1939 and CAN. This page is the map; each layer has its own chapter.

Why this is the spine

A farmer buys a tractor from one company and a planter from another, ten years apart, and expects them to cooperate the moment the hitch pin drops — no installer, no network admin. Plug-and-play between strangers on a noisy two-wire bus is the demand that shapes every choice below. Get this layer right and everything above it is just conversation; get it wrong and nothing works at all.

The layer cake

Each layer trusts the one beneath it (read bottom-up):

   ISO 11783-5   network management  address claiming (lowest NAME wins)
   ISO 11783-4   network layer       joining segments, routing, loop guard
   ISO 11783-3   data link           TP / ETP / Fast Packet (big payloads)
   SAE J1939     naming              29-bit identifier · PGN · PDU1/PDU2
   ISO 11783-1   general             the NAME · device classes · layering
   ISO 11783-2   physical            250 kbit/s CAN · arbitration

Read it layer by layer

• ISO 11783-1 — general and device classes — the architecture and the NAME (with its bit-field).
• ISO 11783-2 — the physical layer — the CAN bus and non-destructive arbitration.
• SAE J1939 — the heritage — the identifier, PGNs, and the PDU1/PDU2 trap.
• ISO 11783-3 — data link and transport — moving more than 8 bytes (TP/ETP/Fast Packet) with the RTS/CTS handshake.
• ISO 11783-4 — the network layer — joining CAN segments safely.
• ISO 11783-5 — network management and address claiming — the plug-and-play handshake that runs first.

The two ideas to carry away

1. Lowest number wins, everywhere. CAN arbitration (lowest identifier wins the bus), message priority (lowest value wins), and address claiming (lowest NAME wins the address) are the same rule applied at three levels. Once it clicks, the whole foundation feels inevitable.
2. Layers above pretend messages are any size and addresses are stable. Transport quietly chops and reassembles; address claiming quietly resolves conflicts. The application services get to ignore both.

How machbus expresses the foundation

You almost never touch it directly — that is the point. Build a node with a NAME and a preferred address; the claim runs first. Send a payload of any size; the network layer picks single-frame / Fast Packet / TP / ETP. Receive fully reassembled Messages, routed to the subsystem that cares. React to AddressClaim and bus/confinement events on the unified stream. See The session facade.

From concept to code

Failure modes worth knowing (across the foundation)

• PDU1 vs PDU2 confusion — a frame that looks right but routes wrong.
• Talking before claimed — application sends are rejected until the claim completes.
• Transport timeouts/aborts — a stalled CTS or missed packet kills a transfer; retry.
• Address loss mid-run — a lower-NAME newcomer can take your address.
• Bus-off / error confinement — a flood of CAN errors takes a node off the bus.

See also

• The standards, end to end and Standards capability map.
• The Virtual Terminal — the first big service built on this spine.

ISO 11783-1 — general and device classes

Part 1 is the table of contents for the whole family: it lays out the layered architecture, defines the roles a participant can play, and — most importantly for day-to-day code — establishes the NAME, the 64-bit identity every control function carries. Everything else in this section is a specialization of the picture Part 1 paints.

Why this exists

ISOBUS is a system standard, not a single protocol. Part 1 exists so that the dozen later parts agree on the same vocabulary: what a “control function” is, what a “device class” means, how identity is structured, and how the layers stack. Without that shared frame, the VT part and the TC part would describe incompatible worlds.

The layered picture

   application services      VT · TC · FS · SC · diagnostics · implement · GNSS
        ───────────────────────────────────────────────────────────────
   identity & messaging      NAME · address claim · requests · transport
        ───────────────────────────────────────────────────────────────
   naming                    PGN · source · destination · priority   (J1939)
        ───────────────────────────────────────────────────────────────
   wire                      250 kbit/s CAN                          (Part 2)

Part 1 owns the top-to-bottom shape; the other parts fill in each band.

Roles and device classes

A participant is a control function (CF) — one job, one identity. A physical box (an ECU) may host several CFs. Part 1’s device-class vocabulary lets a CF say, in its NAME, roughly what kind of machine part it is (a tractor ECU, a planter, a fertilizer system, a positioning device, …). Other nodes use that to decide whether they want to talk to it.

   ECU "ACME-Box"
     ├─ CF: Tractor ECU      (device class = tractor, function = TECU)
     └─ CF: Navigation       (device class = positioning)

machbus models roles in net (the NAME and its fields) and surfaces the role/ownership mapping in Role boundaries.

The NAME, field by field

The NAME answers “what is this?”, not “where is it?”. It is 64 bits, and every field is exposed on net::Name:

   NAME (64 bits) — what a control function IS:

   ┌──────┬──────────┬──────────────┬──────────┬──────────┬──────────┬──────────────┐
   │ self │ industry │ device class │ function │ function │ ECU      │ manufacturer │
   │ cfg  │ group    │ (+ instance) │ code     │ instance │ instance │ + identity # │
   └──────┴──────────┴──────────────┴──────────┴──────────┴──────────┴──────────────┘

   self-cfg = "if I lose my address, I may pick another"
   manufacturer + identity number make every NAME globally unique

Two properties make the NAME the keystone of the whole network:

1. Globally unique — manufacturer code plus identity number guarantee no two CFs share a NAME.
2. Totally ordered — the 64-bit value is directly comparable, so any two CFs can deterministically decide who outranks whom.

Address claiming (Part 5) needs exactly those two properties and nothing more. The self-configurable bit decides a CF’s fate in a conflict: a self-configurable CF that loses its preferred address may take another; one that is not must go silent.

From concept to code

See also

• ISO 11783-5 — address claiming — where the NAME earns its keep.
• The standards, end to end — the whole-system story.

ISO 11783-2 — the physical layer

Part 2 is the copper. It fixes the bus that every higher layer assumes exists: a single twisted pair running at a defined speed, terminated correctly, with bit timing chosen so dozens of ECUs spread across a long machine all agree on where each bit starts and stops.

Why this exists

A field machine is an electrically brutal place — long harnesses, big motors, welding repairs in a shed. The physical layer is the agreement that makes a robust, deterministic bus out of that environment, and that lets a stranger’s ECU plug in and just work at the same bitrate and timing as everyone else.

The profile

   CAN_H ──┬───────┬───────┬───────┬──
   CAN_L ──┴───────┴───────┴───────┴──
           │       │       │       │
         ECU 1   ECU 2   ECU 3    GNSS

   • 250 kbit/s   • terminated at both ends
   • twisted pair • defined bit timing + sample point

machbus does not toggle pins — a transport/driver owns the hardware — but it validates the profile: a wrong bitrate, an out-of-range sample point, or inconsistent explicit bit-timing segments are rejected before they can be mistaken for a compliant bus.

The one idea that matters upward: arbitration

CAN’s defining trick is non-destructive, priority-based arbitration. When two nodes transmit simultaneously, the bus ANDs their bits: a dominant 0 overwrites a recessive 1. The node sending the lower identifier wins and continues; the loser detects the mismatch and backs off — no frame is destroyed.

   ECU X  transmits  1 0 1 1 0 …
   ECU Y  transmits  1 0 1 0 …        ← differs at bit 4
   bus    carries    1 0 1 0 …        ← Y's dominant 0 wins
                            ▲
                     X sees bus ≠ what it sent → X yields, retries later

This “lowest number wins, losers retry cleanly” behavior is the hardware foundation for two things higher up: message priority (low priority value = wins the bus) and NAME-based address claiming (low NAME = wins the address). The same rule, all the way up the stack.

From concept to code

See also

• SAE J1939 heritage — what those arbitrated bits mean.
• ISO 11783-3 — data link & transport — moving more than 8 bytes over this wire.

SAE J1939 — the heritage

ISOBUS did not start from scratch. It took SAE J1939 — the heavy-duty vehicle network already proven on trucks and buses — and built farming on top. Understanding what came from J1939 (and what ISO 11783 added) explains a lot of otherwise-arbitrary detail, especially the shape of the identifier and the PDU1/PDU2 split that trips up newcomers.

What J1939 contributed

J1939 turns raw CAN bits into a disciplined messaging system:

• The 29-bit identifier layout — priority, parameter group, and source address.
• PGNs (Parameter Group Numbers) — every message is a named group of parameters.
• The transport protocol — multi-packet BAM and RTS/CTS (see Part 3).
• The diagnostic “DM” family — DM1 active faults, DM2 history, and the rest, which ISO 11783-12 reuses almost verbatim.
• Address-based addressing — which ISO 11783-5 then upgraded to NAME-based claiming.

The identifier, decoded

   29-bit extended CAN identifier

   ┌────────┬─────┬───────────┬────────────────┐
   │ prio   │ EDP │ PF · PS   │ source address │
   │ 3 bits │ DP  │ (the PGN) │ 8 bits         │
   └────────┴─────┴───────────┴────────────────┘

• Priority — lower wins arbitration (safety low, status high).
• PGN — the message identity, assembled from the PF (PDU format) and, sometimes, the PS byte.
• Source address — who sent it.

PDU1 vs PDU2 — the classic confusion

The single most error-prone J1939 detail, inherited directly by ISOBUS:

   PF < 240  →  PDU1 (point-to-point)
                the PS byte IS the destination address
                e.g. "send this to address 0x26"

   PF ≥ 240  →  PDU2 (broadcast)
                the PS byte is part of the PGN itself
                e.g. "wheel speed, to everyone"

Get this wrong and you produce a frame that looks valid but routes to the wrong place — a destination-specific PGN sent as broadcast, or a broadcast PGN “addressed” to a node. machbus’s net::Identifier encodes/decodes this correctly; the failure mode is worth knowing because it shows up in hand-built frames.

What ISO 11783 added on top

In short: J1939 is the grammar; ISO 11783 is the agricultural language written in it.

From concept to code

See also

• The networking foundation — the overview of parts 1–5 on top of this heritage.
• ISO 11783-2 — physical layer — the CAN bus underneath.

ISO 11783-3 — data link and transport

A CAN frame holds at most 8 bytes. An object pool, a DDOP, or a file is far bigger. Part 3 (carrying SAE J1939’s transport) is how ISOBUS pretends messages can be any size: it chops a large payload into 7-byte packets, ships them with flow control, and reassembles them on the far side. Master this and the rest of the stack stops being mysterious — almost every “describe yourself” service rides this layer.

Why this exists

The services that make ISOBUS valuable — sending a whole UI to a terminal, a whole device description to a task controller, a whole file to a server — are all bulk transfers. Without a transport, none of them could exist on an 8-byte bus.

The three (plus one) ways to move data

   ≤ 8 bytes ─────────────► single frame              (one shot)
   ≤ 1785 bytes ──────────► Transport Protocol (TP)   (7-byte packets + flow control)
   up to megabytes ───────► Extended TP (ETP)         (big counters; pools, files)
   modest multi-frame ────► Fast Packet               (NMEA 2000's lighter scheme)

machbus picks automatically: hand it a payload and it chooses single-frame, Fast Packet, TP, or ETP; inbound, you receive the fully reassembled Message.

Broadcast transport (BAM): fire and forget

For data addressed to everyone, the sender announces the size, then streams packets at a fixed pace with no feedback. Listeners reassemble what they catch.

   sender ── BAM "1024 bytes / 147 packets, PGN X" ──►  (everyone)
   sender ── DT 1 ─► DT 2 ─► … ─► DT 147 ─►              (paced, no acks)
                                       │
                              receivers reassemble independently

Connection-mode transport (RTS/CTS): the receiver sets the pace

Point-to-point transfers let the destination throttle, so a small ECU is never flooded. This is the handshake to know cold:

   SENDER (drives)                                   RECEIVER (paces)

     ── RTS:  "1024 bytes, 147 packets, PGN X" ──────►   request to send
     ◄─ CTS:  "send 16 packets, starting at #1" ─────    clear-to-send window
     ── DT #1 … #16 ─────────────────────────────────►   one window of data
     ◄─ CTS:  "send 16 packets, starting at #17" ────
     ── DT #17 … #32 ────────────────────────────────►
        … repeat until all 147 packets sent …
     ── DT … #147 ───────────────────────────────────►
     ◄─ EndOfMsgAck:  "got all 1024 bytes" ─────────     done
     ◄─ (or) Abort:   "stop — reason R" ────────────     failure, any point

Things that bite in practice and that machbus’s TP/ETP engines handle for you:

• Windows and holds. A receiver may send a CTS with a zero count to say “hold — I’m busy”; the sender waits and resumes on the next non-zero CTS.
• Timeouts. If a CTS or a data packet does not arrive within the protocol window, the session aborts; robust callers retry the whole transfer.
• One session per peer-pair-and-PGN. Starting a second transfer to the same peer for the same PGN while one is active is an error; machbus queues it behind the active one.
• Abort. Either side can abort with a reason at any point; the half-sent payload is discarded.

Extended TP and Fast Packet

ETP is the same shape as RTS/CTS with larger counters for megabyte payloads (big object pools, files). Fast Packet is NMEA 2000’s lighter multi-frame format for records like a GNSS position — a header frame plus a few continuation frames, no windowed flow control. machbus reassembles all of them beneath the message layer.

From concept to code

See also

• ISO 11783-4 — network layer — moving these messages across joined segments.
• The Virtual Terminal and The Task Controller — the biggest users of transport.

ISO 11783-4 — the network layer

Most machines are one CAN segment and can ignore this part. But a big machine — a tractor with its own bus joined to a large implement with its own bus — is two segments bridged by a router. Part 4 defines how a message crosses that boundary safely: which messages forward, in which direction, and how to avoid loops and address clashes between the two sides.

Why this exists

One CAN segment has electrical and load limits. When a machine outgrows them, you split it and join the halves with an interconnect (a network interconnection unit, NIU). The moment you do, two new problems appear: a broadcast could echo back and forth forever (a loop), and two devices on opposite segments might claim the same address. Part 4 is the rulebook that prevents both.

The mental model

   Tractor segment                     Implement segment
   (TECU · VT · GNSS)                   (rate ctrl · sections · sensors)
          │                                      │
          └──────────────►  ┌───────┐  ◄─────────┘
                            │  NIU  │   router: forwards selected PGNs by
                            └───────┘   rule, drops echoes, guards addresses

The NIU is not a dumb repeater. It applies forwarding rules: a given PGN may be allowed to cross in one direction, both, or neither, optionally filtered by source or destination NAME. A loop guard ensures a forwarded frame is not forwarded back.

What machbus models

machbus implements the interconnect in net::niu: forwarding policies per PGN, direction control, NAME-based source/destination filters, and the loop guard. It is the piece that lets a large machine scale without every ECU having to know it lives on a multi-segment network.

For single-segment applications — the common case — none of this is in your way; you build one node on one bus and the network layer is invisible.

From concept to code

See also

• ISO 11783-3 — data link & transport — what is being routed.
• ISO 11783-5 — address claiming — the address clashes the NIU must guard against.

ISO 11783-5 — network management and address claiming

This is the part that makes “hitch any implement to any tractor” actually work. Part 5 turns two strange boxes that both want the same address, with no installer and no central authority into a deterministic, self-healing assignment. It is the first thing every node does after power-on, and nothing above it may speak until it finishes.

Why this exists

SAE J1939 mostly assigns addresses by convention — fine for one manufacturer’s truck. On a farm, a random implement from another vendor, built years apart, may want the same address as something already on the bus. There is no human to resolve it. Part 5 resolves it automatically using the one thing that is guaranteed unique and comparable: the NAME.

NAME arbitration: lowest NAME wins

When two CFs contend for an address, they compare 64-bit NAMEs and the numerically lower one keeps the address. Because NAMEs are unique, the contest always has a winner and the network always converges.

   Both want address 0x80:

   CF-A   NAME = 0x00A0_0000_0000_1234   ┐
   CF-B   NAME = 0x00C0_0000_0000_5678   ┘ compare as 64-bit numbers
                       │
                 0x00A0… < 0x00C0…
                       ▼
        CF-A keeps 0x80   ·   CF-B must move (if self-configurable) or go silent

This is the same “lowest number wins” rule as CAN arbitration — applied to identity instead of priority.

The state machine

   POWER ON
      │   have NAME + preferred address; may not send app traffic yet
      ▼
   CLAIMING ── broadcast "I claim 0x80, NAME = N" ──►  bus
      │
      │   wait the contention window, then:
      │
      ├─ no contender ──────────────►  CLAIMED   (may now send app traffic)
      ├─ contender, higher NAME ────►  CLAIMED   (the contender yields)
      └─ contender, lower NAME ─────►  lose 0x80:
            ├─ self-configurable ─►  claim another address (→ CLAIMING)
            └─ not ───────────────►  SILENT (cannot operate)

Rules machbus enforces:

• No application traffic before CLAIMED. The session core refuses app sends until the claim completes — this is why “drive the claim loop first” is the cardinal rule.
• Request for Address Claim. Any node can ask everyone to re-announce; a CF replies with its current claim.
• Address violation → diagnostic. Detecting another node on your claimed address is surfaced as a DTC (SPN derived from the offending address).
• Loss mid-run. A lower-NAME newcomer can take your address while you are running; a self-configurable CF moves, and the change is reported on the event stream.
• Convergence. Because the tie-break is numeric and NAMEs are unique, the network reaches a stable assignment with no oscillation.

NAME management (dynamic identity)

A further wrinkle: a CF can be commanded to adopt a new NAME (NAME management). The node applies the new identity and re-claims. machbus models this with the NameManagement plugin, which answers the management requests, adopts a commanded NAME, and triggers a fresh claim.

From concept to code

See also

• ISO 11783-1 — the NAME — the identity this part arbitrates on.
• The networking foundation — the overview that ties parts 1–5 together.

The Virtual Terminal

The Virtual Terminal — ISO 11783-6 — is the most elaborate service on the bus, and the one that makes ISOBUS visible to a farmer. It is a screen-sharing protocol: an implement with no display of its own ships a complete description of its user interface to the terminal in the cab, and from then on the two cooperate to show controls and react to the operator. This chapter tells that story end to end.

Why this exists

A modern cab cannot grow a new dial and a new screen layout every time a different implement is attached. So the cab terminal is deliberately dumb about implements: it is a general-purpose renderer that knows how to draw rectangles, numbers, strings, bars, and buttons, and how to report touches and key presses. The implement is the one that knows what its UI should look like. The VT protocol is the contract that lets the implement describe its UI once, hand it over, and then drive it — so any implement can present rich controls on any certified terminal.

   IMPLEMENT (VT client)                      CAB (VT server)
   "knows what the UI means"                   "knows how to draw"

     ── object pool (the whole UI) ──────────────►   uploaded once
     ── change_numeric_value(rate, 42) ──────────►   field redraws
     ◄─ soft key 3 pressed ───────────────────────   operator input

Mental model: the object pool

The implement’s UI is a pool of objects, each with a numeric ID, that reference one another to form a tree. A working set object is the root; it points at data masks (full-screen layouts); masks contain containers, output fields, input fields, buttons, bar graphs, and so on; fonts, colours, and pictures are shared leaf objects. machbus models all ~48 object types in isobus::vt.

   WorkingSet ──► DataMask "main" ──► OutputNumber "rate"
       │              │           └─► SoftKeyMask ──► Key 1, Key 2, Key 3
       │              └─► OutputString "status"
       └──► DataMask "settings" ──► InputNumber, InputList …

   shared: Font, Colour, Picture, Macro, … (referenced by ID)

The pool is data, not code. The implement builds it (often exported from a design tool as an .iop file), and machbus’s codec serializes it to the exact wire layout the terminal expects and parses it back — including the per-type length walk that makes the byte stream unambiguous.

The lifecycle: find, upload, activate, run

A VT client moves through a connect state machine. The shape:

  DISCONNECTED
     │  who is a VT?  (look for VT status)
     ▼
  DISCOVERED  ── learns the VT's address + version
     │  send working-set announcement
     ▼
  UPLOADING   ── transfer the whole object pool (big → Transport Protocol)
     │  "End of Object Pool"; VT validates it
     ▼
  ACTIVATING  ── ask the VT to make this pool the active one
     │  activation OK
     ▼
  CONNECTED   ── steady state: push value changes, receive input events

Two realities make this interesting:

• The pool is large. The upload rides the Transport Protocol from the foundation chapter — often hundreds or thousands of bytes in one connection-mode transfer. A failed transfer means no UI.
• Versions differ. Terminals advertise a VT version and capabilities (screen size, colour depth, soft-key count, fonts). A good client adapts; machbus exposes the version handshake and capabilities so you can.

Anatomy of the runtime conversation

Once CONNECTED, the protocol is a steady two-way stream:

Client → VT (commands). The implement keeps the displayed UI in sync with its internal state. The common commands, all on the machbus VT client:

VT → client (events). The terminal reports what the operator did and what it decided:

machbus surfaces these as VtEvent variants on the unified event stream.

Doing it with machbus

On the recommended facade, the whole lifecycle is a plugin:

   Session::builder(name, addr)
       .plug(VtClient::new(config, pool, working_set))
       .spawn(transport)
              │
              ▼  driver.poll() each cycle
   ┌────────────────────────────────────────────────────────┐
   │ FSM: discover → upload → activate → run                │
   │ inbound VT frames → VtEvent on the event stream        │
   │ your commands (set_value, …) → buffered, sent next tick│
   └────────────────────────────────────────────────────────┘

You point the client at a VT (connect_to), and once connected push updates with set_value / set_string / etc. through fine control. Soft-key and value-change events arrive on poll() (or drain::<VtEvent>()). The full walkthrough is in the Virtual Terminal client tutorial; the server side (acting as the terminal) is in Virtual Terminal server.

machbus also ships a renderer and a VT server: it can play the terminal, maintain the active pool, apply runtime commands, run macros, and report operator input — useful for simulation, testing, and headless terminals.

Auxiliary control (AUX)

Beyond the screen, ISO 11783-6 defines auxiliary inputs — physical joysticks and switch banks that an operator assigns to implement functions. There are an older (AUX-O) and a newer type-2 (AUX-N) scheme. machbus decodes the status messages and, on the VT-version-5 path, the capability discovery that lets a client learn what auxiliary channels a terminal offers.

Failure modes worth knowing

• Pool too big or malformed — the VT rejects the upload or returns a pool error; nothing draws. Validate the pool and watch for PoolError.
• Version mismatch — commands or objects the terminal does not support fail silently or with a pool error; check the advertised version/capabilities first.
• Lost activation — another working set can become active; handle ActiveWorkingSet so you do not fight for the screen.
• Editing races — the operator may be editing a field while you push a new value to it; the protocol and a careful client reconcile who wins.
• Reconnect — if the VT drops, the client must re-discover and re-upload; the pool is not persisted on the terminal across a real power cycle.

From concept to code

What this proves / does not prove

machbus implements the VT client, server, renderer, and the object-pool codec, and exercises them against real .iop pools and reassembled uploads. That proves the protocol behavior locally; it does not prove pixel-accurate rendering on a specific commercial terminal or AEF VT certification — see Conformity first.

See also

• The Task Controller and the data dictionary — the other big implement-side service, usually running alongside the VT.
• VT object pools, VT updates, VT auxiliary capabilities.

The Task Controller and the data dictionary

If the Virtual Terminal is how a machine talks to the operator, the Task Controller is how it does documented work. ISO 11783-10 (Task Controller) defines the conversation between a field computer and an implement so a prescription can be executed, section by section, and an accurate as-applied record produced. It only works because ISO 11783-11 gives everyone a shared vocabulary — the data dictionary (DDIs). This chapter covers both.

Why this exists

Precision agriculture is bookkeeping at speed. A sprayer must apply the right rate at the right place, turn individual booms off over already-covered ground, and log exactly what it did for compliance and analytics. None of that is possible unless the field computer and the implement agree, to the litre and the centimetre, on:

• what the implement is — how many booms, sections, and tanks; what it can measure and control;
• what each number means — that “application rate” is this DDI, in these units, at this resolution;
• where the implement is — so coverage and section control line up with the map.

The TC protocol plus the DDI dictionary plus a geometry description make that agreement machine-readable.

The two halves

   TASK CONTROLLER (server)                 IMPLEMENT (TC client)
   the field computer / job log             the sprayer / seeder

        ◄──── DDOP upload ─────────────────  "here is what I am" (device desc.)
        ───── activate ───────────────────►
        ───── setpoint: rate = 200 L/ha ──►  process data DOWN (commands)
        ◄──── measured: actual = 198 ─────   process data UP (as-applied)
        ◄──── section 3 worked ───────────

machbus implements both: a TC client (the implement side) and a TC server (the controller side), plus the DDOP builder, the process-data helpers, peer control, and TC-GEO geometry/prescription conversion.

The device description: the DDOP

Before any work, the implement uploads a Device Object Pool (DDOP) — a tree that describes the machine. It is conceptually similar to a VT object pool, but instead of describing a screen it describes a machine’s structure and capabilities:

   Device "ACME Sprayer"
     └─ DeviceElement "boom"                (a functional part)
          ├─ DeviceProcessData  DDI=ActualRate     (a runtime value)
          ├─ DeviceProcessData  DDI=SetpointRate
          ├─ DeviceProperty     DDI=WorkingWidth    (a fixed attribute)
          └─ DeviceElement "section 1"      (offset X/Y/Z, width)
             DeviceElement "section 2"
             …

• DeviceElement — a part of the machine (the device, a boom, a section), with a geometry (offsets from a reference point).
• DeviceProcessData — a runtime value the TC can read or write (rate, speed, section state), tagged with a DDI.
• DeviceProperty — a definition-time constant (working width, capacity).

machbus builds DDOPs fluently and serializes them to the wire layout. The upload itself rides the Transport Protocol — a DDOP is far bigger than one frame.

The shared vocabulary: DDIs (ISO 11783-11)

A DDI — Data Dictionary Identifier — is a number that means a specific quantity, in specific units, at a specific resolution, agreed across the whole industry. “Setpoint volume per area application rate” is one DDI; “actual working width” is another. The dictionary is what stops one vendor’s “rate” being another vendor’s “rate ÷ 10.”

machbus ships the dictionary as a generated, sorted, fingerprinted table with:

• lookup by DDI number, distinguishing a known entry from the unknown sentinel;
• resolution-aware engineering conversion (raw integer ↔ real units), saturating on invalid input;
• explicit handling of the proprietary DDI range so custom values never collide with the unknown sentinel.

Crucially, the data dictionary is a public vocabulary; machbus references named DDI constants (e.g. ddi::ACTUAL_WORKING_WIDTH) rather than magic numbers, and its helpers carry the named references through so geometry, rate, and total semantics stay correct. The dictionary has its own deep-dive: ISO 11783-11 — the data dictionary.

The lifecycle

  DISCONNECTED
     │  who is a TC?  (TC status broadcast)
     ▼
  DISCOVERED ── learns TC address + version
     │  working-set master + version handshake
     ▼
  UPLOADING  ── transfer the DDOP (Transport Protocol)
     │  activate
     ▼
  CONNECTED  ── trade process data for the life of the task
     │           setpoints down, measurements up, section reports
     ▼
  (task ends / disconnect)

This mirrors the VT lifecycle deliberately — discover, upload a big description, activate, then run — because both are “describe yourself, then cooperate” services. machbus drives the FSM and ships the frames; you supply the DDOP and react to value requests and commands.

Process data in practice

Once connected, process data flows continuously:

• Down (TC → implement): setpoints and triggers — “set rate to 200 L/ha”, “enable section 4”.
• Up (implement → TC): measured values and state — “actual rate 198”, “section 4 on”, “12.4 ha worked” — sometimes on change, sometimes on a time/distance trigger the TC requests.

The TC can ask for values on a trigger (every N ms, every N cm, on change, on threshold) so the network is not flooded. machbus exposes the process-data value helpers and the request/command path.

Priority follows the command, not the PGN

All of this rides one parameter group (0xCB00), but Annex B.2 does not give it one priority. It splits three ways by the command nibble in byte 1:

The split arrived in version 4 “giving higher priority to control and connection maintenance messages versus request and acknowledgement messages”. It matters because the TC Status (E) and Client Task (F) messages are the heartbeats each side declares the other dead over after six seconds — sending them at the same priority as a bulk DDOP transfer is how they get starved on a loaded bus. ProcessDataCommands::priority() carries the mapping.

Peer control and TC-GEO

Two higher-order capabilities sit on the TC foundation:

• Peer control — the TC can hand control of a specific element/DDI from one CF to another (for example, letting a guidance or rate controller drive a section directly). machbus models the peer-control assignment messages and surfaces them as events.
• TC-GEO — geographic/prescription work: turning a position fix plus a prescription map into per-section setpoints, with DDI-aware engineering conversion for the rates. This is where the GNSS feed (see Positioning) meets the DDOP geometry.

   prescription map  +  GNSS fix  +  DDOP geometry (section offsets/width)
            │               │                 │
            └───────────────┴─────────────────┘
                            ▼
              per-section setpoint rates (TC-GEO)
                            ▼
              process data DOWN to the implement

Doing it with machbus

On the session facade, plug TcClient (implement) or TcServer (controller):

   Session::builder(name, addr)
       .plug(TcClient::new(config, ddop))
       .spawn(transport)
              │
              ▼  driver.poll() each cycle
       FSM: discover → announce → upload DDOP → activate → trade data
       state changes → Event::Tc(TcEvent::StateChanged(..))

The full hands-on path is in the Task Controller client tutorial and Task Controller server tutorial; DDOP construction in DDOP; the geographic side in TC-GEO prescription.

Failure modes worth knowing

• DDOP rejected — a structural or DDI error makes the TC refuse activation; validate the DDOP and watch the state machine.
• Magic DDI numbers — using a raw number instead of a named, dictionary-checked DDI is how units quietly drift; machbus’s helpers guard against it.
• Trigger storms vs starvation — too-frequent triggers flood the bus; too-rare ones lose resolution in the as-applied log. Match the trigger to the work.
• Geometry mistakes — wrong section offsets/widths make section control and coverage misalign with reality even when every message is “valid.”
• Version gaps — older TCs support fewer features; negotiate on the advertised version.

From concept to code

What this proves / does not prove

machbus implements the TC client/server, DDOP, process data, peer control, TC-GEO conversion, and the DDI dictionary, tested locally. That proves protocol and conversion behavior; it does not prove interoperability with a specific commercial TC or AEF TC certification — see Conformity first.

See also

• The Virtual Terminal — usually running alongside the TC.
• Positioning: NMEA and GNSS — the fix that feeds TC-GEO.
• ISO 11783-11 — the data dictionary — the shared DDI vocabulary.

ISO 11783-11 — the data dictionary

The Task Controller can only trade numbers if everyone agrees what each number means. Part 11 delegates that agreement to a public dictionary of DDIs — Data Dictionary Identifiers — each pinning a quantity to specific units and resolution. It is the vocabulary that makes one vendor’s “application rate” equal another vendor’s.

Part 11 does not contain the dictionary. The document is three pages. §4.1 says the process-data variables “shall be as defined in the ISOBUS Data Dictionary, accessible at the ISOBUS website” — maintained by VDMA as the maintenance agency appointed by the ISO Technical Management Board — and §4.2 fixes only the shape of an entry: “identification number; process data element definition; range of the process data element; resolution of the process data element; units of the process data element.”

So the DDI values below are sourced from the online database, and no document in the ISO 11783 series can be used to check them. What is checkable is that every entry carries those five attributes, which DDIDefinition does. See the standards-text audit.

Why this exists

“Rate = 200” is meaningless without units and scale. Is that litres per hectare, or kilograms, or millilitres per square metre? At what resolution? Part 11 removes the ambiguity: a DDI number is the definition. Pick the DDI for “setpoint volume per area application rate” and both ends know the units and the integer-to-real conversion.

What a DDI carries

   DDI 0x0001 ─► "Setpoint Volume per Area Application Rate"
                  unit: mm³/m²   ·   resolution: 0.01   ·   range: …
   DDI 0x0043 ─► "Actual Working Width"  ·  unit: mm  ·  resolution: 1
   …                                      (a public, industry-wide table)

Two ranges matter:

• the standard range — the published dictionary everyone shares;
• the proprietary range — vendor-private DDIs, which must never collide with the unknown sentinel the lookup returns for unrecognized numbers.

How machbus expresses it

machbus ships the dictionary as a generated, sorted, fingerprinted table with:

• lookup by number, distinguishing a known entry from the unknown sentinel;
• engineering conversion — raw integer ↔ real units using the entry’s resolution, saturating cleanly on invalid input;
• proprietary-range handling so custom DDIs never alias the unknown sentinel.

Crucially, the code refers to named DDI constants (e.g. ddi::ACTUAL_WORKING_WIDTH) rather than magic numbers, and the DDOP/process-data helpers carry those named references through so geometry, rate, and total semantics stay correct end to end.

   raw 12_345  ── ddi_to_engineering(DDI, raw) ──►  123.45 (real units)
   123.45      ── ddi_from_engineering(DDI, x) ──►  12_345 (raw, saturating)

From concept to code

Failure modes worth knowing

• Magic numbers — a raw DDI literal instead of a named, dictionary-checked constant is how units silently drift.
• Resolution mistakes — applying the wrong scale turns 200 L/ha into 20 or 2000.
• Proprietary collisions — a custom DDI that overlaps the unknown sentinel becomes invisible.

See also

• The Task Controller — the protocol that uses this vocabulary.

Application services: implement, tractor, and the rest

The Virtual Terminal and Task Controller get the spotlight, but a working machine runs on a handful of quieter services: the messages that move a hitch and spin a PTO, the tractor’s promise of what it offers, diagnostics, the on-bus filesystem, saved automation sequences, and the AEF authority that lets an implement command the tractor. This page is the map; each service has its own chapter.

The services at a glance

   ISO 11783-7   implement messages   hitch · PTO · aux valves · speed · lighting
   ISO 11783-9   tractor ECU          facilities advertisement + status source
   ISO 11783-12  diagnostics          DM1 faults, clears, freeze frames, memory, IDs
   ISO 11783-13  File Server          a shared filesystem on the bus
   ISO 11783-14  sequence control     headland automation and saved step sequences
   AEF / TIM     authority            implement commands the tractor, under interlocks

Read each service

• ISO 11783-7 — implement messages — the physical-control vocabulary (hitch, PTO, aux valves, speed/distance, lighting).
• ISO 11783-9 — the tractor ECU — facilities, classes, and the capability contract.
• ISO 11783-12 — diagnostics — the DM fault family and service-tool access.
• ISO 11783-13 — the File Server — files, volumes, and the TAN-matched request/response model.
• ISO 11783-14 — sequence control — master/client step automation.
• TIM (AEF) — authority with safety interlocks.

The supporting cast

A few more services round out a real node, each an machbus plugin:

From concept to code

See also

• The networking foundation — what these services stand on.
• The Task Controller and The Virtual Terminal — the two big implement-side services.
• Standards capability map — the one-screen index.

ISO 11783-7 — implement messages

Part 7 is the vocabulary of physical machine control: the frames that report and command hitches, power take-offs, auxiliary valves, ground/wheel speed, distance, and lighting. These are the network’s steady heartbeat of “what the iron is doing” and “what I want it to do.”

Why this exists

A tractor and an implement must continuously agree on the physical situation: how fast the ground is moving, where the hitch is, whether the PTO is turning, which booms are on. Part 7 standardizes those signals so a rate controller, a guidance system, or a section controller from any vendor reads the same numbers.

The message families

   TRACTOR  ── wheel-based speed + distance ──►  bus      (Class 1+)
   TRACTOR  ── ground-based speed (radar) ────►  bus      (Class 2+)
   TRACTOR  ── machine-selected speed ────────►  bus
   TRACTOR  ── front/rear hitch status ───────►  bus
   TRACTOR  ── front/rear PTO status ─────────►  bus
   IMPLEMENT ── aux-valve command ────────────►  tractor
   either   ── lighting command / data ───────►  bus

Two ideas to hold

Speed has provenance. Wheel-based, ground-based (radar), and machine-selected speed are different signals with different trust. A controller must choose the right one — radar for true ground speed, wheel for driveline. machbus decodes each with 0xFF-tail “not available” handling, and offers a wheel-slip helper derived from wheel vs ground speed.

   wheel speed 10.0 km/h ─┐
   ground speed 9.2 km/h ─┴─► slip = (10.0 − 9.2)/10.0 = 8%

Status and command are symmetric. The same structures describe “the hitch is at 62%” and “move the hitch to 80%”; front vs rear is carried by which PGN delivered it. machbus’s Implement plugin decodes the status/command families into a cache plus events, and offers broadcast_* / command_* helpers.

From concept to code

Failure modes worth knowing

• Wrong speed source — using wheel speed where radar ground speed is meant skews rate and coverage.
• Front/rear mix-up — acting on the wrong hitch/PTO because the PGN was misread.
• Ignoring “not available” — treating a 0xFF-filled signal as a real zero.

See also

• ISO 11783-9 — the tractor ECU — what the tractor advertises it can do.
• TIM (AEF) — guarded command of the tractor by the implement.

ISO 11783-9 — the tractor ECU

Part 9 defines the Tractor ECU (TECU) — the tractor’s representative on the bus — and, crucially, its classes. A tractor advertises which facilities it offers and at what class level, so an implement knows up front whether the tractor can do what it needs before it asks.

Why this exists

An implement that needs ground speed, rear-hitch control, and guidance readiness must not blindly send commands and hope. Part 9 makes the tractor publish a contract of capability: “here is what I provide, at this class.” The implement reads it and adapts — or warns the operator that this tractor cannot run this implement fully.

Facilities and classes

   TECU advertisement ──► "I provide:
                            • ground + wheel speed
                            • rear hitch control
                            • rear PTO
                            • guidance readiness"
                              ▲
   implement reads it, then only requests facilities the tractor actually offers

Higher tractor classes provide more facilities (more speed signals, more hitch/PTO control, guidance). machbus models the facility set, the class matrix, and the tractor() preset plus the Implement facilities broadcast that advertises them; maintain-power and guidance-readiness sit here too.

Steering, speed and motion are three separate classes

Base class 1/2/3 says nothing about whether a tractor can be driven over the bus. That is carried by letter addenda, and §4.4.2 gives them separately:

A class 2G tractor steers on command and need not accept a speed command at all. Even with P, §4.4.2.8 says outright that bringing the tractor to a stop (speed 0.0) is optional and “can be determined by an implement via the tractor facilities response message”.

The handshake is not optional for the implement either

Two PGNs, and the second one is the part that surprises people:

• 0xFE09 Tractor Facilities Response — what the TECU has installed.
• 0xFE0A Required Tractor Facilities — what the implement needs.

§4.4.2: “An implement CF can send the required tractor facilities message to the Tractor ECU to enable the transmission of the messages that provide the required facilities. A facility is not required if its corresponding bits are set to 0 in the implement CF required tractor facilities message. The Tractor ECU can then stop the transmission of this implement message to reduce bandwidth.”

So a node that never declares what it needs may simply never receive it. That is why AutoDrive broadcasts the request on a cycle rather than only listening.

The TECU’s other duties

Beyond the advertisement, a TECU is the source of the part-7 status broadcasts (speed, hitch, PTO) and the relay for some tractor-side services. In machbus a tractor node is typically the Implement plugin (for the status/command messages) plus the facilities advertisement, optionally MaintainPower and guidance.

From concept to code

See also

• ISO 11783-7 — implement messages — the signals the TECU produces.
• TIM (AEF) — how an implement borrows the tractor’s facilities under authority.

ISO 11783-12 — diagnostics

When a sensor reads out of range, a valve stops responding, or a supply voltage sags, the ECU that noticed needs to tell the network, and a service technician needs to read that fault back later. Part 12 is the shared language for that. It reuses the SAE J1939 “DM” diagnostic family almost verbatim and adds a few ISOBUS-specific wrinkles.

Why this exists

A fault only one ECU knows about is useless to everyone else. Network diagnostics make a fault visible (other nodes and the terminal can show it) and durable (a service tool can read and clear it long after it occurred).

The anatomy of a fault

   a DTC = SPN (which parameter is wrong)
         + FMI (how it is wrong: too high, too low, open circuit, …)
         + occurrence count (how many times)
   plus a lamp panel: malfunction / warning / protect / amber-red status

The DM family

   active faults   ──► DM1   broadcast, periodic
   previous faults ──► DM2   on request
   clear           ──► DM3 / DM11 (clear all) · DM22 (clear one, with ack/nack)
   freeze frame    ──► DM25  captured conditions at fault time
   memory access   ──► DM14 / DM15 / DM16   service-tool read/write
   identity        ──► ECU / software / product identification strings

The DM1 broadcast is the heartbeat of health: a node periodically announces its active faults; clearing one moves it to the “previously active” list. ISOBUS adds a sixth ECU-identification field and the control-function functionalities advertisement on top of the J1939 base.

ISOBUS DM1 and DM2 have no lamp bytes. Annex B.6 and B.7 define bytes 1–2 as “Reserved, set to FF16” and put SPN/FMI/occurrence in bytes 3–6; the word “lamp” does not appear in ISO 11783-12 at all. J1939-73 does put lamp status there, which is why DmDtcList keeps two encoders — encode() for the J1939 form and encode_iso() for the ISOBUS one. The diagnostics plugin broadcasts the ISOBUS form.

Advertising functionalities is forward-compatible by design

The Control Function Functionalities message (PGN 0xFC8E) is how a node says which roles it implements and at which generation. Annex B.9 is unusually explicit that a reader must tolerate what it does not recognise:

“Functionality characteristics values reserved for ISO assignment shall be parsed without generating an error.” … “If the number of option bytes is larger than specified in this document for a functionality, the receiving CF shall ignore the undefined functionality option bytes and parse the known option bytes for this functionality only.”

Both halves matter, because A.10 keeps the 0–255 functionality list in the online database — it grows between revisions. A decoder that rejects the message over one unknown code throws away every functionality it did understand, so machbus skips unknown blocks using their own declared option length and keeps the rest.

How machbus expresses it

Two plugins cover the family:

• Diagnostics — owns the active/previous lists, the periodic DM1 broadcast, and request handling (DM1/DM2 requests, DM3/DM11 clears, DM22 individual clears). You raise/clear faults through fine control; inbound peer faults arrive as Event::Diag(DiagEvent::Dm1Received { .. }).
• DmMemory — the service-tool messages (DM14/15/16) and the identity strings, with automatic answers to identification requests.

   ctrl.with_mut::<Diagnostics, _>(|d| d.raise(dtc));   // active → goes out on DM1
   // peer DM1 → Event::Diag(DiagEvent::Dm1Received { source, active, lamps })

From concept to code

Failure modes worth knowing

• Silent faults — forgetting to enable diagnostics means a real fault never reaches the bus.
• Stale active list — clearing must move a DTC to previously-active, not just drop it.
• Identity gaps — service tools expect identification responses; missing them looks like a dead ECU.

See also

• SAE J1939 — the heritage — where the DM family comes from.
• Implement control, the tractor ECU, and the rest — the services overview.

ISO 11783-13 — the File Server

Part 13 puts a filesystem on the bus. A File Server offers volumes and directories; clients open, seek, read, write, and close files, manage attributes, and query free space — each as a request/response exchange. It is how implements persist configuration, prescriptions, and logs without storage of their own.

Why this exists

A small implement ECU may have little or no non-volatile memory, yet it needs to load a prescription, save an as-applied log, or keep settings across power cycles. Rather than give every ECU a card slot, ISOBUS lets one node be the server and everyone else share it.

The conversation

Every operation is a request tagged with a transaction number (TAN); the matching response carries the same TAN, so a client can have several in flight:

   CLIENT                                   SERVER
     │ ── open "/presc.bin", read ──► (TAN 7)
     │ ◄── handle 3, ok ────────────
     │ ── read handle 3, 512 bytes ─► (TAN 8)
     │ ◄── 512 bytes ───────────────          (large reads ride Transport Protocol)
     │ ── write handle 3, <data> ──► (TAN 9)
     │ ◄── 512 bytes written ───────
     │ ── close handle 3 ──────────► (TAN 10)
     │ ◄── ok ──────────────────────

The full surface: connect (a CCM handshake), open/close, read/write/seek, get/set attributes, get date-time, current/change directory, move/delete, volume init and status, plus free-space queries.

How machbus expresses it

machbus implements both halves with an async-style request → event model: each request method returns its TAN immediately, and the matching response arrives later as an FsEvent. The FsClient plugin drives the client; FsServer serves in-memory files and directories.

   let tan = ctrl.with_mut::<FsClient, _>(|fs| fs.open("/presc.bin", flags))??;
   // … later …
   // Event::Fs(FsEvent::OpenResponse { tan, result: Ok(handle) })

From concept to code

What counts as malformed

Narrower than it looks. §4.9 scopes the malformed-request error to one thing:

“The file server shall respond with Error Code 47 Malformed Request, if it receives a message, which is shorter than expected.”

Length — not a surprising flag value. The volume flags (B.29) and volume mode (B.30) each describe their spare bits as “Reserved, send as 000000”, which binds the sender; nothing licenses a server to refuse a request over one. Refusing would also mean a later revision that defines one of those bits gets turned away rather than ignored, against the general rule that undefined bits are “received as ‘don’t care’”. machbus therefore masks them on receive while still refusing to transmit them set.

Failure modes worth knowing

• TAN confusion — matching a response to the wrong request if TANs are not tracked.
• Not connected — issuing file ops before the CCM handshake completes.
• Big transfers — large reads/writes ride the transport protocol and inherit its timeout/abort behavior.

See also

• ISO 11783-3 — data link & transport — what carries the big reads and writes.
• Implement control, the tractor ECU, and the rest.

ISO 11783-14 — sequence control

Part 14 automates sequences of actions. Its most familiar face is headland management: at the end of a pass, the machine raises the hitch, folds a marker, disengages sections, and lifts the implement — in a defined order, from one operator action or a position trigger. Sequence Control is the protocol that coordinates that.

Why this exists

Turning at the headland is a choreography of half a dozen actuator actions that must happen in the right order every time. Doing it by hand, every pass, is tiring and error-prone. Sequence Control lets the machine record the choreography once and replay it reliably, with each participating ECU executing the steps it owns.

Master and client

   MASTER (runs the saved sequence)            CLIENTS (execute their steps)
     │ ── start sequence ──────────────────►  (all)
     │ ── step 3: "raise rear hitch" ──────►  hitch ECU executes
     │ ◄── step 3 complete ─────────────────  hitch ECU reports
     │ ── step 4: "disengage section bank" ►  section ECU executes
     │ ◄── step 4 complete ─────────────────
     │     … pause / resume / abort as needed …
     │ ── sequence complete ───────────────►

The master drives ordering and timeouts; each client executes the steps addressed to it and reports progress. The protocol carries pause, resume, and abort so a sequence can be interrupted safely.

How machbus expresses it

machbus implements both roles: ScMaster runs and broadcasts the sequence; ScClient executes steps and reports completion. Both surface their lifecycle as ScEvent variants (state changes, step started/completed, sequence complete, timeout, pause/resume/abort).

   ctrl.with_mut::<ScMaster, _>(|m| { m.add_step(step)?; m.start() })?;
   // progress arrives as Event::Sc(ScEvent::MasterStepCompleted { step_id }) …

From concept to code

Failure modes worth knowing

• Step never completes — a client that cannot perform a step must report, or the master times out; do not hang the sequence.
• Unsafe abort — aborting mid-sequence must leave the machine in a safe state, not half-folded.
• Ordering assumptions — steps run in the master’s order; clients should not reorder.

See also

• TIM (AEF) — the authority model often paired with automated motion.
• Implement control, the tractor ECU, and the rest.

TIM — Tractor Implement Management (AEF)

TIM lets an implement command the tractor — adjust speed, work the hitch, spin the PTO — so the implement can optimize the whole operation rather than just react to it. That is powerful and dangerous, so TIM is built around authority with safety interlocks. It is an AEF-driven capability layered on the ISO messages.

Why this exists

Often the implement knows best. A baler knows when to slow the tractor for a dense windrow; a precision planter knows when to lift. Letting the implement make those adjustments directly is more accurate and less tiring than the operator relaying them. But handing a stranger’s box control of a moving tractor demands a hard safety model — hence authority that must be explicitly granted and can be revoked the instant an interlock trips.

The authority handshake

   IMPLEMENT ── request authority over {rear hitch, rear PTO} ──►  TRACTOR
             ◄── grant (only if interlocks are clear) ──────────
   IMPLEMENT ── command: rear PTO engage CW ──►  (allowed only while granted)
             ◄── status: PTO engaged ──────────
                 …
             ── any interlock trips → authority revoked → further commands refused

The guard is the whole point: a guarded command is refused before any frame goes on the wire unless authority is currently granted and the local interlocks are clear. A revoked grant immediately blocks subsequent commands.

How machbus expresses it

The Tim plugin is a local authority/interlock guard plus the guarded command helpers and the decoded PTO/hitch/aux status stream:

   ctrl.with_mut::<Tim, _>(|t| {
       t.request_authority(options)?;     // ask
       t.grant_authority()?;              // (tractor side) grant if interlocks clear
       t.command_pto_engage(Pto::Rear, true)   // refused unless granted + clear
   });
   // a blocked command surfaces as Event::Tim(TimEvent::CommandBlocked { .. })
   // an interlock change surfaces as Event::Tim(TimEvent::AuthorityStateChanged(..))

set_interlocks updates the local safety state; if it revokes authority, the change is reported and further guarded commands fail until authority is re-granted.

Certification

TIM is defined and certified by AEF. machbus ships the mechanism — the authority guard, the guarded commands, the status decoding — but no certification. Shipping a TIM-capable product to market is a separate AEF process; see Conformity first.

From concept to code

Failure modes worth knowing

• Commanding without authority — refused by design; check the grant first.
• Ignoring revocation — an interlock can revoke mid-operation; watch for the authority-state event and stop commanding.
• Treating the mechanism as certification — it is not.

See also

• ISO 11783-9 — the tractor ECU — the facilities TIM borrows.
• ISO 11783-14 — sequence control — automated motion that often pairs with TIM.

Automatic guidance

The first question everyone asks about ISOBUS guidance is: do I send points, angles, or velocities? The answer is none of those — you send a desired path curvature.

One capability, several names. Automatic guidance, agricultural guidance and autosteer all mean the same thing: this page. ISO 11783-7 calls the messages “Agricultural Guidance System Command” and “Agricultural Guidance Machine Info”; “autosteer” is the colloquial name for using them. There is no separate autosteer facility, message or plugin.

In machbus one plugin speaks these messages: AutoDrive, which carries steering and speed behind a single engage lifecycle.

Everything else you may see is supporting code, not another concept: isobus::implement::guidance is the wire codecs, geo::guidance is pure path-to-curvature maths, and machbus drive is a tool subcommand that drives a plugin.

Points vs. angles vs. curvature

Three things you might imagine sending to make a tractor steer itself, and why only one of them is right:

• Not waypoints. You do not stream a list of latitude/longitude points and let the tractor figure out the geometry. The bus has no message for “drive to these coordinates.”
• Not a raw steering angle. You do not command the wheels directly to N degrees. The right wheel angle depends on the machine’s geometry and changes with speed; an angle that holds a line at 4 km/h would oversteer at 12 km/h.
• Curvature. You send the desired curvature of the path: how tightly the machine should be turning, expressed in 1/km — the inverse of the turn radius. Zero curvature is dead straight. A larger magnitude is a tighter turn, and the sign tells the steering which way to turn. A 50 m radius is 1000 / 50 = 20 1/km.

Curvature is the natural interface because it is independent of speed and of the machine’s steering linkage. The tractor’s steering ECU takes the commanded curvature and closes the loop on its own wheels — it owns the actuator, the mechanical limits, and the speed-dependent geometry. The guidance controller only has to say how hard to turn, not how to move the wheels.

Speed is a separate concern. A curvature command says nothing about how fast the machine travels. The tractor owns its speed. Keep the two ideas apart: guidance is geometry, not throttle.

If you also want to influence speed, there are two different facilities, and they are not interchangeable:

• Machine Selected Speed Command (PGN 0xFD43) — the ISO 11783-7 message, sent as a plain broadcast with no authority handshake. This is what the AutoDrive plugin uses alongside the curvature command.
• TIM — a separate protocol on its own PGNs, where speed is a function that must be explicitly assigned and authenticated before you may command it.

Which one a given tractor acts on is a property of that tractor. An AEF-certified machine will generally guard speed behind TIM; a retrofit or bench system will generally take the native message. See AutoDrive → Do I need TIM? for the full comparison.

Turning a path into curvature is the application’s job. Each control cycle, something has to look at the planned line, the current GNSS position and heading, and the cross-track error, then compute the single curvature value that steers the machine back onto the line. That control law — a pure-pursuit or Stanley tracker, typically — lives in your application. machbus does not plan paths or run the tracker; it carries the resulting curvature command onto the wire and decodes what comes back.

Thinking in (v, ω): the robotics twist

If you come from mobile robotics, you command a body with a twist: a linear velocity v and an angular (yaw) velocity ω. Curvature is not a rejection of that model — it is that model with the speed factored out:

κ = ω / v

A robot uses (v, ω) because one controller owns both steering and throttle. ISOBUS deliberately splits them: the guidance message carries only the speed-independent geometry (curvature), because on a tractor the steering authority and the speed authority are usually different systems — and the operator often keeps speed. Dividing ω by v is exactly what removes the speed dependence: a 50 m circle stays a 50 m circle whether you crawl or fly. (This is also why a raw yaw rate ω alone would be the wrong thing to send — the same ω is a different arc at every speed.)

You can still command in twist terms when it is convenient. machbus’s (v, ω) call computes κ = ω / v and sends it as the Guidance System Command (PGN 0xAD00), and also sends v as a Machine Selected Speed Command (PGN 0xFD43) — so the two separate authorities each receive the message they expect, from one call. A near-zero v cannot define a forward path curvature, so it commands straight. See the Guidance tutorial.

The two messages

Guidance is a two-way conversation between the guidance controller (the thing deciding where to go) and the tractor’s steering ECU (the thing that moves the wheels). Two messages carry it, each in one direction.

   guidance controller                         steering ECU (tractor)
   (your app: path + GNSS → curvature)          (actuator + safety logic)
        │                                                │
        │   Guidance System Command (PGN 0xAD00)         │
        │   commanded curvature + intent to steer  ───►  │  inside limits?
        │                                                │  engaged / allowed?
        │                                                │
        │ ◄─── Agricultural Guidance Machine Info        │
        │      (PGN 0xAC00): estimated curvature,        │
        │      steering readiness, limit status          │
        ▼                                                ▼
   adjust the request next cycle              steer, refuse, or drop out

Guidance System Command — PGN 0xAD00

Direction: guidance controller → tractor. This is the command. It carries the commanded curvature plus a small readiness/intent signal that says whether the controller actually wants to steer right now, or is merely reporting a curvature without asking to take the wheel. A curvature number on its own is never a request to steer — the intent flag is the engage signal. The controller resends this message on a fixed cadence; it is a heartbeat, not a one-shot.

Agricultural Guidance Machine Info — PGN 0xAC00

Direction: steering ECU → bus. This is the feedback. The steering system broadcasts:

• its estimated actual curvature — what the wheels are really producing now, which is not always what you asked for;
• its steering-system readiness — whether the system is engaged and in a state that allows an external command to steer it;
• a guidance limit status — whether the command is being clamped, the system is at a limit, or there is a fault.

You command through 0xAD00 and you always verify through 0xAC00. Never assume the machine reached the curvature you requested — read back the estimated curvature.

What each signal means, in plain terms

Two messages, a handful of fields. Here is what each field is actually telling you — no jargon.

On the command (PGN 0xAD00), controller → tractor:

On the feedback (PGN 0xAC00), tractor → bus. The steering ECU broadcasts this every 100 ms the whole time it is powered. Seeing this message on the bus at all is the first signal that the ECU can be steered. Inside it:

is_steering_ready() is exactly the “Steering System Readiness State == on/active” check. For everything else, read the full record with latest_machine_info().

When it refuses: the exit / reason code

When the steering ECU will not — or will no longer — accept your commands, it says why in the exit/reason code. The reasons a real system reports (from the AEF automation guideline’s external-guidance table) include:

• required level of operator presence/awareness not detected
• operator override of function — someone touched the wheel
• operator control not in a valid position
• remote command timeout — your command heartbeat stalled
• remote command out of range / invalid
• system not calibrated
• alternate guidance system active
• vehicle speed too high / too low
• transmission gear does not allow remote commands (park, etc.)

Treat any non-clear reason as “stop asserting intent and tell the operator,” not as something to retry blindly.

The lifecycle: when each thing happens

Read the two messages in order and a normal engage → steer → release cycle looks like this:

1. Power on. The steering ECU starts broadcasting Agricultural Guidance Machine Info (0xAC00) at 100 ms with readiness = not ready. Its mere presence tells your controller the machine is steerable. A deeper, up-front capability check is the ISO 11783-9 tractor-facilities advertisement, which you can read before any guidance traffic to know the tractor supports being steered at all.
2. Operator arms it. The person in the seat flips the remote-engage switch (or holds the button). Remote Engage Switch Status goes on, and the system moves toward ready. Until this happens, nothing your code sends will steer.
3. Controller asks for the wheel. Your app calls engage() and starts sending the Guidance System Command (0xAD00) carrying the curvature and Curvature Command Status = intended to steer, on a fixed ~100 ms heartbeat.
4. System engages. With the operator armed, no lockout, speed in range, and the command stream alive, the steering ECU engages: readiness reports on/active and the estimated curvature begins tracking your command.
5. Steady state. Every cycle you recompute a curvature from your path + GNSS and resend it, and you read back readiness, limit status, and estimated curvature to confirm the machine is actually following.
6. Drop out. The instant the operator touches the wheel — or speed leaves the window, or your heartbeat stalls — the system leaves automatic mode, readiness drops to not ready, and the exit/reason code says why. Your controller must disengage() and stop asserting intent at once. It does not fight the operator.
7. Release. When you are done, call disengage(): the next command goes out with not intended to steer, and the operator has the wheel back.

The rule under all of it: the steering ECU is the authority on its own safety. Your controller asks, the tractor decides, and a dropout is honoured immediately — every cycle.

Two layers of “is it allowed?”

The fields above are the raw ISO 11783-7 handshake. On top of them sits the AEF TIM / automation layer, which treats steering as an authority-controlled automated function: authority to steer must be granted, and it comes with the same operator-override interlocks formalised as part of the automation contract. Both layers say the same thing — the operator and the tractor stay in charge — at different levels of formality. See TIM for how that authority is granted and revoked.

machbus is not a safety system

machbus encodes and decodes these messages. It does not plan paths, does not close the steering loop, does not supervise the operator, and carries no ISO/SAE/AEF certification. Nothing here makes a machine safe for unattended steering. Real deployment needs official standards, functional-safety engineering, qualified hardware, and interoperability evidence this crate does not provide.

From concept to code

The session::plugins::AutoDrive plugin is the whole surface: arm and engage (assert intent to steer), disengage, command a curvature and optionally a speed, and read back the steering system’s estimated curvature, readiness and limit status. It is also exposed in the C and Python bindings (session-level autodrive_* functions/methods, behind an enable_autodrive flag).

See also

• AutoDrive tutorial — the plugin, end to end.
• ISO 11783-9 — the tractor ECU — what the tractor advertises.
• TIM (AEF) — steering under granted authority.
• Positioning: NMEA and GNSS — where the position and heading that feed your path tracker come from.

Positioning: NMEA and GNSS

Guidance, section control, and TC-GEO all need one thing the rest of ISOBUS does not provide: an accurate, fresh answer to “where am I, which way am I pointed, and how fast am I going?” That answer comes from a GNSS receiver, and on a modern machine it usually arrives over NMEA 2000 — a CAN-based standard that is a cousin, not a child, of ISOBUS. This chapter explains how the fix gets onto the bus and into a prescription.

Why this is a separate world

ISO 11783 is about machine control; positioning is a measurement domain with its own committee, its own message catalog, and its own history (the older serial NMEA 0183 sentences and the CAN-based NMEA 2000). Rather than reinvent it, ISOBUS machines simply carry NMEA 2000 traffic on the same wire and let agricultural software consume it. machbus treats positioning as a first-class but bounded subset: it decodes the PGNs guidance and TC-GEO actually need.

   GNSS receiver ──(NMEA 2000 PGNs)──► bus ──► guidance / TC-GEO / logging
        │                                            │
        position, COG/SOG, heading, attitude,        turns a fix + a map into
        dilution-of-precision, system time           per-section setpoints

What a fix actually contains

A position is more than a latitude/longitude pair. The signals that matter for agriculture, each its own NMEA 2000 PGN that machbus decodes:

The recurring theme: a raw lat/lon is not enough. Accurate section control needs heading and attitude (the GNSS antenna is not at ground level, and a tilted machine projects its position sideways), and the DOP values tell the software when the fix is too poor to act on.

Fast Packet: the right-sized transport

A full GNSS position record does not fit in 8 bytes, but it is far smaller than an object pool. NMEA 2000 uses Fast Packet — a lightweight multi-frame scheme — for these modest records, rather than the heavier ISOBUS Transport Protocol. machbus’s network layer reassembles Fast Packet PGNs (the GNSS position-data message among them) so the decoder sees a complete record.

   Fast Packet:  frame 0 (header + first bytes) · frame 1 · frame 2 …
                 → reassembled into one GNSS position record → decoded

NMEA 0183, briefly

Some receivers still speak the older serial NMEA 0183 — comma-separated ASCII sentences (GGA, RMC, VTG, …) over a UART rather than CAN. machbus can parse these too, which is useful for bench setups and simpler receivers. The two worlds carry the same underlying information in very different envelopes; machbus normalizes both into the same position types.

From a fix to a setpoint

The payoff is the loop that closes guidance and variable-rate work:

   NMEA fix (lat/lon, heading, attitude, quality)
        │  normalize, check quality (DOP)
        ▼
   machine ground position (antenna offset + tilt corrected)
        │  +  DDOP geometry (section offsets, working width)
        │  +  prescription map
        ▼
   per-section coverage + setpoint rates          (TC-GEO)
        │
        ▼
   process data DOWN to the implement  ·  as-applied logged UP

This is why the positioning chapter sits next to the Task Controller: the fix is an input to TC-GEO, and the DDOP geometry is what turns “the machine is here” into “boom section 7 is over this square metre.”

Doing it with machbus

On the session facade, plug Gnss. It decodes the NMEA 2000 GNSS/navigation PGNs into cached state plus GnssEvents, and can broadcast a few of them:

   Session::builder(name, addr)
       .plug(Gnss::new(NMEAConfig::default().with_all(true)))
       .spawn(transport)
              │
              ▼  driver.poll()
       inbound NMEA PGNs → Event::Gnss(GnssEvent::Position / Cog / Sog / …)
       cached fix available via get::<Gnss>().latest_position()

The hands-on paths are NMEA 2000 and Serial GNSS.

From concept to code

Scope and honesty

machbus implements the GNSS/navigation PGNs that agricultural guidance and TC-GEO need, decoded and tested locally; it is deliberately a subset of the full NMEA 2000 catalog (it is not a marine chartplotter). It does not provide RTK correction, a positioning engine, or certified positioning accuracy — that is the receiver’s job. What machbus guarantees is faithful decoding of the records the receiver puts on the bus.

Failure modes worth knowing

• Trusting a bad fix — acting on a position without checking DOP/quality leads to misapplied product; gate work on fix quality.
• Ignoring attitude — on slopes, an uncorrected antenna position is metres off at ground level.
• COG ≠ heading — at low speed, course-over-ground is noisy; heading is the reliable signal for orientation.
• Stale fix — if the receiver drops out, the last position must be treated as stale, not current.

See also

• The Task Controller and the data dictionary — where the fix becomes a setpoint.
• The networking foundation — Fast Packet and the transport family.
• Guidance — steering and curvature on top of the fix.

Decode without ISOBUS

machbus is best known as an ISOBUS stack. But underneath the session facade, the implement personas, and the Virtual Terminal client, there is a smaller, sharper tool: a CAN / J1939 / NMEA 2000 decoder. You can use it on its own.

This is deliberate. Most of the value of being on an agricultural bus is simply understanding what is on it. A tractor, a GNSS receiver, an engine ECU, and a planter all chatter constantly. Before you ever claim an address or send a command, you usually want to listen — to take a raw 29-bit identifier and eight bytes of payload and turn it into something you can reason about: “engine speed, 1450 rpm, from source 0x00.”

machbus exposes exactly that capability as three standalone public modules. You do not need to start a session, claim an address, or run a network manager to use them.

The three public modules

   machbus
   ├── net      ── CAN frames, identifiers, PGNs, the wire layer
   ├── j1939    ── SAE J1939 PGN codecs (engine, diagnostics, …)
   └── nmea     ── NMEA 2000 PGN codecs + an NMEA 0183 serial parser

machbus::net — the wire layer

This is the foundation. It knows nothing about the meaning of a message — only its shape on the bus. Here you find:

• Identifier — the 29-bit extended CAN identifier, with structured accessors for priority, PGN, source address, and destination. It does the PDU1/PDU2 arithmetic for you (more on that trap in the next page).
• Message — an identifier paired with up to eight data bytes; the unit a node actually sends and receives.
• Pgn and the PGN helpers — the Parameter Group Number, plus utilities to extract the PF/PS fields, decide whether a PGN is broadcast, and look up known PGNs.

If all you want is to read a candump line and answer “who sent this, to whom, at what priority, and which parameter group is it?”, net alone is enough.

machbus::j1939 — named messages

net gives you a PGN number. j1939 tells you what that number means. It is a collection of wire codecs, one family per concern: engine controllers, fuel and temperature, hours, transmission, speed and distance, the whole diagnostic “DM” family, acknowledgements, requests, and proprietary messages. Each codec takes the raw bytes for its PGN and produces a typed Rust struct with named, scaled fields.

machbus::nmea — positioning and the marine heritage

NMEA 2000 rides on the same 29-bit CAN bus as J1939 and ISOBUS. In agriculture it is how GNSS receivers, compasses, and weather sensors report position, heading, course, and environment. The nmea module decodes a focused subset of N2K PGNs through its NMEAInterface, handles the N2K network-management PGNs, and — as a bonus — ships an NMEA 0183 parser for the older serial-text sentences a GNSS puck might emit over a UART.

The decode pipeline as a mental model

Every decode, no matter the protocol, follows the same four steps. Hold this picture in your head and the rest of these pages will slot into place.

   ┌──────────────────────────────────────────────────────────────┐
   │  1. RAW FRAME                                                  │
   │     29-bit identifier  +  0–8 data bytes                       │
   │     e.g.  0x0CF00400   [ FF FF 68 13 FF FF FF FF ]            │
   └───────────────────────────┬──────────────────────────────────┘
                               │  net::Identifier::from_raw(...)
                               ▼
   ┌──────────────────────────────────────────────────────────────┐
   │  2. STRUCTURED IDENTIFIER                                      │
   │     priority = 3   PGN = 0xF004   source = 0x00   dst = global │
   │     "broadcast, electronic engine controller #1"              │
   └───────────────────────────┬──────────────────────────────────┘
                               │  match on the PGN
                               ▼
   ┌──────────────────────────────────────────────────────────────┐
   │  3. PICK THE CODEC FOR THAT PGN                               │
   │     PGN 0xF004 → j1939 EEC1 codec                            │
   │     PGN 129025 → nmea rapid-position codec                   │
   └───────────────────────────┬──────────────────────────────────┘
                               │  decode the data bytes
                               ▼
   ┌──────────────────────────────────────────────────────────────┐
   │  4. TYPED STRUCT                                              │
   │     Eec1 { engine_speed: 620.0 rpm, … }                       │
   └──────────────────────────────────────────────────────────────┘

Read it left to right:

1. Raw frame. Whatever your CAN driver hands you: an identifier and a byte slice. This is the same shape whether the frame is J1939, NMEA 2000, or plain ISOBUS — they all share the 29-bit CAN format.
2. Structured identifier. net::Identifier cracks the 29 bits into priority, PGN, source, and destination. This step is protocol-agnostic; it is pure bit arithmetic.
3. Pick the codec. The PGN is the routing key. You look at it and decide which decoder applies — a J1939 engine codec, an NMEA navigation codec, or none (an unknown or proprietary PGN you choose to ignore).
4. Typed struct. The chosen codec interprets the data bytes — applying scale factors, offsets, bit masks, and “not available” sentinels — and gives you a struct with real units.

The crucial insight: steps 1–2 are universal, steps 3–4 are protocol-specific. That is exactly why machbus splits net (universal) from j1939 and nmea (specific).

A note on multi-frame messages

Step 1 above assumes one frame carries one whole message. Often it does — most J1939 and N2K signals fit in eight bytes. But some messages are larger: a long diagnostic list, a detailed GNSS fix with every satellite. Those are split across many frames and reassembled by a transport protocol (J1939 TP/BAM/ETP) or Fast Packet (NMEA 2000).

For the basics, treat reassembly as a black box that sits between steps 1 and 2: many frames go in, one logical payload comes out, and from there the pipeline is unchanged. The J1939 and NMEA 2000 pages explain how those mechanisms work conceptually.

When to use this vs the full session facade

Reach for the decode modules when you want to observe the bus:

• You have a candump trace, a log file, or a live socket and you want to know what is on it.
• You are building a dashboard, a logger, a black-box recorder, or a diagnostics viewer.
• You only care about reading engine, GNSS, or diagnostic data — you are not a participant, just a listener.
• You want a tiny dependency: no address claiming, no network manager, no timers.

Reach for the session facade when you want to participate:

• You need a claimed address and a NAME on the network.
• You must respond to requests, send acknowledgements, or run a Virtual Terminal or Task Controller client.
• You need the network manager to track partners, handle address conflicts, and run transport sessions for you.

A good rule of thumb: if you are read-only, stay in net / j1939 / nmea. The moment you need to talk back in a way the network must track, move up to the session facade.

Where to go next

Three conceptual pages build the picture from the bottom up:

• Anatomy of a CAN frame — the bus, the 29-bit identifier, and the PDU1/PDU2 split that trips up everyone.
• J1939 messages and PGNs — from frames to named messages, the transport protocols, the DM diagnostic family, and what j1939 decodes.
• NMEA 2000 on the bus — how N2K reuses J1939, Fast Packet, the GNSS PGNs, and what nmea decodes.

Then three hands-on tutorials show the actual code:

• Tutorial: inspect CAN identifiers
• Tutorial: decode J1939 PGNs
• Tutorial: decode NMEA 2000

For the deep theory behind the wire — why the identifier looks the way it does, how address claiming works, how transport is specified — see the standards section, in particular SAE J1939: the heritage and Positioning: NMEA and GNSS.

Anatomy of a CAN frame

Everything on an agricultural bus — J1939 engine data, NMEA 2000 position, ISOBUS commands — is, at the very bottom, a CAN frame. If you understand the frame, you understand the substrate that all three protocols share. This page builds that picture from the wire up, and ends with the single detail that confuses every newcomer: the PDU1/PDU2 split.

You will use machbus::net to work at this layer. Its Identifier type is the structured form of what this page describes.

The bus

CAN — Controller Area Network — is a two-wire, multi-drop, broadcast bus. Every node is wired to the same pair of differential wires (CAN-H and CAN-L), terminated at both ends.

        ┌──────┐    ┌──────┐    ┌──────┐    ┌──────┐
        │ ECU  │    │ GNSS │    │ Term │    │ Disp │
        │  A   │    │      │    │ inal │    │ lay  │
        └──┬───┘    └──┬───┘    └──┬───┘    └──┬───┘
   120Ω    │           │           │           │   120Ω
   ──┳━━━━━┷━━━━━━━━━━━┷━━━━━━━━━━━┷━━━━━━━━━━━┷━━━━┳──  CAN-H
     ┃                                              ┃
   ──┻━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┻──  CAN-L

Two consequences shape everything else:

• There are no addresses on the wire. Every node hears every frame. Filtering by who-is-it-for happens in software, above CAN. This is why a decoder can simply listen and see the whole bus.
• Frames carry an identifier, not a destination. The identifier names the message, and arbitration uses it to decide who transmits when two nodes start at once. A lower numeric identifier wins; the loser backs off and retries. This is how “priority” gets baked into the identifier — lower value, higher priority.

Two identifier sizes: 11-bit vs 29-bit

CAN comes in two flavours of identifier:

An 11-bit identifier gives you 2048 possible message IDs — fine for a small closed system. Agriculture and heavy vehicles need far more structure than that: a priority, a message identity, and the address of the sender, all packed into the identifier itself. Eleven bits cannot hold all of it.

So agriculture uses 29-bit (extended) identifiers. The extra 18 bits are exactly what lets J1939 — and therefore ISOBUS and NMEA 2000 — carry priority, a Parameter Group Number, and a source address in every single frame. When you see a 29-bit ID on a farm bus, it is almost certainly one of these three protocols, all of which share the same layout.

The 29-bit identifier layout

Here is the layout J1939 defined and ISOBUS and NMEA 2000 inherited. Bit 28 is the most significant.

   bit  28      26 25  24 23           16 15            8 7             0
        ┌─────────┬───┬───┬───────────────┬───────────────┬─────────────┐
        │ priority│EDP│ DP│   PF          │   PS          │  source     │
        │ 3 bits  │ 1 │ 1 │  PDU format   │ PDU specific  │  address    │
        │         │   │   │  8 bits       │ 8 bits        │  8 bits      │
        └─────────┴───┴───┴───────────────┴───────────────┴─────────────┘
         \_______/ \_____________________________________/ \___________/
          priority            the PGN lives here              who sent it

Field by field:

• Priority (3 bits). 0–7. Lower wins arbitration. Safety-critical messages get low numbers; routine status gets higher ones. A common default is 6.
• EDP — Extended Data Page (1 bit). Selects which PGN page the message lives on. J1939/ISOBUS messages use EDP = 0. NMEA 2000 also lives in the standard pages. EDP = 1 is reserved for other ISO 15765 uses.
• DP — Data Page (1 bit). A second page-selector bit. Together EDP and DP extend the PGN number space.
• PF — PDU Format (8 bits). The high byte of the message identity. Its value decides whether the frame is point-to-point or broadcast (see below).
• PS — PDU Specific (8 bits). The low byte. Its meaning depends on PF — it is either a destination address or part of the message identity. This is the trap.
• Source address (8 bits). Who sent the frame. 0–253 are real node addresses, 254 is the null address (used during address claiming), and 255 is the global/broadcast address.

The middle 18 bits — EDP, DP, PF, and (sometimes) PS — together form the PGN, the Parameter Group Number that names the message. The next page is all about PGNs.

net::Identifier gives you each of these directly: priority(), pdu_format(), pdu_specific(), source(), data_page(), extended_data_page(), plus the derived pgn(), destination(), and is_broadcast().

The data field: DLC and up to 8 bytes

After the identifier comes the payload. Classic CAN frames carry a DLC (Data Length Code) and 0 to 8 data bytes.

   ┌──────────────────────┬─────┬───────────────────────────────┐
   │  29-bit identifier   │ DLC │  data: 0–8 bytes              │
   └──────────────────────┴─────┴───────────────────────────────┘
                                  └ byte 0 … byte 7 ┘

Eight bytes is a hard ceiling for classic CAN. That single constraint explains a huge amount of how J1939 and NMEA 2000 are designed:

• Signals are packed tightly — a field might be one byte, or two bytes little-endian, or even a handful of bits — to fit the budget.
• Anything larger than eight bytes must be split across multiple frames and reassembled. That is what transport protocols (J1939 TP/BAM/ETP) and Fast Packet (NMEA 2000) exist to do. Each gets covered on its protocol’s page.

Two more details worth knowing as a decoder:

• Byte order is little-endian. Multi-byte signals put the least-significant byte first. A two-byte value in bytes 3–4 is byte3 + (byte4 << 8).
• 0xFF means “not available.” A byte (or all bytes of a signal) set to all-ones is the standard “no data” sentinel. A scaled signal reading its maximum raw value almost always means the sensor has nothing to report, not a real reading. Treat these as missing, never as data.

Bit timing and bus speed (briefly)

You rarely touch this as a decoder, but it is worth one paragraph.

The ISOBUS / NMEA 2000 baseline runs at 250 kbit/s. Every node on the segment must agree on this rate, or nothing communicates. The bit rate is built from a nominal bit time divided into time quanta, with a sample point typically placed around 75–87% of the bit. The sample point and synchronization-jump-width let nodes stay in lock-step despite clock drift and propagation delay along the cable. J1939 buses also commonly run at 250 kbit/s, with some segments at 500 kbit/s.

The practical takeaway: if you are capturing a farm bus, configure your interface for 250 kbit/s, extended (29-bit) identifiers, and you will see the traffic. The deeper electrical and timing rules live in ISO 11783-2: the physical layer.

The PDU1 vs PDU2 split — read this twice

This is the one rule that catches everyone. The meaning of the PS byte — and therefore how you compute the PGN and the destination — depends entirely on the PF byte.

   ┌─────────────────────────────────────────────────────────────┐
   │  if  PF < 240   →   PDU1   (point-to-point)                  │
   │                                                              │
   │      PS = DESTINATION ADDRESS                                │
   │      "send PGN <PF·00> to node <PS>"                         │
   │      the PGN's low byte is forced to 0                       │
   │                                                              │
   │  if  PF ≥ 240   →   PDU2   (broadcast)                       │
   │                                                              │
   │      PS = GROUP EXTENSION (part of the PGN)                  │
   │      "broadcast PGN <PF·PS> to everyone"                     │
   │      there is no destination — it is for all                 │
   └─────────────────────────────────────────────────────────────┘

Why it matters: the same 8-bit PS field is a destination in one case and message identity in the other. If you blindly fold PS into the PGN, you will compute nonsense PGNs for every peer-to-peer message. If you blindly read PS as a destination, you will think broadcast messages are addressed to phantom nodes.

PDU1 example — a request to one node

   identifier bytes (PF=0xEA, the Request PGN):
        prio  EDP/DP   PF=0xEA   PS=0x26   src=0x80
                                  └ destination! ─┘

   → PGN  = 0xEA00   (PS is NOT part of it; low byte is 0)
   → dest = 0x26     (the PS byte)
   → "address 0x80 is requesting something from address 0x26"

PDU2 example — a broadcast signal

   identifier bytes (PF=0xF0, an engine controller PGN):
        prio  EDP/DP   PF=0xF0   PS=0x04   src=0x00
                                  └ group extension ┘

   → PGN  = 0xF004   (PS IS part of it)
   → dest = global   (broadcast, no specific node)
   → "address 0x00 is broadcasting EEC1 to everyone"

The mechanics in one table

net::Identifier implements all of this for you. is_pdu2() returns true when PF ≥ 240; pgn() folds PS in only for PDU2; destination() returns the PS value for PDU1 and the broadcast address for PDU2. You never have to do the masking by hand — but you must understand why the same bits decode two different ways, because the trap reappears the moment you read a raw trace without the helper.

Putting it together: reading one frame

Take a single candump-style line: an identifier and some bytes. To decode it as a human:

1. Split the 29 bits into priority, EDP/DP, PF, PS, source.
2. Look at PF. Is it < 240 (PDU1, point-to-point) or ≥ 240 (PDU2, broadcast)?
3. Compute the PGN accordingly, and the destination accordingly.
4. Now you have the routing key (PGN) and can hand off to a J1939 or NMEA codec.

That hand-off — PGN to named message — is the subject of the next two pages.

Cross-links

• ISO 11783-2: the physical layer — the electrical bus, termination, bit timing, and 250 kbit/s in depth.
• SAE J1939: the heritage — where the 29-bit identifier and the PDU1/PDU2 split came from, and what ISOBUS added.

J1939 messages and PGNs

The previous page took a raw 29-bit frame and cracked it into priority, PGN, source, and destination. The PGN is the routing key. This page is about what that key unlocks: turning a PGN into a named message with named, scaled signals — the job of the machbus::j1939 module.

SAE J1939 is the heavy-vehicle networking standard that ISOBUS was built on. The engine, transmission, and diagnostic messages an agricultural bus carries are, overwhelmingly, J1939 messages. Decode them and you can read a tractor’s powertrain without ever joining the network.

PGNs name the message; SPNs name the signal

Two acronyms carry the whole model.

• PGN — Parameter Group Number. A number that identifies a group of related parameters — one message type. “Electronic Engine Controller 1” is a PGN. “Engine Hours” is a PGN. The PGN is what you matched on in the identifier.
• SPN — Suspect Parameter Number. A number that identifies a single signal within (or referenced by) a PGN. “Engine speed” is an SPN. “Engine coolant temperature” is an SPN. SPNs are how individual values get named, and they matter most in diagnostics, where a fault points at a specific SPN.

   PGN  0xF004  "Electronic Engine Controller 1"   ← one message
     ├── SPN 190  engine speed          (2 bytes, 0.125 rpm/bit)
     ├── SPN 513  actual torque         (1 byte,  1 %/bit, -125 offset)
     ├── SPN 512  driver demand torque  (1 byte,  …)
     └── …

A J1939 codec’s whole job is this mapping: given the PGN’s data bytes, pull out each SPN at its byte/bit position, apply its scale and offset, honour the not-available sentinel, and hand you a typed value in real units. machbus does this inside each codec in j1939, so you receive a struct like Eec1 { engine_speed, … } rather than raw bytes.

Scaling, offset, and “not available”

Every SPN has three things you must respect:

• Resolution (scale). Raw bits times a factor. Engine speed is raw × 0.125 rpm.
• Offset. Added after scaling. A percent-torque signal might be raw × 1 − 125, letting one byte cover −125% to +130%.
• Not-available sentinel. The top of the raw range (all-ones) means “no reading.” A two-byte signal of 0xFFFF is missing, not 8191.875 rpm.

Get any of these wrong and your decode is silently, plausibly wrong — which is worse than crashing. The codecs in j1939 encode them once, correctly, so you do not re-derive them per project.

Single-frame vs multi-frame messages

Most J1939 messages fit in the eight-byte CAN payload, so the pipeline is direct: one frame in, one decoded struct out. But some messages are larger than eight bytes — a long list of active faults, a block of vehicle-identification text. Those need a transport protocol to break the payload into numbered packets and reassemble it on the far side.

J1939 defines three transport mechanisms. Conceptually:

   ┌──────────────────────────────────────────────────────────────┐
   │  TP — Transport Protocol  (up to 1785 bytes)                  │
   │                                                              │
   │   BAM  Broadcast Announce Message                            │
   │        "I'm about to send N bytes of PGN X to everyone"      │
   │        then a stream of numbered data packets. No handshake. │
   │        Best-effort, one-to-all.                              │
   │                                                              │
   │   RTS/CTS  Request-To-Send / Clear-To-Send                   │
   │        A point-to-point handshake: sender asks, receiver     │
   │        grants a window, data flows, receiver acknowledges.   │
   │        Flow-controlled, one-to-one.                          │
   └──────────────────────────────────────────────────────────────┘

   ┌──────────────────────────────────────────────────────────────┐
   │  ETP — Extended Transport Protocol  (very large transfers)   │
   │        Same idea as RTS/CTS but with a wider length field,    │
   │        for payloads beyond the TP ceiling.                    │
   └──────────────────────────────────────────────────────────────┘

How to think about it as a decoder:

• BAM is the one you will see most when listening, because it is broadcast — you can reassemble it without participating. Watch for the announce frame, collect the numbered data frames, concatenate, then decode the resulting payload as if it had arrived in one piece.
• RTS/CTS and ETP are directed and handshaked. To receive them you generally have to be a claimed participant sending CTS/acknowledgement frames — which is when you graduate from the decode modules to the session facade.

For the basics, picture transport as a black box between “many frames” and “one payload.” Once the payload is whole, the PGN-to-struct decode is identical to the single-frame case. The full handshake rules live in the standards section; see SAE J1939: the heritage.

The “DM” diagnostic family

Diagnostics deserve their own mention because they are a whole sub-language built on PGNs, and ISOBUS reuses them almost verbatim. The “DM” (Diagnostic Message) family reports faults as DTCs — Diagnostic Trouble Codes — each a bundle of an SPN (which parameter), an FMI (Failure Mode Identifier — how it failed: short, open, out-of-range, …), and an occurrence count, alongside lamp status (the warning lights).

The members you meet most:

The mental model: DM1 is the present, DM2 is the past. A diagnostics viewer listens for DM1 to show what is wrong right now, and can request DM2 to show what has been wrong. Each carries one or more DTCs you then expand into SPN + FMI + count + lamp state.

What machbus::j1939 decodes

The j1939 module ships a codec per PGN family. You match the PGN from the identifier, pick the matching codec, and get a typed struct. The table below maps the families the module covers to the kinds of PGN they decode.

A few notes on reading this table:

• EEC1 (0xF004) is the workhorse — engine speed lives here, broadcast continuously. If you decode exactly one J1939 PGN, decode this.
• The diagnostic family is the largest single codec because the DM messages are numerous and structured; it expands DTC lists into typed Dtc { spn, fmi, count } records with lamp status.
• pgn_request (0xEA00) is a PDU1 message — recall from the previous page that its PS byte is a destination, not part of the PGN. The payload then carries the PGN being requested.
• Proprietary PGNs are, by definition, manufacturer-defined; the codec gives you the raw payload and the addressing helpers so you can route them, but it cannot name the signals for you.

The decode loop in words

Putting the whole J1939 picture together, the listener’s loop is:

1. Receive a frame; build a net::Identifier.
2. If it is a transport control/data frame, feed it to reassembly; continue until a full payload is ready.
3. Take the PGN. Match it against the families above.
4. Hand the payload to the matching j1939 codec.
5. Receive a typed struct with real units; act on it (log, display, alarm).

Nothing here requires a claimed address as long as you only listen and only reassemble broadcast (BAM) transports. The moment you must request directed data or acknowledge RTS/CTS, move up to the session facade.

Cross-links

• SAE J1939: the heritage — the identifier, PGN/SPN model, the transport handshakes, and the DM family in depth.
• Anatomy of a CAN frame — the PDU1/PDU2 split you need before matching any PGN.
• NMEA 2000 on the bus — the same machinery, applied to positioning.

NMEA 2000 on the bus

If you have read the J1939 page, you already understand most of NMEA 2000. That is not an accident: NMEA 2000 is built directly on J1939. Same 29-bit CAN identifier, same 250 kbit/s wire, same PGN/source/priority model, same address-claiming mechanism. N2K took the heavy-vehicle networking stack and pointed it at the marine and positioning world — depth, heading, wind, and above all GNSS position.

In agriculture, NMEA 2000 is how the GNSS receiver, the compass, and weather sensors put their data on the bus, and it frequently shares the same physical bus as ISOBUS. So a decoder that wants position has to speak N2K. That is what machbus::nmea is for.

What N2K reuses from J1939

   ┌─────────────────────────────────────────────────────────────┐
   │              NMEA 2000  (positioning / marine)               │
   │   GNSS · heading · attitude · wind · depth · environment      │
   ├─────────────────────────────────────────────────────────────┤
   │                       SAE J1939                              │
   │   29-bit identifier · PGN/SPN · source addr · priority        │
   │   address claiming (NAME) · transport for big messages        │
   ├─────────────────────────────────────────────────────────────┤
   │                    CAN 2.0B @ 250 kbit/s                     │
   └─────────────────────────────────────────────────────────────┘

Concretely, N2K inherits:

• The identifier layout — priority, EDP/DP, PF, PS, source — decoded by the same net::Identifier. A GNSS PGN cracks open exactly like an engine PGN.
• PGNs as message identity. N2K PGNs are large numbers (129025, 127250, …) because many live in the broadcast (PDU2) range, where the PS byte folds into the PGN.
• Address claiming and NAME. N2K devices claim an address and announce a NAME just as J1939/ISOBUS nodes do. As a pure listener you ignore this; as a participant you do not.
• Little-endian byte order and not-available sentinels. Same rules: LSB first, all-ones means “no data.” A latitude of all-0xFF is no fix, not a real coordinate.

What N2K adds is mostly a different catalogue of PGNs and a different multi-frame mechanism.

Fast Packet — N2K’s multi-frame transport

J1939 carries big messages with TP/BAM/ETP. NMEA 2000 has its own scheme for the moderately-large records it sends constantly — most importantly a detailed GNSS fix that does not fit in eight bytes. That scheme is Fast Packet.

Fast Packet is lighter than full transport: no announce, no handshake. It steals a few bits at the start of the payload for sequencing, so the frames self-describe how to reassemble.

   First frame of a Fast Packet sequence
   ┌──────────┬──────────┬──────────────────────────────────────┐
   │ seq/frame│ total len│  data bytes (start of the record)     │
   │  counter │ (1 byte) │                                       │
   └──────────┴──────────┴──────────────────────────────────────┘

   Continuation frames
   ┌──────────┬─────────────────────────────────────────────────┐
   │ seq/frame│  more data bytes                                 │
   │  counter │                                                  │
   └──────────┴─────────────────────────────────────────────────┘

   counter encodes  [ sequence id | frame number ]
   → group frames by sequence id, order by frame number, drop the
     header bytes, concatenate → one whole record.

The mental model:

• The first frame carries the total byte count and the first chunk.
• Continuation frames carry an incrementing frame number within the same sequence id.
• You group by sequence id, sort by frame number, strip the counter bytes, and concatenate to recover the full record. Then you decode it like any single-frame PGN.

Because Fast Packet is broadcast and needs no handshake, a pure listener can reassemble it — exactly the property that makes N2K position decodable without joining the network.

The navigation and GNSS PGNs

This is the heart of why you would decode N2K in a field. A GNSS receiver does not send one “position” message; it spreads position, velocity, orientation, and quality across several PGNs at different rates. A decoder typically fuses them.

How to think about them together:

• 129025 (rapid position) and 129026 (rapid COG/SOG) are the fast, lightweight feeds — what a guidance controller leans on. They fit in single frames.
• 129029 (detailed GNSS) is the rich, slower record — it is a Fast Packet message because it carries altitude, fix type, satellite count, and reference-station data all at once. This is the one that needs reassembly.
• 129539 (DOPs) tells you whether to trust the fix. A great-looking latitude with a terrible HDOP is not a usable position. Always read quality alongside coordinates.
• 127250 (heading) and 127257 (attitude) come from a compass/IMU, not the GNSS engine, but a navigation consumer fuses them with position to know orientation, not just location.

machbus’s positioning layer collapses these into a coherent GNSSPosition / GNSSBatch, so you reason about “a fix” rather than five disjoint PGNs. The deeper positioning theory — datums, fix types, RTK — is in Positioning: NMEA and GNSS.

What machbus::nmea decodes

The nmea module is deliberately focused. NMEA 2000 has a large PGN catalogue; machbus decodes a selected navigation / environment / engine subset that covers what an agricultural consumer actually needs, plus the management PGNs and an NMEA 0183 parser.

The selected N2K PGN subset (via NMEAInterface)

Around two dozen PGNs, grouped by concern:

The NMEAInterface is the dispatcher: it knows which of these PGNs to recognise, runs Fast-Packet reassembly where needed, and produces the typed records.

The management PGNs

Three N2K network-management PGNs round out the picture. These are the N2K analogues of the housekeeping every J1939 network does:

The N2KManagement helper handles these: it tracks heartbeats for liveness, and collects product/config information about devices on the bus.

The NMEA 0183 serial parser

Older GNSS receivers — and many cheap GNSS pucks — do not speak N2K at all. They emit NMEA 0183: comma-separated ASCII sentences over a serial line ($GPGGA,…, $GPRMC,…, and friends), not CAN frames. It is a different physical and framing world, but the information overlaps heavily with the N2K GNSS PGNs.

nmea’s SerialGNSS parses that 0183 sentence stream into the same kind of typed position/time records, so a consumer can take GNSS from either source — a CAN-bus N2K receiver or a serial 0183 puck — and treat the result uniformly.

The event / callback decode model

A small but important conceptual point: NMEA data is a stream, not a request/response. The receiver broadcasts position several times a second whether anyone is listening or not. So the natural shape for consuming it is event-driven, not poll-driven.

   frames arrive ──► reassemble (Fast Packet) ──► decode PGN
                                                     │
                                                     ▼
                          ┌──────────────────────────────────────┐
                          │  your callback fires with a typed     │
                          │  record:  "new GNSS fix", "heading"   │
                          └──────────────────────────────────────┘

You register interest once; as frames flow, the interface reassembles, decodes, and invokes your handler with each completed record. You react to fixes as they happen rather than asking “where are we?” on a timer. This matches the pump-style architecture machbus uses throughout — you feed frames in, decoded events come out — and it is exactly the listener-friendly model that lets you read position off a shared ISOBUS/N2K bus without ever claiming an address.

Cross-links

• Positioning: NMEA and GNSS — GNSS fundamentals, fix types, datums, and how positioning fits the wider stack.
• J1939 messages and PGNs — the PGN/SPN model and transport that N2K inherits.
• Anatomy of a CAN frame — the shared 29-bit identifier and the PDU1/PDU2 split.

Tutorial: inspect CAN identifiers

Every frame on a J1939, ISOBUS, or NMEA 2000 bus carries a 29-bit extended identifier. That identifier is not an opaque number — it is a packed structure holding the message priority, the Parameter Group Number (PGN), the source address, and (sometimes) a destination address. Before you decode a single data byte you can already learn who sent the frame, who it is for, and roughly what it contains, purely from the identifier.

This tutorial walks through examples/can_inspect.rs, a tiny program that pulls a 29-bit identifier apart using nothing but [machbus::net]. There is no protocol stack here, no address claim, no session, and no IO — just bit arithmetic wrapped in a typed API. If all you want is to sniff a bus and label the traffic, this is the smallest possible starting point.

The one import you need

#![allow(unused)]
fn main() {
use machbus::net::Identifier;
}

Identifier is the typed view over a raw 29-bit CAN identifier. You build one from a u32 and then ask it questions. It owns no data buffer and performs no allocation; constructing one and reading a field is just masking and shifting, so you can call it on every frame in a high-rate capture without worrying about cost.

Decomposing one identifier

Here is the heart of the program — the describe function that takes a raw u32 and prints everything the identifier encodes:

#![allow(unused)]
fn main() {
{{#include ../../../examples/can_inspect.rs:decode}}
}

Walk through it call by call.

• Identifier::from_raw(raw) takes the raw 29-bit value as a plain u32 and wraps it. This is infallible: any u32 is a valid identifier as far as the bit layout is concerned (the upper 3 bits are simply ignored — only 29 bits are meaningful). There is no Option and no error here; the fallible step comes later when you try to decode the payload.

• id.priority() returns the message priority. Lower numbers are higher priority on the bus (priority 0 wins arbitration over priority 7). The return type is a small Priority newtype rather than a bare integer, which is why the example writes u8::from(id.priority()) to get a number it can print. Typical values you will see: 3 for fast control messages like engine speed, 6 for slower informational and network-management traffic, 2 for some high-rate NMEA 2000 navigation PGNs.

• id.pgn() returns the Parameter Group Number — the identity of the message. The PGN is what tells you “this is engine speed” versus “this is wheel speed”. The example prints it twice, once as hex (0x{:04X}) and once as decimal ({:>6}), because lookup tables in different specifications quote it in different bases.

• id.source() returns the source address: the 8-bit address of the ECU that transmitted the frame. On a live bus this is assigned dynamically through address claiming, but in the identifier itself it is always the low byte.

• id.is_pdu2() distinguishes the two addressing formats (explained in detail below). The example uses it to pick the label and to decide whether a destination address even exists.

• id.destination() returns the destination address — but only meaningful for PDU1 frames. For a PDU2 (broadcast) frame there is no destination, so the example never calls destination() in that branch; it prints ALL instead.

The samples it decodes

The program runs describe over a list of real-world 29-bit identifiers:

#![allow(unused)]
fn main() {
{{#include ../../../examples/can_inspect.rs:samples}}
}

These are not toys. 0x0CF00400 is the classic EEC1 engine-speed broadcast. 0x18EAFF00 is a PGN request sent to the global address. 0x18EEFF80 is an Address Claimed announcement. 0x09F80180 is an NMEA 2000 rapid-position frame. Each one exercises a different corner of the identifier layout, which is exactly why they make a good demonstration set.

The PDU1 / PDU2 trap

This is the single most important rule when reading CAN identifiers on these buses, and it is the one people get wrong. The relevant field inside the PGN is the PDU Format byte, conventionally called PF:

• PF < 240 → this is PDU1, a peer-to-peer format. The byte that would otherwise be part of the PGN is actually the destination address. The frame is directed at one specific ECU (or at 0xFF, the global address, meaning everyone). Use is_pdu2() → false and read destination().

• PF ≥ 240 → this is PDU2, a broadcast format. That same byte (now called the PDU Specific, PS) is part of the PGN itself, not an address. There is no destination; the frame goes to the whole bus. is_pdu2() → true, and is_broadcast() → true.

The example asserts exactly this distinction so the behaviour is pinned down in code:

#![allow(unused)]
fn main() {
{{#include ../../../examples/can_inspect.rs:pdu}}
}

Read it carefully:

• 0x18EA26EE is a PGN request. Its PF is below 240, so it is PDU1. The low byte 0x26 is therefore a destination address, and the assertions confirm is_pdu2() is false and destination() is 0x26. The request is aimed at the ECU at address 0x26.

• 0x0CF00400 is EEC1. Its PF is 0xF0 (240), which is ≥ 240, so it is PDU2. The assertions confirm is_pdu2() and is_broadcast() are both true. The 0x04 low byte is part of the PGN, not an address.

If you ever find yourself reading a destination address of “4” or “0” off a broadcast message and wondering why nobody is listening, this rule is why: you read a PGN byte as if it were an address. is_pdu2() is the guard that keeps you honest.

Run it

$ cargo run --example can_inspect

The program prints the decoded view of each sample identifier:

0x0CF00400  prio=3  PGN=0xF004 ( 61444)  src=0x00  dst=ALL   PDU2 (broadcast)
0x18EAFF00  prio=6  PGN=0xEA00 ( 59904)  src=0x00  dst=0xFF  PDU1 (peer-to-peer)
0x18EEFF80  prio=6  PGN=0xEE00 ( 60928)  src=0x80  dst=0xFF  PDU1 (peer-to-peer)
0x09F80180  prio=2  PGN=0x1F801 (129025)  src=0x80  dst=ALL   PDU2 (broadcast)

Match the output against the rule. The two EA00/EE00 lines are PDU1 (their PF is below 240), so they show a real destination byte — here 0xFF, the global address, meaning “broadcast to all” as a PDU1 message addressed to everyone, which is subtly different from a PDU2 broadcast. The F004 and 1F801 lines are PDU2, so their destination is reported as ALL and the low byte stays part of the PGN.

Note 0x09F80180 decodes to PGN 0x1F801 (129025) — a five-hex-digit PGN. That is expected: PDU2 PGNs can exceed 16 bits because the Data Page and Extended Data Page bits extend the range. NMEA 2000 lives heavily in this upper PGN space.

What to change for real bus data

This example feeds in hard-coded identifiers so the output is reproducible. To point it at a live bus, replace the samples array with identifiers you read off the wire. With SocketCAN, for instance, you would receive a frame, take its id field (the 29-bit extended identifier), and hand it straight to Identifier::from_raw. Nothing else changes — Identifier does not care where the u32 came from. Once you have the PGN you can branch to the right payload decoder, which is exactly what the next two tutorials do.

See also

• Anatomy of a CAN frame — the structure behind the identifier, in prose.
• J1939 messages and PGNs — what those PGNs actually mean.
• The networking foundation — how the addressing model fits the larger stack.
• SAE J1939: the heritage — where PDU1/PDU2 comes from.
• Tutorial: decode J1939 PGNs — the natural next step: turn the PGN you just identified into a typed struct.

Tutorial: decode J1939 PGNs

Identifying a PGN tells you what a frame is; decoding it tells you what it says. machbus ships the J1939 wire codecs as plain functions on typed structs in [machbus::j1939]. Each message group — engine controllers, diagnostics, hours meters, language preferences, and more — has a struct with three uniform operations: decode bytes into the struct, from_message decode from an assembled Message, and encode the struct back to bytes. No protocol stack, no session, no IO.

This tutorial walks through examples/j1939_decode.rs. It builds two messages — EEC1 (engine speed) and DM1 (active diagnostic trouble codes) — encodes each one, then decodes it straight back. Because every block round-trips, the output is self-validating: if the codec were wrong, the numbers coming out would not match the numbers going in.

The imports

#![allow(unused)]
fn main() {
use machbus::j1939::{DiagnosticLamps, DmDtcList, Dtc, Eec1, Fmi};
use machbus::net::Message;
}

• Eec1 is the Electronic Engine Controller 1 message (PGN 61444): engine speed, driver demand, actual torque, and so on.
• DmDtcList is the diagnostic-message DTC list — the structure behind DM1 (active faults) and its siblings.
• Dtc is a single Diagnostic Trouble Code: an SPN plus a failure mode plus an occurrence count.
• Fmi is the Failure Mode Identifier enum — the kind of fault (too high, too low, intermittent, and so on).
• DiagnosticLamps is the lamp-status block that rides along with a DM1 (malfunction lamp, warning lamp, etc.).
• Message (from machbus::net) is the assembled-message type: a PGN, a data buffer, and a source address. It is what you get after the transport layer has reassembled multi-frame traffic for you.

The codec contract

Every J1939 codec in machbus follows the same shape, and learning it once means you know all of them:

• Struct::decode(&[u8]) -> Option<Self> — parse raw payload bytes. It returns an Option because the bytes might be too short or malformed; None means “this is not a valid payload for this message”. Always handle the None case when you are reading off a real bus, where truncated and garbage frames happen.
• Struct::from_message(&Message) -> Option<Self> — the same, but starting from an assembled Message. It reads the data out of the message and runs decode on it. Use this when you already have a Message in hand.
• struct.encode() -> [u8; 8] (or -> Vec<u8> for variable-length messages) — serialize back to the wire format you would transmit.

Decoding EEC1

#![allow(unused)]
fn main() {
{{#include ../../../examples/j1939_decode.rs:eec1}}
}

Step through it:

• The Eec1 struct is built with physical, human-readable values: engine_speed_rpm: 1500.0 is RPM, driver_demand_percent: 40.0 is a percentage, and so on. You do not deal with the scaling factors and offsets the wire format uses — the codec applies them for you. source_address is the address this frame claims to come from.
• eec1.encode() returns a [u8; 8] — exactly one CAN frame’s worth of data, with each field scaled and packed into its bit positions. This is the buffer you would hand to your CAN driver to transmit.
• Eec1::decode(&bytes) parses those eight bytes back into an Eec1. Note the .expect("valid EEC1 payload"): decode returns Option<Eec1>, and the example unwraps it because it just produced the bytes itself and knows they are valid. In real code you would match or if let on the Option instead, because off-bus bytes are not guaranteed to be well-formed.
• The printout reads the decoded fields back: 1500 rpm, driver demand 40%, actual 38%. These match the input exactly, which is the round-trip proving the codec is symmetric.

Decoding from a Message

Often you do not have a bare byte slice — you have a Message that the network layer handed you. The second block decodes from one of those:

#![allow(unused)]
fn main() {
{{#include ../../../examples/j1939_decode.rs:from_message}}
}

• Message::new(61444, bytes.to_vec(), 0x00) builds a message for PGN 61444 (EEC1), carrying the bytes we just encoded, from source address 0x00. In a real reader these three pieces come off the bus, not from a local encode.
• Eec1::from_message(&msg) returns Option<Eec1>. The example uses if let Some(e) = … — this is the idiomatic way to handle the fallible decode. If the message’s PGN or payload did not match, you would simply skip it.
• The output, from_message: 1500 rpm from source 0x00, shows you can pull the source address off the Message itself (msg.source) alongside the decoded engine speed. This is the pattern you will use in a real dispatch loop: match on the PGN, call the matching from_message, and use both the decoded fields and the message metadata.

Decoding DM1 diagnostics

Diagnostics are where J1939 gets interesting, because a single DM1 can carry a list of faults and can spill across multiple CAN frames. machbus models this with DmDtcList:

#![allow(unused)]
fn main() {
{{#include ../../../examples/j1939_decode.rs:dm1}}
}

Read it field by field:

• lamps: DiagnosticLamps::default() sets all the diagnostic lamps to their default (off) state. On a real ECU these flags tell the operator whether the malfunction lamp, amber warning lamp, red stop lamp, or protect lamp is lit.
• dtcs: vec![…] is the list of active faults. Each Dtc has:
  • spn — the Suspect Parameter Number, identifying what is faulty. 110 is engine coolant temperature; 190 is engine speed.
  • fmi: Fmi::AboveNormalModerate / Fmi::BelowNormal — the Failure Mode Identifier, an enum describing the nature of the fault. AboveNormalModerate means a value is moderately too high (coolant running hot); BelowNormal means a value is too low. Because Fmi is an enum, the example can print it with {:?} and get a readable name instead of a raw number.
  • occurrence_count — how many times this fault has been seen.
• dm1.encode() returns a Vec<u8>, not a [u8; 8]. DM1 is variable-length: a few faults fit in a single frame, but more will exceed eight bytes and require the transport protocol (multi-frame). The codec produces the full logical payload; the transport layer handles the framing.
• DmDtcList::decode(&payload) parses it back, again returning an Option. The example loops over decoded.dtcs and prints each one. The two faults come back exactly as they went in.

Run it

$ cargo run --example j1939_decode

Output:

EEC1: 1500 rpm, driver demand 40%, actual 38%
from_message: 1500 rpm from source 0x00

DM1: 2 active fault(s):
  SPN 110   FMI AboveNormalModerate (count 3)
  SPN 190   FMI BelowNormal (count 1)

Every value printed is the value that was fed in, which is the whole point of a round-trip example: it proves the encode and decode paths agree.

What to change for real bus data

The example encodes its own bytes so the demo is reproducible. On a live bus you skip the encode entirely. You read a frame, build a Message from the PGN, payload, and source (or, for multi-frame messages, let the transport layer reassemble the full payload first), then call the matching from_message. The crucial difference: handle the Option. Real frames can be truncated, corrupted, or simply a different PGN than you expected, so decode and from_message will legitimately return None — treat that as “skip this frame”, not as a panic. Replace the .expect(...) you see here with an if let Some(...) or a match.

More J1939 codecs

EEC1 and DM1 are two members of much larger families. machbus provides codecs across the J1939 message groups, including:

• Engine and powertrain — engine controllers, fuel economy, hours and revolutions, temperatures and fluid levels.
• Diagnostics — the full DM family (active, previously active, and the related diagnostic messages), built on the same DmDtcList / Dtc / Fmi types you used above.
• Network management and heartbeat — address claim, keep-alive, and status messages.
• Language and units — operator language and unit-system preferences.

They all follow the identical decode / from_message / encode contract, so the patterns in this tutorial carry over directly. See J1939 messages and PGNs for the catalogue.

See also

• J1939 messages and PGNs — the message catalogue and PGN meanings.
• Tutorial: inspect CAN identifiers — how to get the PGN in the first place, before you decode the payload.
• SAE J1939: the heritage — the standard these codecs implement.
• Powertrain — engine and drivetrain messages in a full application.
• Diagnostics — the DM family at application scale.

Tutorial: decode NMEA 2000

NMEA 2000 shares the physical CAN bus and the PGN addressing model with J1939, but its navigation messages have their own decoding style in machbus. Instead of one struct per message with a static decode function, you use a pump-style decoder: [machbus::nmea::NMEAInterface]. You subscribe to the on_* events for the PGNs you care about, then feed it Messages. As each message arrives, the interface decodes it and fires the matching event with the decoded value. No protocol stack, no session, no IO.

This tutorial walks through examples/nmea2000_decode.rs. It sets up an interface listening for the GNSS navigation profile, encodes a position fix and a course/speed update with the matching build_* helpers, and feeds the bytes back in so the decode path actually fires and the event handlers print.

The imports

#![allow(unused)]
fn main() {
use machbus::geo::Wgs;
use machbus::nmea::{GNSSPosition, NMEAConfig, NMEAInterface};
use machbus::net::Message;
use machbus::net::pgn_defs::{PGN_GNSS_COG_SOG_RAPID, PGN_GNSS_POSITION_RAPID};
}

• NMEAInterface is the pump decoder itself — it holds the event channels and any reassembly state.
• NMEAConfig selects which PGN families the interface should decode. You enable the parts you need rather than paying for everything.
• GNSSPosition is the decoded position type: a WGS coordinate plus fix metadata (satellites, fix type, and more).
• Wgs (from machbus::geo) is the geographic-coordinate type: latitude, longitude, altitude.
• Message (from machbus::net) is the assembled message you feed in — the same type the J1939 codecs use.
• PGN_GNSS_POSITION_RAPID (129025) and PGN_GNSS_COG_SOG_RAPID (129026) are named PGN constants from machbus::net::pgn_defs, so you do not sprinkle magic numbers through your code.

The pump / event decode model

The mental model is different from the J1939 one-shot codecs, so it is worth stating plainly:

1. You construct an NMEAInterface with a config that says which PGNs to decode.
2. You subscribe handlers to the on_* events. Each event corresponds to a decoded quantity — on_position, on_cog, on_sog, and so on.
3. You feed the interface raw Messages with handle_message. For each message, the interface decodes it (reassembling Fast Packet PGNs across multiple frames first, if needed) and dispatches the result to every subscribed handler for that event.

This inverts control compared to calling decode yourself: you describe what you want once, then push messages through. It maps naturally onto a real bus loop where messages arrive continuously and you react to them.

Setting up the interface

#![allow(unused)]
fn main() {
{{#include ../../../examples/nmea2000_decode.rs:setup}}
}

Walk through it:

• NMEAConfig::default().with_gnss_navigation(true) builds a config that enables the GNSS navigation profile — rapid position, COG/SOG, heading, attitude, and the related navigation PGNs. The builder style means you can chain .with_* calls to enable exactly the families you need.
• NMEAInterface::new(config) constructs the decoder. It is declared mut because subscribing and feeding messages mutate its internal state.
• nmea.on_position.subscribe(|pos: &GNSSPosition| { … }) registers a handler for decoded positions. The closure takes &GNSSPosition — handlers are FnMut(&T), so they receive the decoded value by reference and can hold mutable captured state across calls. Inside, the example reads pos.wgs.latitude, pos.wgs.longitude, pos.satellites_used, and pos.fix_type.
• nmea.on_cog.subscribe(|cog_rad: &f64| { … }) and nmea.on_sog.subscribe(|sog_mps: &f64| { … }) register handlers for course over ground and speed over ground. Note the units carried over the wire: COG is in radians, SOG is in metres per second. The handlers convert for display — cog_rad.to_degrees() and sog_mps * 3.6 (m/s → km/h). machbus hands you SI units; presentation is your choice.

Nothing has decoded yet at this point. You have only declared what to do when a position, course, or speed arrives.

Feeding messages

#![allow(unused)]
fn main() {
{{#include ../../../examples/nmea2000_decode.rs:feed}}
}

This is where the decode path fires:

• The GNSSPosition is built with Wgs::new(52.379_189, 4.899_431, 0.0) — latitude, longitude, altitude for a point in Amsterdam — and satellites_used: 12. The ..Default::default() fills the remaining fields (fix type and the rest) with their defaults.
• NMEAInterface::build_position(&fix) encodes that fix into a [u8; 8] payload for PGN 129025, the rapid-position message. This is the inverse of what the decoder does — it exists so the example can produce valid bytes to feed back in.
• nmea.handle_message(&Message::new(PGN_GNSS_POSITION_RAPID, pos_bytes.to_vec(), 0x80)) feeds the encoded bytes back as a Message from source 0x80. The interface recognises PGN 129025, decodes it to a GNSSPosition, and fires on_position — which runs your subscribed handler and prints the line.
• The second pair does the same for course and speed: NMEAInterface::build_cog_sog(60.0_f64.to_radians(), 5.0) encodes a heading of 60° (passed in as radians) and a speed of 5 m/s into PGN 129026’s payload, and handle_message feeds it in. The interface fires both on_cog and on_sog, running their handlers.

The rapid-PGN satellite caveat

Look closely at the expected output below: it reports sats 0, even though the fix was built with satellites_used: 12. This is correct, not a bug. PGN 129025 is the rapid position message — it is deliberately minimal, carrying only latitude and longitude so it can be sent at high rate. It does not carry a satellite count. When the interface decodes a rapid-position frame, there is no satellite field to read, so satellites_used decodes to its default of 0.

The takeaway: a decoded struct reflects only what the wire format actually carries. If you need the satellite count, fix quality, and the rest, you subscribe to the richer (Fast Packet) GNSS PGN that carries them — but you pay for it in bus bandwidth and reassembly. The rapid PGN is for position, fast; nothing more.

Fast Packet reassembly

Many NMEA 2000 PGNs carry more than eight bytes and are transmitted as a Fast Packet: a sequence of CAN frames the receiver must stitch back together before decoding. handle_message handles this transparently. You feed it each frame as it arrives, and it holds partial state internally; only when a Fast Packet is complete does it decode and dispatch the event. The two PGNs in this example are single-frame rapid messages, so no reassembly happens here, but the same handle_message call is what drives reassembly for the larger PGNs.

Run it

$ cargo run --example nmea2000_decode

Output:

position: 52.379189, 4.899431  (sats 0, fix GNSSFix)
course over ground: 60.0°
speed over ground: 18.0 km/h

Read it back against the inputs:

• The latitude and longitude match the Amsterdam coordinate exactly.
• sats 0 is the rapid-PGN caveat from above — the rapid message does not carry a satellite count, so it decodes to the default.
• fix GNSSFix is the default fix type printed with {:?}.
• Course is 60.0° — the 60° heading round-tripped through radians.
• Speed is 18.0 km/h — 5 m/s converted (5 × 3.6).

What to change for real bus data

The example encodes its own bytes with build_position and build_cog_sog so the demo is reproducible. On a live bus you drop those entirely. Your job becomes: read frames off the wire, wrap each one in a Message (PGN, payload, source), and call nmea.handle_message(&msg) for every frame. The interface does the rest — decoding single-frame PGNs immediately and reassembling Fast Packet PGNs across frames before dispatching. Your on_* handlers fire exactly as they do here. You write the subscription logic once and let the message pump drive it.

See also

• NMEA 2000 on the bus — the message families and how NMEA 2000 relates to J1939.
• Tutorial: inspect CAN identifiers — how to read the PGN off the identifier, including the high PGN range NMEA 2000 lives in.
• Positioning: NMEA and GNSS — the positioning standards behind these PGNs.
• NMEA 2000 — NMEA 2000 in a full application.
• Serial GNSS — the serial-input counterpart for GNSS data.

Getting started

This section gets you from a checkout to a running node.

Read:

1. Install Rust
2. Build and verify
3. no_std on microcontrollers, if you are building firmware or an embedded task
4. First node
5. Virtual bus

Use SocketCAN only after the in-process examples make sense.

Install Rust

machbus is a Rust crate with optional C and Python surfaces.

Recommended local setup:

rustc --version
cargo --version
make build

If this repository is opened through its Nix shell, use the repository-provided environment and still prefer Makefile targets for validation.

Feature flags are documented in Feature flags.

Build and verify

Use Makefile targets first.

make build
make test
make verify

make verify is the canonical local gate. It runs the normal build/test lane, all-feature checks, clippy, rustdoc, C binding checks, C examples, Python smoke, trace replay, fuzz smoke, claim-boundary checks, package checks, hardware evidence contract checks, and whitespace checks.

Embedded/no-std checks are intentionally separate while that profile is still evolving. If you changed feature gates, protocol-core imports, the session loop, CAN transport seams, storage/file splits, or embedded examples, also run:

make no-std-check
make no-std-target-check
make no-std-surface-check
make embedded-examples-check

make no-std-target-check uses the configured NO_STD_TARGET embedded target and will tell you to install it if it is missing.

If you only changed documentation, still run at least:

make book
make whitespace-check

before claiming the book is healthy. Run make verify when documentation changes also depend on source, examples, bindings, or generated artifacts.

no_std on microcontrollers

machbus can be built for firmware-style applications where there is no operating-system standard library. In that mode the crate is a caller-driven protocol engine: your board code owns the clock, CAN peripheral, storage, task scheduling, allocator, and panic behavior.

Use this page when you are targeting a microcontroller, an RTOS task, or a small embedded Linux component that wants the same explicit ownership model.

Why this exists

Desktop examples can lean on files, host clocks, virtual buses, SocketCAN, C bindings, Python bindings, and rich geo libraries. A microcontroller usually cannot. It has a CAN peripheral, a timer, maybe flash or an SD card, and a main loop or RTOS executor.

The embedded feature split keeps those worlds separate:

• hosted/default mode keeps the convenient OS integrations;
• embedded compiles the protocol/session surface as no_std + alloc;
• embedded adds fixed-capacity helpers for bounded buffers and selected transport paths.

The important boundary is simple: machbus owns protocol state, while the application owns hardware and resources.

Mental model

        board / RTOS / firmware application
┌────────────────────────────────────────────────────┐
│ monotonic timer                                    │
│ CAN driver / interrupt queues                      │
│ flash, SD, EEPROM, LittleFS, or no persistent store │
│ allocator + panic handler                          │
│ main loop, RTOS task, or executor                  │
└───────────────┬──────────────────────┬─────────────┘
                │ Instant              │ Frame
                ▼                      ▼
        ┌────────────────────────────────────┐
        │ machbus no_std + alloc core        │
        │                                    │
        │ Session / Driver::poll_at          │
        │ J1939 / ISOBUS codecs              │
        │ address claim, TP, ETP, Fast Packet │
        │ VT / TC / FS pump state            │
        └────────────────────────────────────┘
                │
                ▼
        events and outbound CAN frames

There is no hidden host clock and no hidden CAN backend in the embedded path. Each poll step receives explicit time and drains or emits explicit frames.

Dependency setup

Disable default features and enable the embedded profile:

[dependencies]
machbus = { path = "../machbus", default-features = false, features = ["embedded"] }

For fixed-capacity helper APIs:

[dependencies]
machbus = { path = "../machbus", default-features = false, features = ["embedded"] }

The embedded profile intentionally does not compile:

What no_std + alloc means

embedded is not a zero-heap profile. It means:

• the crate itself does not require Rust std;
• heap-backed structures can still be used through alloc;
• the final firmware binary must provide any global allocator it needs;
• the final firmware binary must provide its panic strategy or panic handler;
• machbus is checked as a library, not as a complete firmware image.

That shape is intentional for the first embedded target. It gets the host APIs out of the protocol core without forcing every high-level ISOBUS service into fixed storage immediately.

If your MCU project forbids heap allocation entirely, start from embedded and use its fixed-capacity helpers at the CAN/session boundary, but treat the full no-alloc migration as still in progress.

The embedded loop

The loop shape is:

1. get board monotonic time;
2. drain received CAN frames from your driver or interrupt queue;
3. feed frames into Session;
4. tick protocol timers;
5. transmit every queued frame through your CAN driver;
6. handle session events.

Conceptually:

#![allow(unused)]
fn main() {
let mut now = board_monotonic_instant();

while let Some((port, frame)) = can_recv() {
    session.feed(port, &frame, now);
}

session.tick(now);

while let Some((port, frame)) = session.poll_transmit() {
    can_send(port, &frame)?;
}

while let Some(event) = session.poll_event() {
    handle_event(event);
}
}

The compiled example is examples/embedded_session_loop.rs. It runs as a host example for convenience, but it compiles machbus with --no-default-features --features embedded and uses the same board-owned clock/CAN/storage shape an MCU application would use.

CAN adapter boundary

The embedded CAN boundary is machbus::net::CanTransport, re-exported by the session module as machbus::session::Transport.

Your adapter receives concrete frames from the MCU HAL and converts them into machbus::net::Frame. Outbound frames go the other way.

HAL frame ──► board adapter ──► machbus Frame ──► Session
HAL frame ◄── board adapter ◄── machbus Frame ◄── Session

Keep the adapter thin. It should know about CAN IDs, DLC, data bytes, and the local CAN port number. It should not contain ISOBUS state machines. The protocol state belongs in Session, IsoNet, or the lower-level protocol helpers.

See examples/embedded_hal_adapter.rs for the compiled adapter shape without adding a dependency on a specific HAL crate.

Time and scheduling

Use machbus::time::Instant as the protocol timestamp. Convert your board timer ticks into that type at the application boundary.

Use Driver::poll_at(now) rather than hosted Driver::poll(). The _at method is deterministic because it only sees the time value you pass in. That makes it suitable for:

• bare-metal superloops;
• RTOS periodic tasks;
• cooperative executors;
• deterministic simulation tests.

Storage ownership

Embedded storage is buffer-oriented:

This avoids baking one flash layout or filesystem into the protocol crate.

Protocol surface available today

The embedded feature currently covers the useful protocol core:

• CAN frame, identifier, priority, PGN, and address-claim primitives;
• J1939 request, acknowledgment, diagnostics, heartbeat, engine, powertrain, maintain-power, and related codecs;
• TP, ETP, and Fast Packet helpers;
• NMEA/GNSS encode/decode paths;
• NIU filtering/routing and safety/physical helper data;
• selected ISO 11783 application codecs;
• Sequence Control core state and recording helpers;
• Task Controller heap-backed pump state, DDOP/object codecs, TC-GEO, grids, task logging, rate limiting, outstanding requests, ISOXML parsing, and totals;
• File Client / File Server pump state, codecs, path validation, in-memory file storage, and volume status helpers;
• Virtual Terminal object pools, VT Client / VT Server pump state, update helpers, storage-agnostic stored-version blobs, and working-set state.

The VT renderer/GTUI layer remains hosted because it is a UI/filesystem integration surface, not an MCU protocol primitive.

Fixed-capacity helpers

embedded is the first checked bounded-memory layer. It adds types such as:

• FixedQueue<T, N>;
• FixedFrameQueue<N>;
• FixedSlots<T, N>;
• FixedBytes<N>;
• FixedMessage<N>;
• fixed event polling with Session::poll_fixed_event::<N>();
• bounded TP/ETP/Fast Packet helper paths.

Use this mode when you want fixed RX/TX queues around the session loop or when you are hardening a specific transport path. Do not claim the whole crate is no-alloc yet: the session core is still the no_std + alloc profile.

See examples/embedded_fixed_queue.rs.

Validate locally

Use Makefile targets, not ad-hoc Cargo commands:

make no-std-check
make no-std-target-check
make no-std-surface-check
make embedded-examples-check

make no-std-target-check uses the documented embedded target. If your local Rust toolchain does not have it yet:

rustup target add thumbv7em-none-eabihf

For dependency audits:

cargo tree --no-default-features --features embedded -e normal

The embedded dependency graph should stay free of wirebit, concord, pyo3, and SocketCAN dependencies.

What this proves / does not prove

A green embedded check proves that the selected Rust surface compiles without std and without the hosted adapter dependencies. It also proves the examples and public embedded imports still type-check.

It does not prove:

• your MCU has enough RAM for your chosen feature set;
• your allocator strategy is real-time safe;
• CAN interrupt buffering is correctly sized;
• physical bus timing and wiring are correct;
• the product is ISO 11783, SAE J1939, NMEA, or AEF certified.

For deployment, combine these checks with board-level tests, trace captures, interoperability tests, and the hardware evidence process.

See also

• Feature flags
• Validation gates
• The session facade
• Onto real hardware with SocketCAN
• Hardware evidence

First node

This page is the shortest path to a running node. For the full tour of plugins, the sans-IO core, and the driver/handle split, read The session facade.

A node owns one local role on a bus. The exact plugins you add depend on the role, but the pattern is always the same:

1. choose a NAME
2. choose a preferred source address
3. plug only the subsystems you need
4. spawn over a transport — this gives you (Controls, Driver)
5. start, then claim an address before normal traffic
6. drive driver.poll()? and handle events

Conceptual Rust shape:

#![allow(unused)]
fn main() {
{{#include ../../../examples/session_minimal.rs:build}}
}

The snippet above is copied from examples/session_minimal.rs. Use runnable examples for the exact current API calls.

make run EXAMPLE=session_minimal

What to check

• ctrl.is_claimed() becomes true once the handshake completes, and ctrl.address() reports the address the node owns.
• The node does not send application traffic before address claim.
• Optional fine control such as ctrl.with_mut::<Diagnostics, _>(...) is only available when you plugged that subsystem (it returns None otherwise).
• Events are drained regularly enough for your application queue policy.

Common mistakes

Virtual bus

The virtual bus is the easiest way to test two roles without hardware. It is the recommended first integration environment because it exercises real stack routing without requiring SocketCAN permissions, wiring, or a running tractor.

Common setup:

• tractor node
• implement node
• both attached to the same in-process bus
• run ticks until both claim addresses
• send one workflow message
• drain events on the peer

This is how many stack tests prove behavior without relying on SocketCAN timing or machine wiring. After the virtual-bus workflow passes, move to SocketCAN traces.

make run EXAMPLE=virtual_can_demo

Two-node checklist

Why this matters

The virtual bus catches address conflicts, destination-specific PGN mistakes, event fan-out bugs, and many high-level stack regressions before you touch real hardware. It does not prove physical timing or transceiver behavior.

SocketCAN

SocketCAN is the normal Linux interface for CAN devices and virtual CAN interfaces.

For local smoke testing, use vcan0 where possible. For real machinery, use the correct interface, bitrate, termination, and safety procedure.

Typical setup outside this book:

sudo modprobe vcan
sudo ip link add dev vcan0 type vcan
sudo ip link set up vcan0

Real machine warning: never attach experimental software to a working machine without a safe test plan, isolation, and permission from the equipment owner.

Logging and traces

Traces turn bus behavior into reviewable evidence.

Useful trace sources:

• candump from SocketCAN
• compact fixture files
• bracketed candump-style fixture files
• malformed-line fixtures for parser hardening

machbus includes replay tooling and tests that reject invalid trace shapes such as standard IDs where extended IDs are required, overlong classic CAN payloads, bad hex, and CAN FD-looking tokens in classic-only paths.

Trace evidence should include the command, interface, bitrate, connected devices, and expected result.

The session facade

machbus::session is how you build an application. You compose a node from plugins (one per subsystem), drive a pure Session core, and — for the common case — let a Driver own the CAN interface while a cheap Controls handle issues commands. It covers every protocol machbus speaks, with a composable and testable shape. Hosted/default builds expose the full plugin/controls facade. Embedded builds use the same sans-IO loop shape through the no_std + alloc Session/Driver::poll_at surface, but not every hosted convenience or plugin wrapper is part of that embedded profile.

Why this shape

The session facade is built around three ideas:

• Sans-IO core. Session is a pure state machine: you feed it frames and a timestamp and drain its outputs. No socket, no system clock. That makes it deterministically testable and is the basis of the current embedded no_std + alloc build.
• Plugin composition. Each subsystem is a Plugin you .plug(...). The set is explicit, and a plugin instance is the fine-control object for that subsystem.
• Handle / driver split. spawn(transport) returns (Controls, Driver): the driver runs the loop you own; the Controls is a cheap handle for commands and status.

Mental model

   ┌── Driver + Controls ── owns the CAN transport + clock, runs the loop ┐
   │   let (ctrl, mut driver) = Session::builder(name, addr)              │
   │       .plug(...).spawn(transport)?;                                  │
   │   ctrl.start()?;  loop { driver.poll()? ... }                        │
   ├── Session ── pure sans-IO state machine (no IO, no clock) ───────────┤
   │   s.feed(port, &frame, now);  s.poll_transmit();  s.poll_event();    │
   ├── Plugins ── one per subsystem; reuse the pure codecs ───────────────┤
   │   Diagnostics · Gnss · VtClient · TcClient · FsClient · Implement · …│
   └── Codecs ── encode/decode primitives (net / j1939 / isobus) ─────────┘

A received frame flows up (transport → feed → routed to interested plugins → events). Commands and cadenced broadcasts flow down (plugin → outbound buffer → poll_transmit → transport).

The pieces

Building and driving

Build a node, plug the subsystems you want, and split into controls + driver:

#![allow(unused)]
fn main() {
{{#include ../../../examples/session_minimal.rs:build}}
}

Then drive the loop. Driver::poll_at(now) does one cycle — read the transport, feed frames, advance timers, flush outbound — and returns the next event:

#![allow(unused)]
fn main() {
{{#include ../../../examples/session_minimal.rs:claim}}
}

In a hosted real-time program you would call driver.poll() (which reads the host monotonic clock) in a loop instead of advancing now by hand. In microcontroller or deterministic embedded code, keep using driver.poll_at(now) and pass time from the board timer.

Available plugins

Everything the old facade covered, as plugins in machbus::session::plugins:

Plug one per node:

#![allow(unused)]
fn main() {
// illustrative — the API mirrors the tested types in `src/session`
let (ctrl, mut driver) = Session::builder(name, 0x80)
    .plug(VtClient::new(vt_config, pool, working_set))
    .plug(TcClient::new(tc_config, ddop))
    .plug(Diagnostics::every(1000))
    .spawn(transport)?;
}

Plugging two instances of the same plugin type is a build error (one per type).

Fine control

There are two first-class ways to drop below the facade — both work for every subsystem:

Own the subsystem component. Reach a plugged subsystem by type and call its own methods:

#![allow(unused)]
fn main() {
{{#include ../../../examples/session_minimal.rs:finecontrol}}
}

ctrl.with::<P>(...) / ctrl.with_mut::<P>(...) (or session.get::<P>() / get_mut::<P>()) return None if that plugin was not plugged.

Drive the pure core directly. Skip the driver entirely and run Session yourself — feed frames with an injected timestamp, drain outbound and events. This is what the tests and embedded loops use:

#![allow(unused)]
fn main() {
// illustrative shape
let mut s = Session::builder(name, 0x80).plug(Diagnostics::every(1000)).build()?;
s.start()?;
s.feed(0, &frame, now);                       // a received frame + the time
s.tick(now);                                  // advance timers
while let Some((port, frame)) = s.poll_transmit() { bus.send(port, &frame); }
while let Some(event) = s.poll_event() { /* handle */ }
}

For arbitrary PGNs there is a raw escape hatch: ctrl.send_raw(pgn, &data, dst, priority) / session.send_raw(...).

Events, three ways

The core produces one unified Event enum. Consume it however suits you:

1. Unified enum + poll — driver.poll()? / session.poll_event(). One match site for everything.

2. Typed per-subsystem stream — session.drain::<VtEvent>() / controls.drain::<VtEvent>() returns just that subsystem’s events and leaves the rest queued. No matching a 20-variant enum for one concern.

3. Callbacks (RAII) — register typed callbacks and pump:

   #![allow(unused)]
   fn main() {
   // illustrative shape
   let sub = driver.on::<VtEvent>(|e| handle_vt(e));   // returns a Subscription
   loop { driver.pump()?; }                            // dispatches to callbacks
   drop(sub);                                           // unsubscribes
   }

Presets (personas)

session::presets bundles curated plugin groups — one call wires up a role’s usual subsystems — for plug_group:

#![allow(unused)]
fn main() {
// illustrative shape
use machbus::session::presets;
let (ctrl, mut driver) = Session::builder(name, 0xF0)
    .plug_group(presets::tractor())     // diagnostics + implement + powertrain
    .plug(Heartbeat::every(100))        // add or drop pieces freely
    .spawn(transport)?;
}

Available: presets::tractor(), presets::implement(pool, ws, ddop), presets::diagnostic_node().

Hosted versus embedded session use

The same conceptual loop exists in both modes, but the available conveniences are different:

For the MCU-focused version of this loop, see no_std on microcontrollers.

Validate locally

make run EXAMPLE=session_minimal
make standard-suite-check
make verify

If you change feature gates or embedded session behavior, also run:

make no-std-check
make no-std-target-check
make no-std-surface-check
make embedded-examples-check

What this proves / does not prove

Running session_minimal proves the facade builds, claims an address, drives a plugin, and routes events across a virtual bus. It does not prove vendor interoperability or physical-bus timing — see Hardware evidence and the Claim boundary.

See also

• First node — the shortest path to a running node.
• no_std on microcontrollers — the embedded loop and HAL boundary.
• Crate map — where session sits in the crate.
• Receiving and routing — the feed/route/event model in plain words.

Where to start

Welcome to the machbus guided walkthrough. This is a hands-on, build-along track: you start a real Rust program, add a few lines, run it, watch ISOBUS traffic happen, and then keep extending the same program until it does something genuinely useful on a tractor bus. Every chapter ends with a program you can actually run.

If the rest of the book is the reference manual, this track is the lab course.

New here? Read The session facade first — it shows the whole shape of the API end to end. Most chapters below teach the protocols one at a time using that same session facade, building one program up step by step; chapters 7 and 8 drop down to the lower-level VT and Task-Controller client codec APIs to show how a subsystem works underneath the facade.

Who this is for

• You know a little Rust (enough to build a project with cargo) and want to learn ISOBUS by doing.
• Or you know ISOBUS and want to see how it maps onto the machbus API.

You do not need a CAN adapter or a tractor. The first ten chapters run entirely in software on a simulated bus. Real hardware shows up in chapter 10, and it is optional.

How the track is structured

The chapters build on each other. Each one keeps the program from the previous chapter and adds to it:

How to follow along

Every chapter is anchored to a real example that ships in the repository, so the code you read is code that compiles and runs. Wherever you see a code block pulled from examples/, you can run that exact example:

cargo run --example session_minimal
# or, equivalently, through the Makefile:
make run EXAMPLE=session_minimal

The recommended way to work through the track is to keep your own scratch example file open beside the book and paste each step into it as you go. If you get stuck, the finished example for that chapter is named at the top of the page — diff your version against it.

What you need installed

• A recent stable Rust toolchain (see Install Rust).
• The repository checked out, so cargo run --example ... works.
• Nothing else for chapters 1–9 and 11. Chapter 10 uses Linux SocketCAN and a vcan virtual interface.

Before you dive in

You will get more out of the track if you have skimmed two short concept pages first. They are quick reads and the walkthrough refers back to them:

• ISOBUS in plain words — the five-minute mental model.
• NAME and address claim — why a node needs an identity before it can talk.

Everything else is explained as it comes up.

A word on what this proves

The walkthrough teaches the machbus API and ISOBUS behavior in software. It is a learning resource, not a certification. machbus is not certified; shipping a real machine still needs the official standards, real hardware, and interoperability testing with the actual terminals, task controllers, and ECUs you intend to work with.

Ready? Start with The ISOBUS Hello World.

1. The ISOBUS Hello World

Anchor example: examples/session_minimal.rs — run it any time with cargo run --example session_minimal.

Every networking tutorial has a “hello world”, and on ISOBUS that hello world is not “print some text” — it is claim an address on the bus. Until a node has claimed an address it is not allowed to say anything else, so this is genuinely the first thing every real ECU does. By the end of this chapter you will have a program that brings a node onto a (simulated) ISOBUS network and watches it take ownership of an address.

We will go fast here and just get it running. The next chapter, The Hello World, line by line, pulls the same program apart and explains every piece.

What we are building

A tiny program that:

1. creates a simulated CAN bus with two seats on it,
2. builds an machbus Session for our node,
3. drives the address-claim handshake, and
4. prints the address our node ended up owning.

There are two nodes on the bus because a node is never really alone on a real machine — there is always at least a terminal or a tractor ECU present. We will call our node node_a; node_b stands in for “some other ECU that is already there”.

Step 1 — a node needs a NAME

Before anything else, a node needs an identity: its NAME. The NAME is a 64-bit value that says what the node is and which specific unit it is. We will cover every field in the next chapter and in depth in the Address claim tutorial; for now, a tiny helper that stamps out a NAME from an identity number is enough:

#![allow(unused)]
fn main() {
{{#include ../../../examples/session_minimal.rs:name}}
}

The important part is with_self_configurable(true): it tells the bus “if I lose a fight over an address, I am allowed to move to another one.” That keeps our hello world from getting stuck.

Step 2 — a bus to plug into

On real hardware the bus is a pair of wires and a CAN controller. In software, machbus talks to a bus through a transport, and the companion wirebit crate can build a simulated bus with named seats. We make a bus called bus0 with two members and take an endpoint for each, then wrap each endpoint in an EndpointTransport. Think of take_endpoint("a") as “plug a cable from seat a into our node”.

Step 3 — build the sessions

Now we build a Session for each node. The session is the machbus facade that hides all the protocol bookkeeping. Session::builder(name, addr) takes a NAME and a preferred address; .plug(...) adds optional capabilities (here a Diagnostics plugin); and .spawn(transport) returns a (Controls, Driver) pair. We then call start() on the controls to begin the claim:

#![allow(unused)]
fn main() {
{{#include ../../../examples/session_minimal.rs:build}}
}

node_a would like address 0x80; node_b would like 0x81. They do not conflict, so both should get their wish — but the bus does not know that yet. Right after spawn(), neither node has actually claimed anything. The Controls half (ctrl_a) is how you command and inspect the node; the Driver half (drv_a) is how you advance it and read events.

Step 4 — drive the claim

Claiming is not instant. A node announces its NAME at its preferred address and then waits a short window to see if anyone objects. We make that happen by polling each driver (advancing its sense of time and draining the events it produces) and pumping the bus (delivering frames between the two endpoints) in a loop:

#![allow(unused)]
fn main() {
{{#include ../../../examples/session_minimal.rs:claim}}
}

drv.poll_at(now) hands you one event at a time until there is nothing left for that instant; built.pump_all() carries the frames between endpoints. In a real program you would call drv.poll() instead, which uses the host clock, and you would not need to drive a simulated bus. That loop is the heartbeat of every machbus program: poll the drivers, pump the bus, repeat.

Step 5 — run it

Run the finished example:

cargo run --example session_minimal

You should see output that includes something like:

[claim] node A → 0x80, node B → 0x81
[events] node A saw 1 address-claim event(s)

That is the whole game. After polling and pumping, node_a owns 0x80 and node_b owns 0x81. You can confirm with ctrl_a.is_claimed() and ctrl_a.address(). Our node is now a full citizen of the bus and may start sending real traffic — which is exactly what the next chapters do.

What just happened

node_a: "NAME 0x.... wants 0x80"  ─┐
                                    ├─► bus carries both claims
node_b: "NAME 0x.... wants 0x81"  ─┘
        no conflict → both keep their preferred address → Claimed

Because the two preferred addresses were different, there was nothing to fight over. If both had asked for 0x80, the node with the lower NAME would have kept it and the other — being self-configurable — would have slid to the next free address. You can see that contest play out in the Address claim tutorial.

Things that trip people up

• Forgetting to pump. On a simulated bus, if you poll the drivers but never call pump_all(), the claim announcements never reach the other node and nobody ever becomes claimed. Poll and pump.
• Forgetting to start(). A session does not begin claiming until you call ctrl.start(). Build, start, then poll.
• Sending too early. A node must be claimed before it sends application traffic. We will rely on that in the next chapter.
• Reusing a NAME. Two nodes with identical NAMEs cannot be told apart. Give each node a distinct identity number.

Validate locally

cargo run --example session_minimal
make test

What this proves / does not prove

Proves: machbus can bring a node onto a simulated bus and complete address claim, and you can drive that from a few lines of Rust.

Does not prove: anything about real-hardware timing or interoperability with a specific ECU. The simulated bus is for learning and testing.

Next

→ 2. The Hello World, line by line — now that it runs, understand every line.

2. The Hello World, line by line

Anchor example: examples/session_minimal.rs.

In chapter 1 we got a node onto the bus. It worked, but a few things were waved past. This chapter slows down and explains every part of that program, because almost everything you do later is a variation on it. Nothing new is built here — this is the “read the manual for the thing you just used” chapter.

The imports

#![allow(unused)]
fn main() {
use machbus::Instant;
use machbus::j1939::diagnostic::{Dtc, Fmi};
use machbus::net::{Name, Result};
use machbus::session::plugins::Diagnostics;
use machbus::session::{ClaimEvent, DiagEvent, Event};
use machbus::session::{EndpointTransport, Session};
use wirebit::topology::Topology;
}

Two layers show up here, and it is worth knowing which is which:

• machbus::net is the low-level protocol layer — raw frames, NAMEs, addresses, priorities. You reach into it when you want fine control.
• machbus::session is the surface layer — the Session facade, its Controls / Driver pair, plugins, and the unified Event type. This is what most application code uses.
• wirebit is the bus transport crate. Topology builds simulated buses and hands out endpoints. On real hardware you would build a transport over a SocketCAN link instead (see chapter 10).

A session is generic over its transport. That is how the exact same session code runs on a simulated bus today and a real one later: only the transport changes.

The NAME helper

#![allow(unused)]
fn main() {
{{#include ../../../examples/session_minimal.rs:name}}
}

A Name is built with consuming with_* setters. This helper sets only three things and leaves the rest at default, which is fine for a demo. In a real product every field carries meaning:

The two nodes differ only by identity number (0x100 vs 0x999), which is enough to make their NAMEs distinct. Distinct NAMEs are mandatory — two nodes that present the same NAME break the bus’s ability to tell them apart. The full field-by-field meaning is in NAME and address claim.

Building the simulated bus

We describe a network with wirebit, build it, and take an endpoint per seat:

#![allow(unused)]
fn main() {
let mut topo = Topology::new();
let n1 = topo.add_node("a");
let n2 = topo.add_node("b");
topo.can_bus("bus0").members(&[n1, n2]);
let mut built = topo.build().unwrap();
let bus = built.can_bus_mut("bus0").unwrap();
let ep_a = bus.take_endpoint("a").unwrap();
let ep_b = bus.take_endpoint("b").unwrap();
}

Line by line:

• Topology::new() starts an empty description of a network.
• add_node("a") / add_node("b") declare two devices.
• can_bus("bus0").members(&[n1, n2]) wires both onto one CAN segment.
• build() turns the description into a live, runnable bus.
• take_endpoint("a") removes seat a’s endpoint and hands it to us, so we can wrap it in a transport. Each endpoint can only be taken once.

The object built still owns the bus itself. We keep it around because we have to pump it later to actually move frames between the seats.

Building the session

#![allow(unused)]
fn main() {
{{#include ../../../examples/session_minimal.rs:build}}
}

The builder reads like a sentence: this session has this NAME, prefers this address, has this plugin, and is spawned on this transport. The EndpointTransport::new(0, ep_a) channel index (0) matters once a node sits on more than one bus (a router/NIU node does); for a single-bus node it is always 0.

spawn() returns a Result, so a misconfigured session fails loudly rather than limping along. It also splits the session into two halves:

• ctrl_a — the Controls: command and inspect the node (start(), is_claimed(), address(), with_mut::<Plugin, _>(...)).
• drv_a — the Driver: advance the node and read events (poll() / poll_at()).

After spawn() the session exists but has not claimed anything, and it will not begin until you call ctrl.start(). If you query it before the loop runs, ctrl_a.is_claimed() is false and ctrl_a.address() is the null/no-address placeholder.

The poll-and-pump loop

This is the single most important pattern in machbus, so let us read it carefully:

#![allow(unused)]
fn main() {
{{#include ../../../examples/session_minimal.rs:claim}}
}

• start() (called just above, in the build snippet) tells each session to begin announcing its claim. This only queues the work; nothing is on the wire yet.
• Inside the loop, now.add_millis(50) advances the simulated clock by 50 milliseconds, and drv.poll_at(now) lets the driver do any work that became due — including sending its claim and, later, deciding the contention window has closed — handing you each resulting event in turn.
• built.pump_all() is the bus’s job: it carries frames that one endpoint sent over to the other endpoint’s inbox.
• The loop exits early once both ctrl_a.is_claimed() and ctrl_b.is_claimed() report success.

The mental model: sessions produce and consume frames when you poll their drivers; the bus moves frames when you pump it. Neither happens on its own. A real application runs this loop forever using drv.poll() (host clock, no simulated bus to pump), interleaving it with reading sensors and updating displays.

After enough iterations the contention window has elapsed with no conflict, and each node is claimed at its preferred address. That is the line:

[claim] node A → 0x80, node B → 0x81

Where claim results show up as events

The driver does not only let the node change its state — poll_at (and poll) also hand you an event per piece of progress:

#![allow(unused)]
fn main() {
let mut a_claims: Vec<ClaimEvent> = Vec::new();
while let Some(event) = drv_a.poll_at(now)? {
    if let Event::AddressClaim(claim) = event {
        a_claims.push(claim);
    }
}
}

The unified Event enum has a variant per subsystem — AddressClaim, Diag, Vt, Tc, and so on. A claim success arrives as Event::AddressClaim(ClaimEvent::Claimed { address }).

You will spend a lot of time in later chapters matching on these events. The rule to remember: poll the driver regularly. Events are produced as you poll; if you stop polling, the node stops making progress and you stop seeing what it did.

Fine control through the plugin

The Diagnostics plugin we attached is reachable through the controls. To raise a fault code on node A:

#![allow(unused)]
fn main() {
{{#include ../../../examples/session_minimal.rs:finecontrol}}
}

ctrl.with_mut::<Diagnostics, _>(|diag| ...) borrows the named plugin so you can call its methods. This is the general escape hatch for poking at a specific capability without leaving the session facade. Diagnostics get a full chapter later; here it is just a taste of how fine control works.

The shape of every machbus program

Strip away the demo specifics and every program in this track has the same skeleton:

build a NAME
build a Session (name + preferred address + plugins) → (controls, driver)
controls.start()
loop:
    driver.poll() → react to each Event
    do your application work (controls.send_*, controls.with_mut, ...)

The chapters from here on only change what happens inside “react” and “do your application work”. The plumbing stays identical.

Validate locally

cargo run --example session_minimal
make test

What this proves / does not prove

Proves: you understand the machbus lifecycle and event model well enough to read any later chapter.

Does not prove: anything about hardware or certification — the same caveats from chapter 1 apply.

Next

→ 3. Sending and receiving messages — now that the node is on the bus, make it talk.

3. Sending and receiving messages

Anchor example: examples/session_minimal.rs — run it any time with cargo run --example session_minimal.

In chapter 1 we got a node onto the bus, and in chapter 2 we read the program line by line. Both nodes are now claimed, which is the moment a node earns the right to say anything beyond “this address is mine”. This chapter spends that right: we make one node broadcast a message and the other node receive it.

We keep the same (controls, driver) pair from the previous chapters and the same poll-and-pump loop. Nothing new gets built; we just add traffic.

What we are adding

1. node_b builds and broadcasts a raw frame through its controls.
2. We poll and pump until the message arrives.
3. node_a reads the inbound event out of its driver.

Sender and receiver are two different nodes on the same simulated bus, exactly like a tractor ECU talking to an implement.

Step 1 — send a frame

A node sends an arbitrary frame through its controls handle. The session exposes send_raw for hand-crafted traffic:

#![allow(unused)]
fn main() {
ctrl_b.send_raw(0xFECA, &[0xDE, 0xAD, 0xBE, 0xEF], BROADCAST_ADDRESS, Priority::Default)?;
}

Reading send_raw argument by argument:

The source address is filled in for you: the session uses the address node_b actually claimed. That is why we had to wait until the node was claimed before sending — a node with no address has nothing valid to put there.

Why 0xFECA specifically? It is a PDU2 PGN — its PDU Format byte is 0xFE, which is >= 0xF0. PDU2 PGNs are broadcast-only: the message has no single addressee, so the destination field is not part of the PGN and the address we pass as “destination” will not overwrite it. That keeps this first example simple — we can broadcast to everyone without worrying about who is listening. PGNs below 0xF000 (PDU1) are addressed to one node and behave differently; the difference is covered in PGNs, priority, source and destination.

BROADCAST_ADDRESS (the value 0xFF) means “no specific recipient”. Because we chose a PDU2 PGN, this is the natural and only sensible choice: the message goes out and any node on the bus will pick it up.

Step 2 — poll and pump until it lands

Sending only queues the frame in node_b’s transport. As always in machbus, nothing moves until you pump the bus (on a simulated bus), and nothing is processed until you poll the drivers. So we run the same heartbeat from the previous chapters, watching node_a’s inbound events:

#![allow(unused)]
fn main() {
for _ in 0..10 {
    now = now.add_millis(50);
    while drv_b.poll_at(now)?.is_some() {}   // let node_b flush the send
    built.pump_all().unwrap();               // bus carries the frame
    while let Some(event) = drv_a.poll_at(now)? {
        // node_a turns the inbound frame into an Event here
    }
    built.pump_all().unwrap();               // settle
}
}

This is the same loop from chapter 1, just with traffic flowing. We poll node_b (flush the send), pump (carry the frame from node_b’s outbox to node_a’s inbox), poll node_a (let it recognise the frame and produce an event), and pump again to settle. A real application would call drv.poll() and run this forever, with no simulated bus to pump.

Step 3 — read the inbound event

Polling node_a’s driver hands you each inbound message as an Event. You match on it the same way you matched on claim events:

#![allow(unused)]
fn main() {
while let Some(event) = drv_a.poll_at(now)? {
    match event {
        Event::Custom { pgn, source, data } => {
            println!("got PGN {pgn:#06X} from {source:#04X}: {data:02X?}");
        }
        other => println!("{other:?}"),
    }
}
}

A raw inbound PGN that no subsystem claimed arrives as a Custom event carrying:

• pgn — which PGN this is (0xFECA), so one handler can serve several message kinds.
• source — the address of the node that sent it (node_b’s claimed address), so you know who is talking.
• data — the payload bytes, exactly what node_b put in (DE AD BE EF).

Anything that is not the variant you care about falls through to the other arm. That catch-all is a habit worth keeping: the event stream is shared across every subsystem, so a handler should always have a default branch.

If you prefer to collect one subsystem’s events without matching the whole stream, ctrl.drain::<E>() pulls the buffered events of a single typed kind. The poll-and-match form above is the general path; drain is the convenience when you only want one event family.

What just happened

node_b: ctrl_b.send_raw(0xFECA, ..)   ── build + queue a frame on node_b's transport
                                          │
pump_all()                             ── bus carries it to node_a's inbox
                                          │
drv_a.poll(..)                          ── session recognises the frame,
                                          makes an Event
                                          │
match event { Event::Custom { .. } => . } ── you read { pgn, source, data }

Broadcasting (a PDU2 PGN to BROADCAST_ADDRESS) means anyone on the bus hears it; an addressed message (a PDU1 PGN to a specific node’s address) is delivered to just that one recipient. We use the broadcast form here because it is the simplest thing that demonstrably works; addressed exchanges show up when we send a request and wait for an answer.

Things that trip people up

• Forgetting to pump. On a simulated bus, the frame never reaches the other node until you call pump_all(). Poll and pump.
• PDU1 vs PDU2 confusion. With a PDU2 PGN (>= 0xF000) the destination you pass is harmless — it does not change the PGN. With a PDU1 PGN it is part of the addressing and absolutely does matter. Get this wrong and your message goes to the wrong place or nowhere. When in doubt, re-read PGNs, priority, source and destination.
• Not polling the driver. Inbound frames become events only when you poll. If you stop polling, your “missing” message simply never surfaced. Poll on every loop iteration.
• Sending before claimed. The source address is only valid once the node has claimed. Sending earlier puts a bogus source on the bus.

Validate locally

cargo run --example session_minimal
make test

What this proves / does not prove

Proves: machbus can broadcast a frame from one node, move it across a simulated bus, and surface it on another node as an event with its PGN, source, and payload intact.

Does not prove: anything about real-hardware timing, electrical behaviour, or interoperability with a specific ECU. The simulated bus is for learning and testing; a real deployment still needs hardware and the official standards.

Next

→ 4. Requests and acknowledgements — broadcasting is one-way. Next we send a request to a specific node and wait for its reply.

See also

• Request a PGN — the addressed request/response pattern in depth.
• Receiving and routing — how the session decides which frames become events and where they go.
• PGNs, priority, source and destination — the anatomy of a message identifier and the PDU1/PDU2 split.

4. Requests and acknowledgements

No dedicated example for this chapter. This page builds directly on the chapter-3 program (two sessions on a simulated bus, one broadcasting a PGN the other receives). There is no separate examples/ binary for a bare PGN request, so the request/answer snippets below are illustrative shape grounded in the real machbus API, not compiled includes. Everything still validates with make test, and the codecs they use are unit-tested in the crate.

In chapter 3 a node pushed data: one node broadcast a PGN and the other picked it up whenever it happened to arrive. That is the right shape for data that streams on a schedule. But sometimes you need a value now — the current address of a peer, a version string, a one-off status — and you do not want to wait for the next broadcast that may be seconds away.

This chapter adds the pull side of the bus: you will ask another node for a specific PGN, and handle whatever comes back — including the polite “I cannot give you that” answer.

Pull versus wait-for-broadcast

So far every value reached you because someone decided to send it. A request flips that around: you name a PGN and ask a node (or everyone) to transmit it.

  PULL (this chapter)                 PUSH (chapter 3)
  requester                           sender
     │  Request(PGN = X) ─►              │  PGN X data ─► (on a schedule)
     │                                   │
     │ ◄─ PGN X data  (the answer)       ▼
     │       or                       receiver picks it up
     │ ◄─ Ack (cannot/denied/…)        whenever it arrives

A request is a tiny message whose payload is the PGN you want. The answer is either that PGN’s normal data, or — when there is nothing to give — an Acknowledgement that explains why.

Step 1 — start from the chapter-3 program

Keep the exact two-node setup you already have: a simulated bus0 with seats a and b, a session for each, the claim handshake driven by the poll-and-pump loop, and both nodes claimed. We will call them node_a (the requester) and node_b (the responder). The full skeleton, unchanged from chapter 3 — a (controls, driver) pair per node, started, then driven by the poll-and-pump loop:

#![allow(unused)]
fn main() {
// build NAMEs, build the two sessions, then:
ctrl_a.start()?;
ctrl_b.start()?;
let mut now = Instant::ZERO;
for _ in 0..30 {
    now = now.add_millis(50);
    while drv_a.poll_at(now)?.is_some() {}
    while drv_b.poll_at(now)?.is_some() {}
    built.pump_all().unwrap();
    if ctrl_a.is_claimed() && ctrl_b.is_claimed() {
        break;
    }
}
// both are now Claimed — only now may we send a request
}

Do not send a request before you are Claimed. A request from a node with no address is malformed, and a well-behaved responder ignores it. This is the same rule you met with address claim.

Step 2 — build a request for a PGN

A request rides on PGN_REQUEST (0xEA00) and carries a three-byte payload: the PGN you want, little-endian. The codec lives in j1939::pgn_request:

#![allow(unused)]
fn main() {
use machbus::j1939::encode_request;
use machbus::net::pgn_defs::PGN_ADDRESS_CLAIMED;

// Ask for "address-claimed" data — a safe PGN every node answers.
let payload = encode_request(PGN_ADDRESS_CLAIMED).unwrap();
}

encode_request returns a [u8; 3] and rejects any PGN outside the 18-bit J1939/ISOBUS range with an error, so you cannot accidentally ask for a malformed PGN.

Step 3 — send it like any frame

A request is just a frame. You send it exactly the way you broadcast in chapter 3, but you point it at a destination. Send to node_b’s address for a destination-specific request, or to BROADCAST_ADDRESS (0xFF) to ask everyone who owns the PGN:

#![allow(unused)]
fn main() {
use machbus::net::{BROADCAST_ADDRESS, Priority};
use machbus::net::pgn_defs::PGN_REQUEST;

ctrl_a.send_raw(
    PGN_REQUEST,
    &payload,
    ctrl_b.address(),   // destination: a specific peer (or BROADCAST_ADDRESS)
    Priority::Default,
)?;
}

The source address is filled in for you from the address node_a claimed — the same send_raw you used to broadcast in chapter 3, just pointed at a destination and carrying a request payload.

Then run the same poll-and-pump loop so the frame actually crosses the bus and any answer comes back:

#![allow(unused)]
fn main() {
for _ in 0..20 {
    now = now.add_millis(10);
    while drv_a.poll_at(now)?.is_some() {}
    while drv_b.poll_at(now)?.is_some() {}
    built.pump_all().unwrap();
}
}

That is the whole send path. Nothing here is new machinery — it is the chapter-3 pump loop carrying one more frame.

Step 4 — receive the answer (data, or an Ack)

On the requester, drain events the way you already do. A request resolves in one of two broad ways:

You get the data. If node_b owns the PGN, it transmits it on that PGN. Any inbound PGN that no subsystem plugin claimed surfaces as an Event::Custom when you poll node_a’s driver — exactly like the broadcast you received in chapter 3. No subscription step is needed:

#![allow(unused)]
fn main() {
// ... after the pump loop ...
while let Some(ev) = drv_a.poll_at(now)? {
    if let Event::Custom { pgn, source, data } = ev {
        println!("answer: pgn=0x{pgn:04X} from 0x{source:02X} = {data:02X?}");
    }
}
}

You get an Acknowledgement instead. When a node cannot answer with data, it may reply on PGN_ACKNOWLEDGMENT (0xE800). That is the next step.

Expected output

For a request that the peer can answer, you see the requested PGN come back as a Custom event from node_b’s address — the same event shape as a chapter-3 broadcast, except this time you triggered it:

answer: pgn=0xEE00 from 0x81 = [..]

What just happened

You named a PGN, sent it to a destination, and the responder transmitted that PGN back. The request did not say “do something” — it said “send me PGN X.” The answer is ordinary bus traffic; the only special thing was that you asked for it.

Step 5 — handle the four acknowledgement outcomes

When the honest answer is not data, the responder sends an Acknowledgment (j1939::Acknowledgment) on 0xE800. Its control byte (AckControl) tells you which of four things happened. On the requester, decode it and branch:

#![allow(unused)]
fn main() {
use machbus::j1939::{AckControl, Acknowledgment};
use machbus::net::pgn_defs::PGN_ACKNOWLEDGMENT;

if msg.pgn == PGN_ACKNOWLEDGMENT {
    if let Some(ack) = Acknowledgment::from_message(&msg) {
        match ack.control {
            AckControl::PositiveAck   => { /* accepted — proceed */ }
            AckControl::NegativeAck   => { /* not supported — stop waiting */ }
            AckControl::AccessDenied  => { /* exists, but not for us right now */ }
            AckControl::CannotRespond => { /* exists, not ready yet — retry later */ }
        }
        // ack.acknowledged_pgn and ack.address let you match it to your request
    }
}
}

What a client should do for each:

The two fields acknowledged_pgn and address let you confirm the Ack refers to the request you actually sent, which matters when several requests are in flight.

Building an Ack (the responder side)

If you are writing the responder and you do not implement a requested PGN, answer a destination-specific request with a NACK rather than silence:

#![allow(unused)]
fn main() {
let nack = Acknowledgment::nack(requested_pgn, ctrl_b.address());
// send nack.encode().unwrap() on PGN_ACKNOWLEDGMENT, back to the requester
}

Acknowledgment::ack(pgn, addr) and Acknowledgment::nack(pgn, addr) cover the two common cases; encode produces the eight-byte wire format.

Global versus specific requests

This is the one policy decision that matters most:

• Specific (destination = a peer’s address): that peer should give a definite answer — the data, or a NACK so you are not left waiting forever.
• Global (destination = BROADCAST_ADDRESS): only nodes that actually own the PGN answer; everyone else stays silent. An unanswered global request is normal, not an error.

So a request to one node that never answers is suspicious; a global request that some nodes ignore is expected.

Gotchas

• A request is not a command. It says “send me PGN X,” never “do X.” If you need a node to act, that is a different message; a request only pulls data.
• An unanswered global request is fine. Treat silence on a global request as a valid outcome. Wait a bounded time, then move on.
• Do not block waiting. Never spin tightly re-sending the same request while you wait. Send once, keep ticking-and-pumping, and only re-ask if the response window genuinely closed empty — and even then, only for CannotRespond.
• Malformed requests get no answer. decode_request returns None for short, wrongly-padded, or out-of-range payloads. An invalid request is not a request — a good responder answers nothing.

Validate locally

make test

The Request and Acknowledgement codecs (encode_request / decode_request / requested_pgn, and Acknowledgment encode/decode with every AckControl value) are covered by unit tests beside their modules and by property tests, so make test exercises the exact calls used above.

What this proves / does not prove

Proves: you can build a PGN request, send it to a specific node or to everyone, and handle both a data answer and each of the four acknowledgement outcomes, using the real machbus codecs on the same simulated-bus loop from chapter 3.

Does not prove: how a specific third-party ECU times or answers a request on real hardware, or any conformance or certification claim. machbus is not certified; a real deployment still needs official standards, real hardware, and interoperability evidence.

Next

→ 5. Moving big data with transport — when the answer to a request is larger than eight bytes, it cannot ride in one frame. The next chapter shows how the response is segmented and reassembled.

See also

• PGN request — the reference page: full anatomy of Request, Request2 / Transfer, the responder registry, and the session facade.
• PGN requests and acknowledgements — the basics, why the pull mechanism exists at all.
• Talking diagnostics — diagnostic parameter groups are a common target of destination-specific requests.

5. Moving big data with transport

Anchor example: examples/transport_demo.rs — run it any time with cargo run --example transport_demo.

In chapter 3 and chapter 4 every message fit in a single CAN frame. That is fine for a speed reading or a button press, but it does not get you far: a CAN frame holds eight bytes of payload, and the messages you actually care about — a Virtual Terminal object pool, a Task Controller device description, a diagnostic fault list, a GNSS record — are hundreds or thousands of bytes. Something has to chop the big payload into 8-byte frames, carry them across the bus, and glue them back together on the far side.

That something is the Transport Protocol. By the end of this chapter you will have sent payloads far too big for one frame and watched machbus split them, ship them, and reassemble them byte for byte — first with plain TP, then with the extended ETP for a very large payload, then with NMEA Fast Packet as the NMEA-2000 equivalent.

This is the build-along version. The Transport Protocol tutorial is the reference companion: it has the full state machine, every timeout, and every abort reason. We will point you there for the deep parts instead of repeating them.

What we are building

transport_demo is unusual for this track: instead of a session, it drives the bare transport engines directly so every frame is visible. You create a sender engine and a receiver engine, then pass frames between them by hand. That makes the splitting and reassembly something you can watch happen, step by step.

big payload                                   reassembled payload
   │                                                   ▲
   ▼                                                   │
[ sender engine ] ──► 8-byte frames over the bus ──► [ receiver engine ]

We will do this three times — TP, ETP, Fast Packet — each as its own self- contained block in main.

Step 1 — a connection-mode TP round trip (CMDT)

Start with a 40-byte payload. That is five times bigger than one frame can hold, so it cannot go out as a single message. We use connection mode (CMDT), the flavour with a handshake: the sender asks permission, the receiver paces the flow, and the receiver confirms when every byte has arrived.

Add this block — it is the whole TP section of the example:

#![allow(unused)]
fn main() {
{{#include ../../../examples/transport_demo.rs:17:56}}
}

Run it:

cargo run --example transport_demo

Expected output (the [TP CMDT] section):

[TP CMDT]
  RTS for 40 bytes (≈6 packets)
  CTS num=6 next_seq=1
  TX queued 6 DT frames
  delivered 40 bytes (equal? true)

What just happened

Read the block as a four-message conversation between tx and rx:

tx (0x10)                              rx (0x20)
  │  RTS  "40 bytes, 6 packets" ───────►│   open a receive session,
  │                                     │   allocate the buffer
  │◄────── CTS "send me 6, start at 1"  │   receiver sets the pace
  │  DT seq 1..6  ─────────────────────►│   7 payload bytes per frame
  │◄────── EndOfMsgAck "got all 40"     │   confirm + close
  ▼                                     ▼
Complete                            Complete

Line by line in the code:

1. tx.send(0xEF00, &payload, 0x10, 0x20, 0, Priority::Lowest) validates the payload, opens a transmit session, and hands back the RTS frame (“Request To Send”). The 0x10/0x20 are the sender and receiver addresses.
2. rx.process_frame(&rts, 0) opens the matching receive session and returns a CTS (“Clear To Send”) granting a window of packets. The num=6 is how many DT frames it is ready for; next_seq=1 is where to start.
3. tx.process_frame(&cts, 0) accepts the window; tx.get_pending_data_frames() drains it into the DT (data-transfer) frames — one sequence byte plus seven payload bytes each. Six frames carry the 40 bytes (ceil(40 / 7) = 6).
4. Feeding each DT frame back into rx.process_frame reassembles the bytes, and when the last one lands the receiver returns an EndOfMsgAck.
5. tx.process_frame(&eoma) confirms delivery, which fires the on_complete event we subscribed to. The completed TransportSession carries the reassembled data, and got.data == payload proves it came back intact.

The key idea: the receiver is in charge of pace. It never gets more frames than the CTS it just issued asked for, so a slow receiver cannot be flooded. That handshake-and-flow-control is exactly what makes CMDT the right choice for the big, must-not-drop uploads (object pools, device descriptions) you will meet in later chapters.

Step 2 — the same idea, much bigger (ETP)

TP has a ceiling. Its on-wire counters cap a single transfer at 1785 bytes. When your payload is bigger than that, you reach for the Extended Transport Protocol (ETP), which widens the counters to carry payloads into the megabytes. ETP is connection-mode only — there is no broadcast form.

Here we push 2.5 KiB (2500 bytes), well past TP’s limit, so ETP is required. The handshake is the same shape, with one extra step folded in (a packet-offset message that lets ETP’s small sequence numbers address a huge payload — the tutorial covers it). Because that means several CTS windows, the example pumps in a loop until reassembly completes:

#![allow(unused)]
fn main() {
{{#include ../../../examples/transport_demo.rs:60:96}}
}

Expected output (the [ETP] section):

[ETP]
  converged in 23 turns, delivered 2500 bytes (equal? true)

The exact turn count is not important — what matters is that the loop keeps pumping frames back and forth until received is filled, then checks that 2500 bytes came back byte-for-byte equal. The pump loop here is the same heartbeat you have used since chapter 1, just with the bus stood in by hand: keep feeding frames between the two engines until the transfer converges. Stop pumping early and the transfer never finishes.

The size ladder

The three mechanisms form a ladder, and the choice is decided purely by how many bytes you are sending:

machbus enforces these bounds for you: TransportProtocol::send rejects a payload that is 8 bytes or smaller (“use a single frame”) and one that is too big for TP (“use ETP”), and ExtendedTransportProtocol::send rejects anything small enough for plain TP. You generally do not pick the protocol yourself at the session layer — it looks at the size and routes to the right engine.

Step 3 — Fast Packet, the NMEA side

ISOBUS rides on J1939, where TP/ETP is the transport. NMEA 2000 — the marine and GNSS world — shares the same CAN physical layer but uses its own lighter multi-frame scheme called Fast Packet for payloads up to a couple hundred bytes. machbus speaks it too, and the API mirrors TP closely.

Here we send a 30-byte GNSS-style payload as Fast Packet:

#![allow(unused)]
fn main() {
{{#include ../../../examples/transport_demo.rs:100:119}}
}

Expected output (the [Fast Packet] section):

[Fast Packet]
  5 frames for 30 bytes
  reassembled 30 bytes (equal? true)

What happened

Fast Packet has no handshake at all. tx.send(PGN_GNSS_POSITION, &payload, 0x10) returns the complete set of frames in one go — the first frame carries a length and the leading bytes, each following frame carries a sequence counter and more payload. The receiver glues them back together as they arrive and returns the finished message once the last frame lands. Thirty bytes split into five frames; msg.data == payload confirms the round trip.

Fast Packet is to NMEA what BAM (the broadcast form of TP) is to ISOBUS: a fire-and-forget, no-flow-control way to push a moderately sized payload to listeners. It trades the safety of a handshake for simplicity and speed.

Broadcast vs connection-mode

You have now seen both postures, and the difference is the one thing to carry forward:

• Connection-mode (CMDT, ETP) — there is exactly one receiver, it paces the flow with CTS windows, it can refuse the transfer, and it confirms completion. Reliable. Use it for uploads that must not drop a byte.
• Broadcast (BAM, Fast Packet) — the sender pushes to everyone with no acknowledgement and no flow control. A listener that misses a frame just fails to reassemble and drops the message; nobody retransmits. Use it when many nodes want the same data and occasional loss is acceptable.

machbus handles the framing, sequencing, and reassembly in both cases. Your job is to hand it a payload and pump.

Things that trip people up

• Stopping the pump too early. Reassembly only completes when you keep feeding frames between the engines. In the ETP step that is the whole point of the loop — break out before received is filled and you get nothing. With a real session this is the usual poll-and-pump loop; keep it running.
• Pumping only one side. A transfer needs frames flowing both ways (RTS→CTS→DT→ack). On a virtual bus, if you only pump the sender, the receiver never gets a chance to issue its CTS and the transfer stalls until it times out.
• Expecting flow control on broadcast. BAM and Fast Packet have no CTS and no ack. There is no back-pressure and no retry — by design.
• Aborts and timeouts exist. Out-of-order frames, duplicate sequences, exhausted buffers, and silent peers all end a session with an abort or a timeout. The full list of abort reasons and the timeout windows lives in the Transport Protocol tutorial — reach for it when a transfer misbehaves.

Validate locally

cargo run --example transport_demo
make test

The example runs all three round trips and prints equal? true for each, proving every payload was split and reassembled byte for byte.

What this proves / does not prove

Proves: machbus can split a payload too large for one CAN frame, carry it as a stream of 8-byte frames, and reassemble it intact — over plain TP, over ETP for very large payloads, and over NMEA Fast Packet — and that it picks the right mechanism by payload size.

Does not prove: anything about real-hardware timing, interoperability with a specific third-party ECU, or any conformance or certification claim. machbus is not certified; real deployment still needs official standards, hardware, and interoperability evidence.

Next

→ 6. Talking diagnostics — fault codes and the kind of fault lists that ride on top of the transport you just built.

See also

• Transport Protocol tutorial — the full reference: state machine, timeouts, every abort reason.
• Fast Packet tutorial — the NMEA multi-frame mechanism in depth.

6. Talking diagnostics

Anchor example: examples/diagnostic_demo.rs — run it any time with cargo run --example diagnostic_demo.

In chapter 5 we moved a payload too big for one frame. Now we make the node say something a human cares about: what is wrong with it.

Picture a service technician plugging a laptop into a machine that quit in the field. The first two questions are always “what failed?” and “which box do I replace?” Diagnostics answers both. A faulting ECU broadcasts the codes that are active right now, keeps a history of ones that were active so a tool that arrives late still sees them, and exposes an identity so the tool knows exactly which unit and software it is talking to.

By the end of this chapter you will have built a fault code by hand, packed it into the active-fault message, read it back out, and you will know how the previously-active list, clearing, and identity fit around it.

What we are building

We work at the codec layer here — pure build-the-struct, encode, decode. No bus, no claim loop yet; just the bytes a diagnostic message is made of, so the anatomy is unmistakable. The example:

1. builds a DTC (a single fault) from its three parts,
2. packs two of them into a DM1 (the “active faults” message) with a lamp lit,
3. encodes that to bytes and decodes it straight back, and
4. round-trips a lone DTC field byte-for-byte.

Then we look at how the previously-active list, clearing, and identity ride the exact same types once you wrap a session around them.

Step 1 — the imports

#![allow(unused)]
fn main() {
{{#include ../../../examples/diagnostic_demo.rs:4:4}}
}

Five names, one module. Dtc is a single fault. Fmi says how it failed. DmDtcList is the message that carries a list of faults plus a lamp panel (DiagnosticLamps), and LampStatus is the state of one lamp. Everything lives under machbus::j1939 because ISOBUS diagnostics is the J1939 diagnostic layer with a few extra fields — see Diagnostics basics.

Step 2 — anatomy of a DTC

A Diagnostic Trouble Code is the unit of fault information, and it has exactly three meaningful parts:

Read together: “parameter X is failing in manner Y, and it has happened N times.” Build one and watch it survive a round-trip through its 4-byte wire form:

#![allow(unused)]
fn main() {
{{#include ../../../examples/diagnostic_demo.rs:48:61}}
}

The SPN here (0x1_2345) is wide on purpose: encoding clamps it to 19 bits and masks the count to 7 bits, so a Dtc always produces a valid wire field rather than corrupting the bytes around it. The assert_eq! proves the value you put in is the value you get back.

Step 3 — pack faults into a DM1

DM1 is the active diagnostics message: the faults a node has right now. In machbus it is DmDtcList — a lamp panel plus a Vec<Dtc>. We build one with the amber warning lamp on and two faults in the list:

#![allow(unused)]
fn main() {
{{#include ../../../examples/diagnostic_demo.rs:9:32}}
}

The lamp panel and the DTC list are independent fields. A DTC says what is wrong; the lamp says how loudly to alert the operator. We lit amber_warning and left the malfunction, red-stop, and engine-protect lamps at their default. The same two-byte lamp block rides at the front of every active/previously-active message, so a reader learns the codes and the alert level from one frame.

Step 4 — encode, send, decode

On a real bus you would put dm1.encode() on the wire and the receiver would call DmDtcList::decode(..). Here we do both ends in one breath so you can see the bytes survive the trip:

#![allow(unused)]
fn main() {
{{#include ../../../examples/diagnostic_demo.rs:34:46}}
}

encode always produces at least 8 bytes (lamps, then the DTCs), and decode returns the faults back as a Vec<Dtc>.

Step 5 — run it

cargo run --example diagnostic_demo

Expected output:

=== Diagnostic Demo ===
[DM1] 2 active DTCs, amber=On
[encode/decode] 10 bytes round-trip → 2 DTCs
  SPN=0x00208 FMI=VoltageLow OC=0
  SPN=0x000BE FMI=AbnormalRateChange OC=7

[DTC] 4-byte field: SPN=0x12345 → wire [45, 23, 27, 0C] → SPN=0x12345
✓ DTC round-trips byte-exact

What just happened

  Dtc{spn:520,  fmi:VoltageLow,         oc:0}  ─┐
  Dtc{spn:190,  fmi:AbnormalRateChange, oc:7}  ─┤
  lamps{ amber: On }                            ├─► DmDtcList.encode() ─► 10 bytes
                                                ─┘                          │
                                                                           ▼
        DmDtcList.decode(bytes)  ◄────────────────────────  back to 2 DTCs + lamps

Two faults plus a two-byte lamp block encoded to 10 bytes, and decoding gave back the same two faults. SPN 520 prints as 0x00208, SPN 190 as 0x000BE — that is just hex, not a different value. The standalone Dtc proved its 4-byte field round-trips byte-exact (45 23 27 0C), which is the guarantee everything above is built on.

Active vs previously-active

DM1 is only half of the read story. When a fault clears, it does not vanish — it moves to the previously-active list, which is published as DM2. DM2 uses the same DmDtcList type. The split is what lets a late-arriving service tool reconstruct what happened:

fault raised  ──►  ACTIVE list   ──► DM1  (broadcast, ~once a second)
                       │
                  fault clears / repaired
                       ▼
                  PREVIOUSLY-ACTIVE list ──► DM2  (sent on request)

A healthy node still broadcasts DM1 — with an empty list. “Nothing wrong” is a real, useful state, not the absence of a message.

Clearing and identity (the session surface)

The codec layer you just used has no list management on purpose. Once you wrap a session around it — plug in the Diagnostics plugin — the active/previous bookkeeping, the periodic DM1 broadcast, and request handling come for free. The shapes below are illustrative — for the verified behavior and the full plugin API, follow the Diagnostics tutorial.

#![allow(unused)]
fn main() {
// Illustrative shape, not a compiled call — see the tutorial.
ctrl.with_mut::<Diagnostics, _>(|diag| {
    diag.raise(Dtc { spn: 520, fmi: Fmi::VoltageLow, occurrence_count: 1 });
}); // adds an active fault → DM1
// ... after the repair ...
ctrl.with_mut::<Diagnostics, _>(|diag| {
    diag.clear();
}); // clears the active list
}

Clearing on the Diagnostics plugin is clear-all: clear() takes no arguments and empties the active DTC list in one call. (The DM protocol itself also defines a service-tool single clear that names one (spn, fmi) and gets an Ack or Nack back; that targeted form is not exposed on this plugin.)

Identity answers the second technician question — which box? A node can be asked for its identification strings (part number, serial, manufacturer, software version, and so on). The tool reads those to confirm exactly which ECU and firmware it is about to clear codes on or reflash. The codecs for those strings live alongside the DM messages; the tutorial covers them in full.

A note on size

Two faults fit in one CAN frame. A long fault list, or a multi-field identity string, will not — those payloads ride the transport protocol you met in chapter 5. You do not change how you build the message; the lower layer fragments and reassembles it for you.

Things that trip people up

• No-fault is a valid state. An empty DmDtcList still encodes to a proper DM1. Do not treat “zero DTCs” as an error or a reason to stay silent.
• Clearing is a move, not a delete. A cleared active code lands in the previously-active list. A technician an hour later still sees it on DM2. That is the whole point — do not expect it to disappear.
• Occurrence counting is yours to manage at this layer. The count does not auto-increment. When the same (spn, fmi) recurs, bump the count instead of pushing a duplicate (use Dtc::matches, which compares by (spn, fmi) and ignores the count). The Diagnostics plugin’s raise is idempotent by (spn, fmi), so the counting policy stays explicitly yours.
• Lamps and codes are independent. A lamp on with no code, or codes with all lamps off, are both legal. Decide your lamp policy deliberately; a reader will not infer one from the other.
• Decoders are strict. A wrong length or a bad placeholder returns nothing rather than a half-parsed value. Check the result; do not unwrap blindly on bytes from the wire.

Validate locally

cargo run --example diagnostic_demo
make test

The example builds a DM1 with two DTCs, round-trips it through encode/decode, and asserts a single DTC field round-trips byte-exact. The test suite exercises every DM codec — round-trips, SPN clamping, lamp packing, and the strict-decode rejections.

What this proves / does not prove

Proves: you can build a DTC from its three parts, pack faults into the active message, and round-trip them through encode/decode in software — and you know where the previously-active list, clearing, and identity fit.

Does not prove: real-hardware timing, interoperability with a specific third-party ECU or service tool, or any conformance/certification claim. The same caveats from the earlier chapters apply.

Next

→ 7. Your first Virtual Terminal client — put a screen on the operator’s terminal.

See also

• Diagnostics tutorial — the full DM family, the session diagnostics surface, clearing, memory access, and identity strings.
• Diagnostics basics — the conceptual primer for DTCs and the DM messages.

7. Your first Virtual Terminal client

Anchor example: examples/vt_client_demo.rs — run it any time with cargo run --example vt_client_demo.

So far our node has claimed an address, swapped messages, moved big payloads, and answered diagnostics. It is a good bus citizen, but it has no way to talk to the person in the cab. That is the job of a Virtual Terminal client.

Here is the key idea: an implement usually has no screen of its own. Instead it borrows the terminal’s. The implement ships the terminal a description of its user interface — a tree of objects called an object pool — and the terminal draws it. From then on the implement sends small commands (“set this number to 42”) and receives input events (“soft key 7 was pressed”) back over the bus.

By the end of this chapter you will have driven a VT client from Disconnected all the way to Connected, watched its connect state machine advance step by step, and pushed one runtime update to the screen. We will keep it focused: building a real pool is a big topic with its own tutorial, so our pool here is deliberately tiny.

The deep reference for behavior is the Virtual Terminal client tutorial and Virtual Terminal concepts. This chapter is hands-on: add a bit, run it, see what happens.

What we are building

The example stands in for the whole bus in software. It plays the implement (the VT client) and fakes the terminal at address 0x80 by feeding the client the frames a real terminal would send. That lets us watch every step of the connect handshake without any hardware. The program will:

1. build a minimal object pool and a client,
2. connect() and pump the connect state machine to Connected,
3. react to the terminal’s replies along the way, and
4. send one UI command once the pool is live.

Step 1 — build a pool and a client

A VT client always starts from an object pool: the UI it wants drawn. Ours is the smallest pool that means anything — a working set object (the implement’s “name badge” on the terminal) that points at a single data mask (one full-screen layout):

#![allow(unused)]
fn main() {
{{#include ../../../examples/vt_client_demo.rs:16:28}}
}

VTClient::new takes a VTClientConfig (the default is fine — a 6-second per-step timeout, VT version 4). set_object_pool hands it the UI tree. connect() does not block and does not put anything on the wire yet; it arms the state machine and moves the client to “listening for a terminal”. Right after it returns, client.state() reports WaitForVTStatus.

Why a working set plus a mask? The working set is your implement’s whole identity on the terminal; a mask is one screen within it. The terminal needs both: something to identify the client, and something to draw. The full object model is covered in Virtual Terminal concepts.

Step 2 — the terminal announces itself

A real VT periodically broadcasts a status frame. The client is waiting for exactly that: the first valid status binds the session to that terminal’s address and advances the FSM. We fake the broadcast (terminal at 0x80, reporting VT version 4) and feed it in with handle_vt_message, then call update to get the first outbound frame:

#![allow(unused)]
fn main() {
{{#include ../../../examples/vt_client_demo.rs:30:48}}
}

This is the same tick-and-pump rhythm from chapter 2, specialized for the VT: inbound frames drive transitions (handle_vt_message); update performs the send-side steps and hands you back a Vec of frames to ship. Each returned frame is a ClientOutbound carrying a pgn, data, and dest — you route it through your own send path exactly as given.

Two update calls happen here. The first emits the Working Set Master frame (announcing our working set to the network). The second emits Get Memory, which asks the terminal to reserve room for the pool — the example asserts that frame’s first byte is cmd::GET_MEMORY.

Step 3 — memory OK, then upload the pool

The terminal answers Get Memory with a verdict: “I have room” or “I do not”. We feed back an OK reply, then pump the pool transfer and the End Of Object Pool marker, and finally feed the terminal’s activation reply:

#![allow(unused)]
fn main() {
{{#include ../../../examples/vt_client_demo.rs:51:75}}
}

Notice the ordering. update ships the pool transfer first (on a real bus this is the part the transport-protocol layer fragments across many CAN frames), and only after that does End Of Object Pool go out. The client deliberately lets the transfer drain before it sends the end marker — sending “that’s all” while the multi-frame transfer is still in flight confuses a real terminal. When the terminal’s End Of Object Pool reply comes back with no error, the client reaches VTState::Connected. The example asserts exactly that.

Step 4 — the connect state machine, in one picture

What you just pumped through is a fixed sequence of states. It is worth seeing the whole path at once:

Disconnected
   │  connect()
   ▼
WaitForVTStatus      ◄── VT status frame binds the terminal
   │  update()
   ▼
SendWorkingSetMaster ── emits Working Set Master
   │  update()
   ▼
SendGetMemory        ── emits Get Memory (pool size)
   │  update()
   ▼
WaitForMemory        ◄── "memory OK" reply
   │  update()
   ▼
UploadPool           ── emits the pool transfer
   │  update() (after a settle delay)
   ▼
WaitForEndOfPool     ◄── End Of Object Pool reply, no error
   │
   ▼
Connected            ── UI commands now allowed

Each “waiting” state is bounded by the config timeout: if the terminal goes silent, the client falls back to Disconnected instead of hanging, and a later status frame can start a fresh attempt. The full table — including the language ReloadPool path and the memory-not-OK branch — is in the client tutorial.

Step 5 — send a runtime update

Now that we are Connected, the pool is live on the terminal and we may send UI commands. The simplest is changing a number — the value behind an output-number object:

#![allow(unused)]
fn main() {
{{#include ../../../examples/vt_client_demo.rs:78:84}}
}

change_numeric_value(object_id, value) returns a ClientOutbound addressed to the bound terminal. This is the everyday loop of a running implement: read your sensors, then push the changed values down with commands like this. You change the value an object references, not the layout — the layout was uploaded once, back in step 3.

The command surface is broad (hide_show, enable_disable, change_string_value, change_active_mask, and many more); they all share two rules: they return a ClientOutbound addressed to the terminal, and they all require the Connected state, returning an error if you call them too early. The full set is in VT updates.

Step 6 — run it

cargo run --example vt_client_demo

You should see the state machine march through its steps, each line printed by the example as it advances:

=== VT Client Demo ===
[1] connect()    → WaitForVTStatus
[2] VT_STATUS    → SendWorkingSetMaster
[3] update() → 1 frame (SendGetMemory)
[4] update() → GET_MEMORY (WaitForMemory)
[5] mem OK     → UploadPool
[6] update() → ... frames (pool transfer + EOP)
[7] EOP ack    → Connected  ✓

[ui] change_numeric_value(0xCAFE, 42) → pgn=0x..., dest=0x80, len=8

Read it top to bottom and you can see the whole lifecycle: connect arms the machine, the status frame binds the terminal, each update advances one step and emits the right frame, the activation reply flips us to Connected, and only then does the UI command go out — addressed to the terminal at 0x80.

Reacting to operator input

In the demo we drive everything by hand, but a real client is event-driven. The terminal sends input events down when the operator acts, and the client fans them out to handlers you register before connecting. The ones you will reach for first:

The pattern is always the same: operator presses a soft key → the terminal sends an input event up → your on_soft_key handler reads the object ID and the ActivationCode (Pressed, Released, Held, Aborted) → you run your logic → you send commands back down to update the screen. The terminal never runs your logic; every visible change is a command you issued. The full event list is in the client tutorial.

Things that trip people up

• Sending updates before Connected. Every command method enforces the Connected state and returns an error otherwise. Watch state() (or on_state_change) and gate your own logic on it — do not generate UI churn into the void.
• Ending the pool too early. Do not try to shortcut the settle delay between the pool transfer and End Of Object Pool. The client waits on purpose so the multi-frame transfer can finish; sending the end marker over a still-draining transfer confuses a real terminal.
• A pool the terminal rejects. An unknown object type, a duplicate object ID, or a missing child reference surfaces as a pool error in the End Of Object Pool reply — the client fires on_pool_error and drops to Disconnected. Fix the offending object and reconnect.
• No active-WS status. The client only reports whether your working set is the active one after you tell it your own address with set_self_address; until then on_active_ws_status stays quiet.

Validate locally

cargo run --example vt_client_demo
make test

make test exercises the client’s transition, timeout, and pool-validation paths beyond the happy path the example walks.

What this proves / does not prove

Proves: machbus can drive a VT client through its full connect-and-upload state machine — discover, announce, reserve memory, transfer the pool, end it, and go active — and then issue UI commands, all from a few lines of Rust against a simulated terminal.

Does not prove: rendering on a real terminal, interoperability with a specific third-party VT, or any conformance/certification claim. machbus is not certified; real deployment still needs official standards, real hardware, and interoperability evidence.

Next

→ 8. Your first Task Controller client — give the implement a screen’s quieter cousin: a controller that logs and commands its work without an operator watching.

See also

• Virtual Terminal client — the connect lifecycle, version/memory negotiation, and event fan-out in depth.
• VT object pools — how to build a real interface tree (more than our one-mask demo).
• VT updates — the full command surface for keeping the UI in sync with your application state.

8. Your first Task Controller client

Anchor example: examples/tc_client_demo.rs — run it any time with cargo run --example tc_client_demo.

In chapter 7 we gave the implement a screen to talk to the operator. Now we give it the quieter partner that needs no screen at all: a Task Controller. Where the Virtual Terminal is about showing things to a person, the Task Controller is about logging and controlling the actual field work — how much product to apply, which sections are on, and what was really done. A documentation TC mostly listens (it records measured values for the field log); a control TC also talks back (it sends setpoints down).

Here is the key idea, and it mirrors the VT one: before the implement can trade any work data, it must describe itself first. With the VT it uploaded an object pool of screens. With the TC it uploads a device description — a small tree called the DDOP (Device Descriptor Object Pool) that says “this is what I am and these are the values I can talk about.” Only after the TC has that description, and has activated it, do the two sides start exchanging process data.

By the end of this chapter you will have driven a TC client from Disconnected all the way to Connected, watching its connect state machine advance one step at a time as you feed it the frames a real Task Controller would send.

The deep reference for behavior is the Task Controller client tutorial and Task Controller concepts. This chapter is hands-on: add a bit, run it, see what happens.

What we are building

The example stands in for the whole bus in software. It plays the implement (the TC client) and fakes the Task Controller at address 0x33 by feeding the client the frames a real TC would send. That lets us watch every step of the connect handshake without any hardware. The program will:

1. build a tiny DDOP and a client,
2. connect(), then hear the TC announce itself,
3. announce a working set and negotiate the TC’s version,
4. upload the DDOP and activate it, landing on Connected.

Step 1 — build a DDOP and a client

A TC client always starts from a DDOP: the description of the machine the TC will log and control. Ours is the smallest pool that means anything — one device object (the implement as a whole, with a designator and software version) that owns one device element (the Root of the device tree):

#![allow(unused)]
fn main() {
{{#include ../../../examples/tc_client_demo.rs:22:34}}
}

TaskControllerClient::new takes a TCClientConfig (the default is fine — a six-second per-step timeout, a version-4 client). set_ddop hands it the device description. connect() does not block and does not put anything on the wire yet; it validates the DDOP, arms the state machine, and moves the client to “listening for a TC”. Right after it returns, client.state() reports it is waiting for the server’s status.

#![allow(unused)]
fn main() {
{{#include ../../../examples/tc_client_demo.rs:36:39}}
}

Why so small? A real DDOP describes every boom, section, bin, and reportable quantity, each with a DDI and units. That is a topic of its own — see the DDOP tutorial. Here we keep it to one device and one element so the handshake is the only thing on screen.

Step 2 — the TC announces itself

A real Task Controller periodically broadcasts a process-data status frame. The client is waiting for exactly that: the first valid status binds the session to that TC’s address and advances the FSM. We fake the broadcast (TC at 0x33) and feed it in with handle_tc_message:

#![allow(unused)]
fn main() {
{{#include ../../../examples/tc_client_demo.rs:41:51}}
}

This is the same tick-and-pump rhythm from chapter 2, specialized for the TC: inbound frames drive transitions (handle_tc_message); update performs the send-side steps and hands you back the frames to ship. After this status, tc_address() is bound to 0x33 — every reply from here on must come from that source, and frames from any other address are refused.

Step 3 — announce the working set, then ask the TC’s version

With a TC in sight, the client announces which working set owns the upcoming pool and then asks the TC what protocol version it speaks. Each update performs one send-side step:

#![allow(unused)]
fn main() {
{{#include ../../../examples/tc_client_demo.rs:53:60}}
}

The first update ships the Working Set Master announcement (member count one). The second ships the version request. Version negotiation comes before anything substantial on purpose: a connection only works at the level both ends support, so “what version is this TC” is the first fact the client establishes.

Step 4 — the version reply

The TC answers with its protocol version and its technical capabilities (how many booms and sections it can handle). We feed that reply back and read the recorded version:

#![allow(unused)]
fn main() {
{{#include ../../../examples/tc_client_demo.rs:63:72}}
}

tc_version() now reports what the TC told us. A malformed version reply is ignored and the client keeps waiting until the timeout, rather than proceeding on bad data.

Step 5 — upload the DDOP, then activate it

Now the description goes up. update serializes the DDOP and emits it as an object-pool transfer (on a real bus, large pools are fragmented across many CAN frames by the transport-protocol layer):

#![allow(unused)]
fn main() {
{{#include ../../../examples/tc_client_demo.rs:74:80}}
}

The TC replies with a verdict on the pool — accepted or rejected — and the client then sends the activate command and waits for its acknowledgement. A zero status means success:

#![allow(unused)]
fn main() {
{{#include ../../../examples/tc_client_demo.rs:82:95}}
}

When the activation reply comes back clean, the client reaches TCState::Connected. The example asserts exactly that. Only now — pool uploaded and activated — is it meaningful to emit process data.

Step 6 — the connect handshake, in one picture

What you just pumped through is a fixed sequence of states. It is worth seeing the whole path at once:

Disconnected
   │  connect()  (validates the DDOP)
   ▼
WaitForServerStatus    ◄── TC status frame binds the server address
   │  update()
   ▼
SendWorkingSetMaster   ── emits Working Set Master
   │  update()
   ▼
RequestVersion         ── emits the version request
   │
   ▼
WaitForVersion         ◄── version + capabilities reply
   │  update()
   ▼
TransferDDOP           ── emits the device-description upload
   │
   ▼
WaitForPoolResponse    ◄── pool accepted
   │  update()
   ▼
ActivatePool           ── emits the activate command
   │
   ▼
WaitForActivation      ◄── activation reply, no error
   │
   ▼
Connected              ── process data now allowed

Each “waiting” state is bounded by the config timeout: if the TC goes silent, the client falls back to Disconnected instead of hanging, and a later status frame can start a fresh attempt. There is also a branch the demo skips for brevity — the label check — described next.

Label-based caching: the upload you can skip

A real client does not always re-upload its DDOP. Between announcing its version and transferring the pool, it can ask the TC two questions: do you already hold my structure? and do you already hold my localization (language/units)? The device object carries a structure label and a localization label for exactly this. If the TC answers that both already match, the client skips the whole transfer and jumps straight to activation; if they do not match, it deletes the stale pool first and then uploads. Set stable labels on your device object so a TC that has met your implement before does not re-download the pool every session. The full label-driven decision is in the client tutorial.

Process data: the live conversation

Once Connected, the handshake is over and the running exchange begins. Every process-data message names an element (which part of your device, from the DDOP) and a DDI (which quantity, from the shared data dictionary), plus a 32-bit value where one applies. It flows both ways:

• Up — measured values. The implement reports what it is actually doing: real rates, flows, counts, section states. A documentation TC logs these. You build an ECU→TC value frame and ship it; the client also calls your value-request handler when the TC asks for a current reading.
• Down — setpoints and commands. A control TC sends what it wants done: target rates, section on/off. The client calls your value-command handler with the element, DDI, and value. A downward command is a request — your application validates it against the real machine state and decides whether acting on it is safe. The implement always owns its own behaviour.

A DDI is only meaningful with its owning element: the same “actual rate” DDI can appear once per section, so “DDI X changed” is ambiguous until you know which element reported it. The DDOP is the map that removes that ambiguity. The message-level detail is in DDOP and process data.

Step 7 — run it

cargo run --example tc_client_demo

You should see the handshake march through its steps, each line printed by the example as it advances:

=== TC Client Demo ===
[1] connect → WaitForServerStatus
[2] TC_STATUS → SendWorkingSetMaster, tc_addr=0x33
[3] sent WS Master + VERSION_REQUEST → WaitForVersion
[4] TC version=4, → TransferDDOP
[5] DDOP frame size=8 bytes → WaitForPoolResponse
[6] activated → Connected  ✓

Read it top to bottom and you can see the whole lifecycle: connect arms the machine, the TC status binds the server at 0x33, the working-set announcement and version request go out, the version reply advances us, the DDOP uploads, and the activation reply flips us to Connected. Only after that last line would real process data start to flow.

Things that trip people up

• Process data before Connected. Reporting values against a pool the TC has not activated is meaningless, and the client’s state guards exist to stop it. Watch state() (or the state-change event) and gate your own logic on Connected — do not emit work data into the void.
• Skipping the version handshake. Both ends cap themselves to the version and capabilities the other actually supports. Establish “what version is this TC” and “how many sections does it support” first, not as an afterthought.
• A DDOP the TC rejects. A non-zero pool response means the upload was refused; the client returns to Disconnected rather than pretending the pool is live. Re-check the DDOP for duplicate object IDs or dangling references before retrying.
• A value out of range. Element numbers are carried in a 12-bit wire field, so a number that does not fit is rejected when you build the payload — a coding error surfaces as an error, not a corrupted frame on the bus.
• A reply from the wrong TC. Once a TC is bound, frames from any other source address are refused. Make sure the TC you target is the one whose status you first heard.

Validate locally

cargo run --example tc_client_demo
make test

make test exercises the client’s label-driven upload/skip/delete decision, the timeout-to-Disconnected path, the re-upload sequence, and the value-request and setpoint callbacks — well beyond the happy path the example walks.

What this proves / does not prove

Proves: machbus can drive a TC client through its full connect handshake — discover the TC, announce a working set, negotiate the version, upload the device description, and activate it — landing on Connected, all from a few lines of Rust against a simulated Task Controller.

Does not prove: interoperability with a specific third-party Task Controller, real-hardware timing or bandwidth behaviour, or any conformance/certification claim. machbus is not certified; real deployment still needs official standards, real hardware, and interoperability evidence.

Next

→ 9. Tractor and implement personas — step back from a single service and wire the whole machine together: a tractor ECU and an implement ECU talking across the bus.

See also

• Task Controller client — the connect FSM, the label-based upload decision, and the process-data callbacks in depth.
• DDOP — how to build and validate the device description you upload (more than our one-element demo).
• DDOP and process data — the message-level view of the device description and the live values.

9. Tractor and implement personas

Anchor example: examples/session_minimal.rs — run it any time with cargo run --example session_minimal. It shows the session build-and-claim loop the personas below ride on top of.

The curated roles live in presets: presets::tractor() and presets::implement(pool, ws, ddop) are plugin groups you plug into a session in one call.

Every chapter up to now built a single node and taught it one trick: claim, send, request, move big data, talk diagnostics, drive a VT, drive a TC. A real machine is not one node doing one trick. It is at least two cooperating ECUs on the same bus — a tractor that knows how fast the ground is moving and where its hitch sits, and an implement that needs those numbers to do its job and occasionally wants the tractor to lift the hitch or spin the PTO.

This chapter stands both of those up. We use two pre-wired presets — plugin groups the session assembles for you — so you can think in machine terms (“this is the tractor”, “this is the implement”) instead of wiring every subsystem by hand. The deep behaviour lives in the Tractor ECU and Implement ECU tutorials; here we build and run.

What a preset is

A preset is a bundle of plugins with the right subsystems already switched on for a job. presets::tractor() returns the plugin group a tractor ECU needs — the tractor message groups and its classification. presets::implement(pool, ws, ddop) returns the implement-side group. You feed either to the session builder with .plug_group(...):

#![allow(unused)]
fn main() {
use machbus::session::{Session, presets};

let (ctrl, mut driver) = Session::builder(name, addr)
    .plug_group(presets::tractor())
    .spawn(transport)?;
ctrl.start()?;
}

Underneath, both presets build the same Session you have used since chapter 2 — the poll-and-pump loop, the event stream, and address claim all work exactly as before. The preset just turns on a coherent set of subsystems in one call.

There are two directions of traffic, and keeping them straight is the whole point of this chapter:

   TRACTOR preset                           IMPLEMENT preset
  ┌────────────────┐                       ┌────────────────┐
  │ PUBLISH state  │ ── speed/distance ──► │ read latest    │
  │ speed, hitch,  │ ── hitch / PTO ─────► │ values, react  │
  │ PTO, GNSS      │                       │                │
  │                │ ◄── hitch command ─── │ COMMAND tractor│
  │ accept command?│ ◄── PTO command ───── │ (if allowed)   │
  └────────────────┘ ◄── aux-valve cmd ─── └────────────────┘

Publishing is a one-way broadcast: the tractor states a fact, anyone who cares subscribes. Commanding is a request the other side may refuse. The tractor publishes; the implement commands. (A capable tractor may also accept commands — that is the right-to-left arrow.)

Step 1 — build a tractor preset

A tractor describes itself with a classification: its base class, whether it offers navigation messages, whether it is front-mounted, and so on. The presets::tractor() group carries sensible tractor defaults and the tractor message groups; you plug it into the session alongside the usual NAME, preferred address, and transport:

#![allow(unused)]
fn main() {
let (tractor, mut tractor_drv) = Session::builder(tractor_name, 0xF0)
    .plug_group(presets::tractor())
    .plug(Gnss::listen())   // the tractor preset has no GNSS — add it to publish position
    .spawn(tractor_transport)?;
tractor.start()?;
}

The builder reads like a description of the machine: this identity, prefers address 0xF0 (the conventional TECU address), with the tractor role plugged in. The presets::tractor() group bundles diagnostics, implement messages, and powertrain — it does not include GNSS, so we add Gnss::listen() here because Step 3 publishes a position. spawn() returns a Result so a contradictory configuration fails loudly.

Step 2 — claim

Then drive the same claim handshake from chapter 1 — poll the driver, pump the bus, repeat until claimed. This is exactly the claim anchor in the session example:

#![allow(unused)]
fn main() {
{{#include ../../../examples/session_minimal.rs:claim}}
}

ctrl.is_claimed() and ctrl.address() tell you where the node landed. Everything you learned about the loop still applies; the preset just rides on top of it.

Step 3 — publish state

A claimed tractor broadcasts what it knows. Use fine control on the relevant plugin to publish a GNSS position (latitude, longitude, ground speed) or raise a diagnostic, then keep polling and pumping so the frames actually move:

#![allow(unused)]
fn main() {
tractor.with_mut::<Gnss, _>(|gnss| {
    gnss.broadcast_position(&pos);
});
}

This is publishing in its purest form — the tractor states a fact and walks away. It does not wait for an acknowledgement and does not care who reads it; the poll-and-pump loop puts the position on the wire.

Step 4 — the events queue

Whatever a node receives surfaces on the one unified event stream you drain with driver.poll_at(now)? (or driver.poll()? on a real clock). Personas do not get their own parallel queue — every subsystem feeds the same Event enum you have been draining since chapter 2:

#![allow(unused)]
fn main() {
while let Some(event) = tractor_drv.poll_at(now)? {
    match event {
        Event::Gnss(g) => { /* position fix */ }
        Event::Diag(d) => { /* fault code */ }
        _ => {}
    }
}
}

Step 5 — two nodes on one bus

The real-machine shape is a tractor and an implement on the same bus0, the tractor built with presets::tractor() and the implement with presets::implement(pool, ws, ddop):

#![allow(unused)]
fn main() {
let (implement, mut impl_drv) = Session::builder(impl_name, 0x80)
    .plug_group(presets::implement(pool, ws, ddop))
    .spawn(impl_transport)?;
implement.start()?;
}

Both must claim before either can say anything else, so the claim loop polls both drivers and pumps the shared bus between them — the same shape as the single-node claim anchor above, with a second poll_at for the implement.

This is the gotcha that bites everyone: if only one session claims, the other stays at the 0xFE null address and silently drops any application traffic you try to send through it. Poll both, pump once, every iteration.

Step 6 — the tractor commands the implement

With both nodes claimed, the tractor issues commands through its implement-message plugin: a rear-hitch raise, a rear-PTO speed, an auxiliary-valve extend. Use with_mut to reach the plugin and queue each command; the following pump loop delivers them. Note the raw values — 4320 raw for ~540 rpm, 0x4000 for 50% flow. The session passes the encoded field through; it does not invent units for you.

Step 7 — the implement reads and reacts

On the other side, the implement drains its stream and matches on Event::Imp(ImplementEvent::…). Then it reads the cached latest value for each through fine control on its implement plugin.

There are two ways to consume implement traffic, and you will use both:

The event tells you something changed; the cached getter tells you what the value is right now. Control loops usually poll the cached value each tick and only watch events for edges (a command just landed, a value went stale).

ImplementEvent at a glance

ImplementEvent is the implement subsystem’s slice of the unified Event enum. The variants this chapter exercises are HitchCommand { hitch, msg } (someone asked to move a hitch), PtoCommand { pto, msg } (drive a PTO at a target speed and ramp), and AuxValveCommand(m) (drive an aux valve at a flow rate). The Hitch and Pto enums (Hitch::Rear, Pto::Rear) pick which actuator; the message body carries the command. Match the variant you care about and ignore the rest, exactly as with any other Event. Both Hitch and Pto are re-exported from machbus::session.

Gotchas

• Both sessions must claim first. On a two-node bus, poll and pump both every iteration until each reports claimed. A node still at 0xFE cannot send anything.
• Check facility availability. A preset only offers what it turned on. Gate on the relevant cached getters returning Some(...) before you trust a value. A None from a last-hitch getter means “no command seen yet”, not “hitch is down”.
• Plan for stale data. Published state can stop arriving (cable knocked loose, sender reset). The cached getter keeps handing you the last value it saw, which can be dangerously old. Real control logic times out a value and falls back to a safe default — stop metering, hold position — rather than acting on a stale number.
• Commands are requests. The tractor publishes; the implement commands. A command is never a guarantee — the receiving side decides whether to honour it, and on a real machine its interlocks have the final say.

Validate locally

cargo run --example session_minimal
make test

What this proves / does not prove

Proves: machbus can stand up tractor and implement presets on one simulated bus, have the tractor publish state and command the implement, and have the implement consume both event-driven and via cached latest values — all on the same poll-and-pump loop and unified event stream from chapter 2.

Does not prove: anything about real-hardware timing, signal cadence, or interoperability with a specific commercial tractor or implement. The simulated bus is for learning and testing; a real pairing still needs official standards, hardware, and interoperability evidence.

Next

→ 10. Onto real hardware with SocketCAN — take the same session code off the simulated bus and onto a real CAN interface.

See also

• Tractor ECU — the publish-vs-command split, classes and facilities, message groups in depth.
• Implement ECU — the consumer side: reading state, safe-state thinking, requesting actions.
• TIM and automation — when an implement is allowed to drive the tractor automatically, and the safety machinery around it.

10. Onto real hardware with SocketCAN

Anchor example: examples/socketcan_capture.rs — a real SocketCAN program. With the socketcan feature on and a Linux CAN interface available, run it with cargo run --features wirebit --example socketcan_capture. It is a frame capture tool: it transmits a few ISOBUS-shaped frames on the interface and records them back into a candump file, proving the wire path end-to-end. It does not build a Session — the session-on-SocketCAN snippets below are illustrative shape showing how you would swap the transport, grounded in the real spawn(...) API.

Up to chapter 9 every node lived on a simulated bus: a wirebit topology whose frames you moved by hand with pump_all(). That is perfect for learning and testing, but it is not a wire. This chapter is where you leave the simulator. You will run the same kind of session code from chapter 1, unchanged in spirit, against a real Linux CAN interface — using a virtual vcan0 so you need no adapter and no machine.

The headline you should carry out of this chapter: the session code does not change. Only the transport changes. You build the session exactly as you have all along; you just hand spawn(...) a SocketCAN transport instead of an endpoint transport. Everything you already know still applies.

If you only want the setup reference, the short version lives in Getting started → SocketCAN. This chapter is the build-along.

What we are building

The anchor example puts real ISOBUS-shaped frames on a real vcan0 interface and records them with a CaptureRecorder, while candump lets you watch the same raw bytes cross the wire — in the same format you read about in Reading candump traces. Alongside it, this chapter shows illustratively how a full Session would run over the same SocketCAN transport: the only thing that changes versus the simulated chapters is the argument you hand to spawn(...).

Step 1 — turn on the socketcan feature

SocketCAN support is behind a Cargo feature. The hosted default build includes the virtual-bus adapter, but not the Linux-only SocketCAN backend, and the embedded profile excludes both. Everything in this chapter needs the hosted socketcan feature. The exact feature name is socketcan, and you pass it on the command line:

cargo run --features wirebit --example socketcan_capture

If you just want to confirm the examples type-check on your machine without a live interface, there is a make target for exactly that:

make socketcan-examples-check

That runs cargo check --features wirebit --examples. It does not open any interface, so it works anywhere — it only proves the code compiles.

Step 2 — bring up a virtual CAN interface

You do not need a physical adapter to exercise the wire format. Linux ships a virtual CAN driver, vcan, that behaves like a real interface but loops frames back in the kernel. Create one called vcan0:

sudo modprobe vcan
sudo ip link add dev vcan0 type vcan
sudo ip link set vcan0 up

These three commands load the vcan kernel module, create the interface, and bring it up. They touch kernel networking state, so they need privileges — hence sudo. Once vcan0 is up it persists until you reboot or remove it (sudo ip link delete vcan0).

Sanity-check that it exists and is up:

ip link show vcan0

You should see vcan0 listed with state UP (vcan often reports UNKNOWN/UP flags — that is normal for a virtual link).

The same vcan0 shows up in the replay tutorial too; see SocketCAN replay for turning captures into repeatable fixtures.

Step 3 — build a session on a SocketCAN transport

Here is the only real difference from chapter 1. Instead of taking an endpoint from a simulated topology, you open a SocketCAN transport on the named interface and hand it to spawn(...). A SocketCanConfig names the interface; create_if_missing: false means “the interface must already exist” (you made it in step 2). The interface name commonly comes from an environment variable like MACHBUS_SOCKETCAN_IFACE, defaulting to vcan0.

From there, the session builder is identical to the simulated case — same NAME, same preferred address, same plugins. (The anchor example is a capture tool and does not build a session; this snippet is illustrative shape for the transport swap.)

#![allow(unused)]
fn main() {
let (ctrl, mut driver) = Session::builder(name, addr)
    .plug(Plugin::...)
    .spawn(socketcan_transport)?;
ctrl.start()?;
}

This is the payoff of the transport being a pluggable parameter. Compare it to the hello-world builder in chapter 2: the only thing that moved is the argument to spawn(...) — an endpoint transport became a SocketCAN transport. Everything above the transport is unchanged.

Step 4 — claim, then drive

The driving loop is the same rhythm from chapter 1, with one important change: there is no pump_all().

On the simulated bus, you carried frames between endpoints by pumping. On SocketCAN there is no software bus to pump — the kernel moves the frames. You still drive the session with driver.poll()? to let it produce and consume frames and advance, but delivery is the operating system’s job now. Because you are on a real host clock, use driver.poll() rather than the simulated driver.poll_at(now); let real wall-clock time pass between polls so the claim’s contention window can elapse and the OS has a moment to ferry frames.

So the loop slogan from chapter 1 — poll the driver, pump the bus — becomes poll the driver, and let the OS move frames. Everything above the transport is unchanged: ctrl.start(), driver.poll(), ctrl.is_claimed(), ctrl.address(), and the plugin event handling all behave exactly as they did on the simulator.

Step 5 — run it, watching the wire

Open two terminals.

Terminal 1 — watch the raw wire:

candump -td -L vcan0

-td prints the delta time between frames; -L prints in a log format that includes the interface. Leave it running.

Terminal 2 — run the example:

cargo run --features wirebit --example socketcan_capture

candump (terminal 1) then shows the actual frames the capture example puts on vcan0 — a handful of ISOBUS-shaped frames (an Address Claimed-style frame and a couple of broadcasts). Those are real CAN frames in the standard 29-bit extended-ID encoding, identical in layout to what a physical ECU would put on the wire. A session running over the same transport would emit its own Address Claimed frame and broadcasts in exactly this format.

What just happened

  example process               vcan0 (kernel)             candump
  ───────────────               ─────────────              ───────
  tx → ISOBUS frame       ──►   frame on the wire   ──►    raw bytes
  tx → ISOBUS frame       ──►   frame on the wire   ──►    raw bytes

No pump_all() appears anywhere. The kernel is the bus. Independent processes — the example and candump — both attach to the same interface and see the same traffic, exactly as separate ECUs and a logging tool would on a shared CAN segment. A session running over a SocketCAN transport works the same way: you poll the driver and the kernel moves the frames.

Bit-rate and timing realities

On vcan the bitrate field is cosmetic: a virtual interface has no physical layer, so frames appear effectively instantly and a bitrate: 250_000 in the config is just carried metadata. On a real adapter that number matters a great deal. Every node on a CAN segment must agree on the bitrate (ISOBUS commonly runs at 250 kbit/s), and the sample point and termination have to be right or you get errors and bus-off conditions instead of frames. Real adapters also impose real arbitration and queueing delays that vcan does not model. The concepts behind all of this — arbitration, priority, the J1939 ID structure — are covered in CAN and J1939. Treat vcan as a faithful model of the wire format, not of wire timing.

Things that trip people up

• Feature not enabled. Without --features wirebit the SocketCAN code is not compiled in. If you see a usage hint instead of “opening SocketCAN interface”, rerun the example with cargo run --features wirebit --example socketcan_capture.
• Interface down or missing. With create_if_missing: false, if vcan0 does not exist or is not UP, the example errors at startup. Re-run the step 2 commands and check ip link show vcan0.
• Permissions. Creating and bringing up an interface needs sudo. Opening an existing vcan0 from the examples usually does not — but on a locked-down host, opening raw CAN sockets may still require elevated capabilities.
• Nothing observed. If candump shows no frames, the session probably ran on a different interface. Use the same MACHBUS_SOCKETCAN_IFACE everywhere.
• PDU2 vs PDU1 on the wire. What you see in candump is the assembled 29-bit CAN identifier, not the friendly PGN names the API uses. A broadcast PDU2 message carries its PGN directly in the ID; a destination-specific PDU1 message packs the destination address into the same bits. If a frame’s ID does not match the PGN you expected, that mapping is usually why — see Reading candump traces for decoding identifiers by hand.

Validate locally

The live example needs a Linux CAN interface, so it is not part of make verify. What you can always run is the type-check:

make socketcan-examples-check

With vcan0 up (step 2), the full run is:

cargo run --features wirebit --example socketcan_capture

What this proves / does not prove

Proves: machbus produces correct, standard-format CAN frames on a real Linux interface, and those frames round-trip to a separate listener (the capture recorder and candump) — confirming the on-the-wire encoding end to end. The same transport swap carries a full Session unchanged.

Does not prove: anything about a physical adapter’s timing, bitrate negotiation, electrical termination, or interoperability with a specific real-world ECU. vcan is a kernel loopback; it models the wire format, not the physics. Real deployment still needs proper hardware, configuration, and interoperability evidence, and machbus ships no certification.

Next

→ 11. Async event streams — instead of a hand-rolled poll-and-react loop, bridge the session into async event streams.

11. Async event streams

By chapter 2 you knew the machbus heartbeat: poll the driver, pump the bus, then react to each event it hands back. Every chapter since has matched on those events by polling — driver.poll_at(now)? or driver.poll()? in your own loop. That works, but in an async program it is awkward: you end up threading the event loop through your own scheduling instead of just await-ing the next thing that happens.

This chapter shows how to bridge the session’s event loop into async code you can await. You still drive poll and pump the bus yourself — the session does not sprout a background thread — but a local task can sleep on an async channel until the next event lands instead of busy-polling. This is an advanced, opt-in pattern; it builds directly on the event model from chapter 2, so make sure that one feels solid first.

Why bridge to async

The polling API is fine for a tight, synchronous loop. An async application is different: it already has an executor, and it wants to express “wait here until something happens” as an .await. The pattern below gives you exactly that. The events are the same events the sync API drains; the async channel is a thin view over them. Nothing about the protocol changes — only how your code waits.

The one rule that shapes everything below: the session is single-threaded and !Send by design. Its internal state lives in Rc<RefCell<_>>, so the session itself cannot move to another thread. You run it on a local executor. There is no tokio dependency baked in and no hidden runtime; CAN progress happens only when you poll and pump.

Step 1 — turn on the async feature

Async helpers live behind the async Cargo feature. Enable it on your dependency line:

[dependencies]
machbus = { version = "0.1", features = ["async"] }

This pulls in futures-core (for the Stream trait). It does not add a runtime — see Feature flags for exactly what each flag pulls in.

Step 2 — build the session and a local executor

The setup is the familiar one from chapter 1: a one-node topology, an endpoint, and a session split into (ctrl, driver):

#![allow(unused)]
fn main() {
let (ctrl, mut driver) = Session::builder(name, addr)
    .plug(Plugin::...)
    .spawn(transport)?;
ctrl.start()?;
}

Because we will not move the session across threads, the executor you pick is a local one — for example futures::executor::LocalPool, which runs tasks on the current thread, or a tokio LocalSet with spawn_local. A multi-threaded executor cannot hold a !Send future, so do not reach for a plain tokio::spawn or a worker pool.

Step 3 — feed events into an async channel

The bridge is one idea: in your synchronous poll loop, push each event the driver returns into an async channel, and let a local task await the receiving end. The driver stays on the main thread; the channel carries owned Event values, so the consumer side can live in any local task.

            ┌─────────────────────┐
 poll()  ─► │  Session (!Send)    │  produces events
 pump    ─► │   └─ each Event ◄────┼── push into an async channel (Sender)
            └─────────────────────┘
                     ▲
            await ───┘  local task awaits the channel's Receiver

When the channel is empty, awaiting the receiver parks the task and stores its waker; the next pushed event wakes it. You drive the producer side; the consumer side reads like ordinary async code.

Step 4 — spawn a local task that awaits events

Spawn a task onto the local pool that loops over the receiver. This is the ergonomic payoff: while let Some(event) = rx.next().await reads like ordinary async code, and each iteration parks until an event actually arrives.

#![allow(unused)]
fn main() {
// On the local pool:
spawn_local(async move {
    while let Some(event) = rx.next().await {
        // react to `event` here, fully async
    }
});
}

spawn_local is the local-executor counterpart of a thread-spawning spawn; it keeps the task on this thread, which is exactly what a !Send consumer requires.

Step 5 — keep driving poll and pump yourself

Here is the part people miss: spawning the task did not start any CAN traffic. The session still only makes progress when you poll it and pump the bus. So the main thread runs the same poll-and-pump loop from chapter 1, pushing each event into the channel and giving the executor a chance to run:

#![allow(unused)]
fn main() {
ctrl.start()?;
loop {
    while let Some(event) = driver.poll_at(now)? {
        tx.unbounded_send(event).ok();
    }
    pump_bus();
    pool.run_until_stalled(); // let the listening task drain the channel
    if ctrl.is_claimed() { break; }
    now = now.add_millis(50);
}
}

ctrl.start() queues the claim; each poll_at advances and lets the session send and settle; pumping moves frames; run_until_stalled() gives the listening task a chance to pull events off the channel and react. On a real host clock you would call driver.poll() instead of driver.poll_at(now).

What just happened

main thread                         local task
-----------                         ----------
ctrl.start()
loop:
  driver.poll_at(now) ──pushes──►   channel
  pump / run_until_stalled ──wake─► rx.next().await returns event
                                     reacts to it, fully async
  (claimed?) break

The session produced an event the moment the claim landed; pushing it into the channel woke the parked task; the task reacted to it. No polling on the consumer side, and no extra thread anywhere.

Things that trip people up

• Forgetting to still poll and pump. The async channel is not a runtime. If you spawn the listener but never call driver.poll() and pump the bus, no frames move, no events are produced, and your task sleeps forever. The application still owns the heartbeat.
• Expecting Send. The session is !Send on purpose. Trying to move it onto a multi-threaded worker (a plain tokio::spawn, a thread pool) will not compile — and you should not work around it. Keep the driver and its consumer on one thread.
• Picking the wrong executor. Use a local executor that polls on the current thread: LocalPool, or a tokio LocalSet with spawn_local. A multi-threaded executor cannot hold a !Send future.
• Bounded channels back-pressure. If you use a bounded channel and the consumer falls behind, the producer side fills up. Drain regularly, or size the channel for your worst-case burst.

What this proves / does not prove

Proves: machbus can bridge its event loop into a runtime-agnostic async channel that integrates with a local async executor, while you keep full control of the poll-and-pump heartbeat.

Does not prove: any multi-threaded safety. The session stays single-threaded and !Send even with async enabled — this surface is a consumption convenience, not a concurrency model. The usual caveats hold: nothing here is certified, and a real deployment still needs official standards, hardware, and interoperability evidence.

See also

• Feature flags — what async pulls in and why the session stays single-threaded.
• Receiving and routing messages — the event model the channel is a view over.

Next

→ 12. Capstone: a complete implement ECU — put the whole track together into one working node.

12. Capstone: a complete implement ECU

Anchor example: examples/session_minimal.rs — run it any time with cargo run --example session_minimal. It is the smallest end-to-end session; the capstone below scales the same shape to three nodes.

This is the last chapter of the track, and it is the one where everything you built in isolation comes together into a single program that looks like a real machine. So far each chapter taught one thing on its own bus. Here we put a tractor, a virtual terminal, and an implement on one bus, let them claim, connect, publish, and react, and drive all three from one poll-and-pump loop. No new concept is introduced — this is the assembly chapter.

What we have learned

Every step below is a capability from an earlier chapter. The capstone uses all of them at once:

The session facade — the presets, the plugins, and the unified Event enum — is what lets one short main hold all of this. Doing the same at the raw net/isobus layer would mean wiring each protocol’s state machine by hand on each node.

What we are building

                         bus0
   ┌──────────┐      ┌──────────┐      ┌──────────────┐
   │ Tractor  │      │   VT     │      │  Implement   │
   │  0xF0    │      │  0x26    │      │    0x80      │
   │ GNSS     │──────│ 800x480  │──────│ 6 sections   │
   │ alarm    │      │ status   │      │ reads DM1    │
   └────┬─────┘      └──────────┘      └──────┬───────┘
        │ position, DM1 (low fuel)            │
        └────────────► every peer ◄───────────┘ sections on

Three presets, one bus, one loop. The tractor publishes its position and raises a low-fuel alarm; the VT server comes online and emits status; the implement turns on three sections and watches the tractor’s diagnostics roll in.

Step 1 — the NAME helper and the topology

Same NAME helper as chapter 1, reused for all three nodes. They differ only by identity number, which is enough to keep their NAMEs distinct — exactly the name anchor from the session example:

#![allow(unused)]
fn main() {
{{#include ../../../examples/session_minimal.rs:name}}
}

The topology now has three seats on bus0 instead of two. You build it and take one endpoint per node, then wrap each in a transport for spawn(...).

Step 2 — build the three sessions from presets

This is the heart of the session facade. Instead of one generic session configured by hand, each node plugs in the preset that turns the right subsystems on for its role:

#![allow(unused)]
fn main() {
let (tractor, mut tractor_drv) = Session::builder(make_name(1), 0xF0)
    .plug_group(presets::tractor())
    .plug(Gnss::listen())   // the tractor preset does not include GNSS — add it
    .spawn(tractor_transport)?;

let (vt, mut vt_drv) = Session::builder(make_name(2), 0x26)
    .plug(VtServer::new(VTServerConfig::default())?)   // no VT preset — plug the server
    .spawn(vt_transport)?;

let (implement, mut impl_drv) = Session::builder(make_name(3), 0x80)
    .plug_group(presets::implement(pool, ws, ddop))
    .spawn(impl_transport)?;
}

Read what each builder asks for:

• the tractor prefers address 0xF0 (the tractor’s conventional range) and plugs in the tractor preset (diagnostics, implement messages, powertrain). The preset does not include GNSS, so we add Gnss::listen() to publish position.
• the VT prefers 0x26 (the first VT address). There is no VT preset, so we plug a VtServer directly; VtServer::new validates the config and returns a Result.
• the implement prefers 0x80 and plugs the implement preset, which takes the object pool, working set, and DDOP it advertises.

Each spawn() returns a Result. Every session is the same Session underneath; the preset just bundles the plugins, and fine control with ctrl.with_mut::<Plugin, _>(...) reaches any one of them when you need role-specific behaviour.

Step 3 — claim, all three at once

Nothing may talk before it has an address, so the first loop is pure address claim. You call start() on every session, then run the familiar poll-pump-settle loop — only now it polls three drivers per iteration. This is the same claim anchor from the session example, scaled up:

#![allow(unused)]
fn main() {
{{#include ../../../examples/session_minimal.rs:claim}}
}

After about a simulated second all three are claimed and the program prints their addresses:

[claim] tractor=0xF0, vt=0x26, implement=0x80

The ordering matters: claim comes first, application traffic second. If you publish before a node is claimed, the send is rejected — there is no address to send from.

Step 4 — bring the subsystems online

Now that everyone owns an address, each session does its job through fine control on its plugins. The VT server starts emitting status, the tractor publishes a position fix and raises a low-fuel alarm, and the implement connects to the task controller so it can report its working values:

#![allow(unused)]
fn main() {
// VtServer::start returns a Result — handle it.
vt.with_mut::<VtServer, _>(|srv| srv.start())
    .transpose()?;

tractor.with_mut::<Gnss, _>(|g| g.broadcast_position(&pos));

tractor.with_mut::<Diagnostics, _>(|diag| {
    // SPN 96 is the fuel-level parameter; FMI BelowNormal is the low-fuel alarm
    diag.raise(Dtc { spn: 96, fmi: Fmi::BelowNormal, occurrence_count: 1 });
});

implement.with_mut::<TcClient, _>(|tc| tc.connect())
    .transpose()?;
}

These are independent actions on independent sessions. Because they all share one bus, what one node sends, the others can receive. The DM1 the tractor raises is the diagnostic message every node on the bus can read; connecting the TC client is how the implement begins reporting the working-set values a task controller logs.

with_mut returns Option<R> (None if the plugin is not plugged); when the inner call returns a Result, .transpose()? turns Option<Result<…>> into Result<Option<…>> so you can propagate any error.

Step 5 — the single combined run loop

You drain the claim events first (you already saw the claim print), then run the same loop again for two simulated seconds. This time it is not driving a handshake — it is letting the periodic broadcasts (VT status, the tractor’s DM1, GNSS) fire repeatedly and flow to every peer:

#![allow(unused)]
fn main() {
for _ in 0..40 {
    now = now.add_millis(50);
    while tractor_drv.poll_at(now)?.is_some() {}
    while vt_drv.poll_at(now)?.is_some() {}
    while impl_drv.poll_at(now)?.is_some() {}
    built.pump_all().unwrap();
}
}

This is the whole point of the chapter. One loop body — poll every driver, pump the bus — drives an entire machine. A real application would interleave reading sensors and updating displays inside this loop, but the plumbing is exactly what you wrote in chapter 1.

Step 6 — drain the unified event stream

Each node’s driver hands back events it received from its peers. The unified Event enum carries a variant per subsystem, so one match reaches across diagnostics, GNSS, VT, and the rest. The implement counts the DM1 broadcasts it saw, and the tractor counts the echoes it received:

#![allow(unused)]
fn main() {
while let Some(event) = impl_drv.poll_at(now)? {
    if let Event::Diag(DiagEvent::Dm1Received { source, active, .. }) = event {
        // the implement seeing the tractor's low-fuel alarm
    }
}
}

Event::Diag(DiagEvent::Dm1Received { source, active, .. }) is the implement seeing the tractor’s low-fuel alarm — the same SPN/FMI the tractor raised in step 4, now decoded on the other side of the bus. The tractor’s drain matches DiagEvent::Dm1Received and GnssEvent::Position from the same unified enum.

Drain or drop: the event stream is bounded. Poll it to empty every iteration; if you never read it, the oldest events are dropped to make room. In a long-running machine you drain every loop iteration, not once at the end. Typed draining is also available — ctrl.drain::<DiagEvent>() pulls just the diagnostics events.

Putting it together — expected output

Run the minimal session example to see the build-and-claim shape end to end:

cargo run --example session_minimal

=== Session facade — minimal demo ===

[claim] node A → 0x80, node B → 0x81
[events] node A saw 1 address-claim event(s)
[rx] node B received DM1 from 0x80 with 1 active DTC(s)

Done.

The capstone scales that same shape to three nodes: three nodes boot, all three claim, the VT comes online, the tractor publishes and alarms, the implement acts, and over two seconds the periodic diagnostics flow across the bus and land as events. The exact DM1 count depends on broadcast cadence and the run window; the shape is what matters.

How the pieces compose

The three sessions never call each other directly. They compose through the bus: one node broadcasts, the bus carries the frame, every other node decodes it into an event. That is why the implement sees the tractor’s low-fuel alarm without any wiring between them — they only share bus0 and the same poll loop.

Where the session facade saved you work versus the low-level layer:

• Presets and plugins instead of hand-wired subsystems. presets::tractor() and presets::implement(...) bundle a role’s plugins, and a single plug such as VtServer::new(...) turns one subsystem on. At the net/isobus layer you would assemble each protocol’s state machine yourself on each node.
• One Event enum instead of N inboxes. Diagnostics, GNSS, VT, and TC events all arrive on one stream you drain with one match. You do not poll each subsystem separately.
• Fine control for the rest. ctrl.with_mut::<Plugin, _>(...) reaches any plugin when you need a role-specific call — raise a fault, send a position, flip a section — without leaving the facade.

When you need to own every byte — tests, tight control loops, an unusual PGN — the low-level layer is still there underneath. The presets are built on it.

Gotchas

• Claim before app traffic. Every node must be claimed before it publishes. The example runs a full claim loop first for exactly this reason.
• Drain events or they drop. The event stream is bounded. Poll it regularly.
• Poll every driver, every iteration. A session that stops being polled stops sending its periodic broadcasts and stops decoding inbound frames. In a multi-node loop it is easy to forget one — poll all three here.
• Pump after polling. Frames a session produced sit in its outbox until you pump the bus. Poll and pump.

Validate locally

cargo run --example session_minimal
make test

What this proves / does not prove

Proves: machbus can host a realistic multi-node machine — tractor, VT, and implement presets — on one bus, drive address claim, subsystem startup, publishing, and cross-node event reaction from a single loop, entirely in software. It is a working software integration of everything in this track.

Does not prove: that this is a certified or hardware-proven machine. machbus is not certified. The bus here is simulated; the timing, the terminals, and the ECUs are not the real ones you would ship against. A real deployment still needs the official standards, real hardware, and interoperability testing with the actual devices you intend to work with.

Where to go next

You have finished the build-along track. To go deeper, leave the lab course and open the reference manual:

• Tutorials — one page per subsystem, in depth: the Implement ECU and Tractor ECU tutorials expand the presets you just used, and there are dedicated pages for the VT client, TC client, diagnostics, and the rest.
• Reference — the crate map, protocol coverage, feature flags, and error handling, for when you are building a real product and need exact behavior.
• Language bindings — driving machbus from C or Python when your application is not pure Rust.
• Conformity — exactly what is and is not tested, and where the evidence boundary sits. Read this before you make any claim about a machine built on machbus.

That last page is the honest edge of everything you have built: the track teaches the API and the behavior, and conformity tells you what still stands between a passing demo and a certified machine.

Tutorial overview

Tutorial chapters are organized by job. Each one explains what the workflow is for, what protocol ideas matter, how to test locally, and what can go wrong.

Use Rust first. C and Python notes are included when the surface is available.

Recommended order:

1. Address claim
2. PGN request and NAME management
3. Transport Protocol
4. The service you actually need: VT, TC, FS, diagnostics, NMEA, or SC

Address claim

Address claim is the first thing almost every control function does on an ISOBUS or J1939 network. Before a node may send normal application traffic it has to own a source address — a single byte, 0x00–0xFD, that uniquely identifies it as a message source on the bus. This tutorial explains why that matters, how the negotiation works end to end, and how to drive it with machbus at both the low level and through the session facade.

If you only read one network-management page, read this one: nearly every other workflow (VT, TC, FS, diagnostics) assumes the node has already claimed an address.

Why this exists

A CAN bus has no master and no central address registry. Any node may transmit, and arbitration on the wire decides which frame wins when two start at once. That is fine for moving bytes, but an application needs to know who sent a message and where to send a reply. ISOBUS solves this with two linked ideas:

• a permanent 64-bit identity called the NAME, baked into the product, and
• a temporary 8-bit source address that the node claims at power-up.

Address claim is the handshake that binds one NAME to one address on this particular bus, at this particular time, and resolves the case where two nodes want the same address. Because the address is only a label and the NAME is the real identity, a node can lose an address fight and simply move to another address without changing who it is.

Mental model

power on
   │
   ▼
pick a preferred address  ──►  announce "NAME X wants address A"
   │                                   │
   │                          someone else also wants A?
   │                          ┌────────┴─────────┐
   │                        no│                   │yes → compare NAMEs
   ▼                          ▼                   ▼
 nobody objects          keep A            lower NAME wins A,
 within the window     (Claimed)           higher NAME must move
                                                   │
                                          self-configurable? ─ yes ─► try next free address
                                                   │
                                                   no ─► give up (Cannot claim, address 0xFE)

The whole negotiation is event-driven and bounded by a short waiting window: a node announces its claim, listens for objections for roughly a quarter second, and is considered the owner of the address if nobody with a better NAME contests it.

Anatomy: the NAME

The NAME is a 64-bit value built from a fixed set of fields. machbus represents it as net::Name, constructed with consuming with_* setters. Every field has a meaning that other nodes can read, and the numeric value of the whole 64-bit word is what decides arbitration.

In machbus you build a NAME like this (taken from the address-claim example):

#![allow(unused)]
fn main() {
{{#include ../../../examples/address_claim.rs:14:23}}
}

Two rules matter most when you choose these fields:

1. Uniqueness. Two control functions on the same bus must not share a NAME. The identity number and instance fields exist precisely so that two copies of the same product can coexist. If two nodes really do present identical NAMEs, the bus cannot tell them apart and behavior becomes undefined — design your identity numbers so this never happens.
2. The self-configurable bit is a policy choice. Set it when the node is allowed to pick a different address after losing arbitration. Clear it when the node must own one specific address or nothing.

How arbitration reads the NAME

When two nodes claim the same address, the one with the numerically lower NAME wins. Because the assigned-by-industry fields sit in the most significant bytes while the per-unit identity number sits in the least significant bytes, the comparison is dominated by what the node is before it is decided by which specific unit it is. The practical consequence: arbitration is deterministic and repeatable. The same two NAMEs always produce the same winner, which is what makes the network predictable across power cycles.

You can inspect the raw value with name.raw to reason about who would win a contest, exactly as the example prints it:

#![allow(unused)]
fn main() {
{{#include ../../../examples/address_claim.rs:25:29}}
}

Lifecycle and state machine

A control function moves through a small set of claim states. machbus exposes them as net::ClaimState:

The transitions:

1. Start. The node announces its NAME at its preferred address and opens a short waiting window (the contention timeout is roughly a quarter second).
2. No contest. If the window closes with no better claim seen, the node becomes Claimed and may begin normal traffic.
3. Contest, you win. If another node claims the same address with a higher NAME, you keep the address. The other node must yield.
4. Contest, you lose. If another node claims the same address with a lower NAME, you must stop using it. If your NAME is self-configurable, you retry at the next candidate address; otherwise you go to Cannot claim and announce that from the null address.
5. Request to claim. Any node may ask everyone to re-announce. A claimed node responds by re-sending its current claim; this is how a newcomer learns who owns what.

The two addresses you never claim as a source are the global/broadcast address 0xFF (a destination, not a source) and the null address 0xFE (used as the source only for the “cannot claim” message). machbus exposes these as BROADCAST_ADDRESS and NULL_ADDRESS.

Doing it with machbus

There are two ways to drive address claim, and they suit different needs.

The session facade (recommended for applications)

The Session facade hides the sequencing. You give it a NAME, a preferred address, and a transport; it runs the claim for you and reports the result. The shape is:

#![allow(unused)]
fn main() {
let (ctrl, mut driver) = Session::builder(my_name, 0x80)
    .spawn(EndpointTransport::new(0, endpoint))?;
ctrl.start()?;

while !ctrl.is_claimed() {
    driver.poll()?;
}
println!("owned address: 0x{:02X}", ctrl.address());
}

ctrl.start()? kicks off the claim; pumping driver.poll()? advances the bus and the claim state machine until the node is Claimed. Once ctrl.is_claimed() returns true, ctrl.address() reflects the owned address and you may start sending — application sends made before the claim confirms are rejected, so the ordering is enforced for you. See Getting started for the full builder.

The low-level claimer (for tests and embedded control)

Underneath, net::AddressClaimer drives a single net::InternalCf. You own the timing: you call start, feed in observed claims with handle_claim, and advance time with update. The address-claim example shows a full contention between two nodes that both prefer 0x80:

#![allow(unused)]
fn main() {
{{#include ../../../examples/address_claim.rs:31:56}}
}

The loser, being self-configurable, shifts from 0x80 to 0x81; the winner keeps 0x80. The claimer raises on_address_claimed and on_address_lost events so your application can react to both outcomes.

Events and responsibilities

Whichever API you use, your application is responsible for reacting to the outcome: