AgIsoStack++ Documentation

AgIsoStack++ is a platform-independent, open-source C++11 library designed to implement the ISO-11783 (ISOBUS) standard for agricultural machinery communication over CANbus networks. It provides a transparent interface that allows developers to focus on application logic rather than the complexities of the ISOBUS standard.

Key capabilities include:

• Virtual Terminal (VT) Client: Implementation of the Universal Terminal.
• Auxiliary Control (AUX-N): Support for auxiliary functions.
• Task Controller (TC): Both Client and Server implementations.
• ISOBUS Shortcut Button (ISB): Support for shortcut functionality.
• NMEA 2000: Support for Fast Packet Protocol.
• Guidance & Speed: Common guidance and speed messaging.
• Hardware Abstraction: Drivers for many common CAN controllers.

AgIsoStack++ is designed to accommodate various hardware, but official support for building from source is limited to the following platforms:

• Ubuntu Linux (Non-WSL)
• Raspberry Pi OS (Raspbian)
• RHEL
• Windows
• MacOS
• ESP32

Note on WSL: Windows Subsystem for Linux (WSL) is not supported because the WSL kernel does not support socket CAN by default. While recompiling the WSL kernel might enable socket CAN, it is not an officially supported use case.

An ISOBUS Shortcut Button (ISB) is a physical or logical button that an operator can press to simultaneously command all implements to stop their current operations, functioning similarly to an emergency stop.

In the context of the AgIsoStack++ library, the ISB interface handles the parsing and sending of the "Stop implement operations" message (associated with SPN 5140).

Key Requirements:

• Receiving: If your application performs implement operations, you are highly advised (and often required for ISOBUS certification) to receive this message so your application can transition to a safe state.
• UI Reflection: If you are using the ISB interface and have a VT (Virtual Terminal) object pool, you must reflect the ISB state on your home screen.
• Sending: Any control function connected to the implement bus may send this message at its discretion.

The Device Descriptor Object Pool (DDOP) is a collection of objects uploaded from an implement to a Task Controller during the connection process. It serves as the authoritative source of implement geometry and capabilities, describing things like the number of sections, section widths, and product types.

• TC Clients: Must create a DDOP to describe the implement to the TC.
• TC Servers: Receive DDOPs from client implements and must interpret them to understand the implement's capabilities.

The Task Controller (TC) is a core component responsible for recording and planning data. It acts as the interface for operators to schedule tasks for implements to execute, enabling automated precision for activities like precision farming.

Architecture

The Task Controller follows a client-server model, similar to the Virtual Terminal:

• Server: Responsible for scheduling tasks.
• Client: Responsible for executing the tasks scheduled by the server.

Data Logger (DL) Distinction

A Control Function that is registered as a Task Controller but is specifically defined to perform data logging functionality is referred to as a Data Logger (DL).

AgIsoStack++ provides a framework for building ISOBUS Electronic Control Units (ECUs) that control agricultural implements (e.g., seed drills or sprayers). A typical implementation involves several layers:

1. Hardware Interface: Implementing a CAN-based interface to communicate on the physical bus.
2. Control Functions: Setting up internal functions to receive commands and external functions to command other modules.
3. Virtual Terminal (VT) Client: Implementing a VT client to send an ISO Object Pool (IOP) file to a tractor's display, allowing the operator to interact with the implement via the cab screen.
4. Task Controller (TC) Client: Implementing a TC client to receive tasking jobs (e.g., field maps or prescription data).
5. Application Logic: Developing the core logic that uses the TC job and VT commands to drive the implement hardware.

The ISOBUS module architecture is divided into three primary layers:

1. Hardware API: Handles the CAN transceiver driver and raw CAN frames.
2. Networking API: Manages Control Functions (listening to and sending data) and transport protocols for message handling.
3. Application: The user-level code where you implement logic to handle received data and send outgoing messages.

This separation allows the stack to abstract away specific hardware implementations (like SocketCAN) from the high-level ISOBUS networking logic.

A Task Controller (TC) is an ISO11783-10 standard control function used to log and control implement functions. It manages task data, including task boundaries, coverage maps, and geospatial status.

Key responsibilities of a TC include:

• Using geospatial data to plan and command variable rate prescription tasks.
• Providing section control to prevent over-application in already covered areas.

Communication between the TC and the implement follows a stateful protocol where the TC sends commands/requests and the implement sends status updates. AgIsoStack abstracts much of this communication logic.

The Virtual Terminal (VT), sometimes referred to as a Universal Terminal (UT), follows a client-server architecture to allow an operator to control various implements through a single interface.

• The Client: The application that determines what content is displayed. It typically runs on the implement.
• The Server: The application that displays the client's content. It typically runs on the tractor.

Because the client and server are separate applications, they are almost always hosted on separate devices.

The callback mechanism used for standard CAN messages also handles multi-frame Transport Protocol (TP) and Extended Transport Protocol (ETP) messages.

If a message is sent via BAM (Broadcast Announce Message) and exceeds the standard single-frame size, the stack reassembles the frames and delivers the complete payload to your registered callback. This allows you to receive messages of any size and any PGN using the same interface used for single-frame messages.