ROS2ISOBUS – ROS 2 adapters for ISO 11783 / NMEA 2000

Experimental ROS 2 nodes that translate key parts of the ISO 11783 (ISOBUS) and NMEA 2000 standards into ROS topics and custom messages.

Research and testing only: not AEF‑conformant; cannot be used in commercial products as such.

Based on legacy ISOBUS research code used in earlier projects; ROS 2 adaptation and refactor were assisted by OpenAI Codex/ChatGPT. ISOBUS components have been used e.g. in the robot described in https://doi.org/10.1016/j.ifacol.2022.11.106. TIMClient and VTClient implementations in this repository are fully Codex-generated.

• Authors: Juha Backman et al. (Luonnonvarakeskus / Natural Resources Institute Finland)
• Contact: juha.backman@luke.fi
• License: LGPL-3.0 (see LICENSE), except for separately licensed third-party components described below.
• Change history: CHANGELOG.md

Third-party licensing

• The modified PoolEditParser sources embedded in src/VTClient/pooledit_parser originate from PoolEditParser and retain their GNU GPL version 3-or-later license notices. They are not covered by the repository's LGPL-3.0-only declaration.
• The optional AEF AuthLib and CryptoLib files are not included in version control. When supplied locally and enabled in the build, they remain subject to their own vendor licensing terms and are not covered by this repository's LGPL license.

Overview

• CanBridge (ISO 11783‑3): SocketCAN ↔ ROS bridge for bus_rx/bus_tx frames (29‑bit extended IDs). Docs: src/CanBridge/README.md
• AddressManager (ISO 11783‑5): address claim / request, maintains NAME/SA book. Docs: src/AddressManager/README.md
• Diagnostics (ISO 11783‑12 Annex B minimum): ECU/SW/protocol identification, DM1/DM2/DM3, ISOBUS certification, functionalities, product identification. Docs: src/Diagnostics/README.md
• TECU Class2/Class3 (legacy) Clients (ISO 11783‑7/9): speed/hitch/PTO/guidance/cruise/AUX valve, custom ROS msgs. Docs: src/TECUClient/README.md
• TECU Server (ISO 11783-7/9): configurable tractor-side Class 1, 2 or 3 server using AddressManager and CanBridge. Missing or stale tractor measurements are encoded as the standard not available values. Docs: src/TECUServer/README.md
• TIMClient (AEF TIM): TIM handshake/state machine + TIM function command/status ROS interfaces. Docs: src/TIMClient/README.md
• NMEA2000Client (NMEA 2000): decodes navigation PGNs into ROS measurement topics. Docs: src/NMEA2000Client/README.md
• NMEA2000Server (NMEA 2000): event-driven server that encodes ROS measurements into the corresponding navigation PGNs. Docs: src/NMEA2000Server/README.md
• VTClient (ISO 11783‑6): Virtual Terminal session management, PoolEdit object-pool transfer and runtime updates, ROS event/value interfaces, and AUX-N assignment and input-status routing. Docs: src/VTClient/README.md
• TestPanel: keyboard‑driven debug UI that subscribes to telemetry and can emit either TECU or TIM commands. Docs: src/TestPanel/README.md

Dependencies

• ROS 2 (tested on Jazzy) with rclcpp, sensor_msgs, geometry_msgs, diagnostic_msgs, std_srvs.
• SocketCAN for CAN I/O (canX interface).
• C++17 toolchain, colcon build.
• TIM authentication (auth_mode=AuthLib) requires the proprietary AEF AuthLib (not bundled/open source in general use). AuthLib availability/licensing is handled via AEF/ITK. aef-support@itk-engineering.de.

Building

By default, TIMClient is built with proprietary AuthLib support. This preserves the normal private-repository build and requires the untracked AuthLib and CryptoLib files under third_party/AuthLib and third_party/CryptoLib:

colcon build --packages-select ros2_isobus
source install/setup.bash

To build the complete package without AuthLib, disable the provider at CMake configuration time:

colcon build --packages-select ros2_isobus --cmake-args \
  -DROS2_ISOBUS_ENABLE_AUTHLIB=OFF
source install/setup.bash

This still builds tim_client_node with auth_mode=None and auth_mode=Dummy support. Selecting auth_mode=AuthLib in an AuthLib-disabled build causes the node to stop with a clear configuration error. Reconfigure with -DROS2_ISOBUS_ENABLE_AUTHLIB=ON to restore AuthLib support.

Launching / Running

Bring up SocketCAN (example):

sudo ./start_can.sh # default can0 can be changed by argument

All nodes (legacy Class3 stack):

ros2 launch ros2_isobus all_nodes_class3.launch.py

All nodes with TIM enabled (TECU Class2 + TIM):

ros2 launch ros2_isobus all_nodes_tim.launch.py

All nodes with VT client enabled:

ros2 launch ros2_isobus all_nodes_vt.launch.py

TIM launch uses one shared parameter file for all launched nodes:

• config/all_nodes_tim_params.yaml (installed to share/ros2_isobus/config/all_nodes_tim_params.yaml)
• In that file, update tim_client_node.authlib.* certificate/key paths for your own setup.

Run TIM client with the same parameter file manually:

ros2 run ros2_isobus tim_client_node --ros-args --params-file src/Ros2ISOBUS/config/all_nodes_tim_params.yaml

Individual nodes:

ros2 run ros2_isobus can_bridge_node      # needs CAN interface (default can0)
ros2 run ros2_isobus address_manager_node
ros2 run ros2_isobus diagnostics_node
ros2 run ros2_isobus nmea2000_node
ros2 run ros2_isobus vt_client_node
ros2 run ros2_isobus tecu_node -- --class3 | --class2
ros2 run ros2_isobus tecu_server_node --ros-args --params-file \
  src/Ros2ISOBUS/config/tecu_server.yaml
ros2 run ros2_isobus tim_client_node

Test panel:

ros2 run ros2_isobus test_panel_node
ros2 run ros2_isobus test_panel_node --ros-args -p control_interface:=tim

Key Parameters

• CanBridge: interface (string, default can0), disable_loopback (bool).
• AddressManager: ecu_name_hex, preferred_address.
• Diagnostics: Annex B parameter groups (ecu_*, software_ident_fields, diagnostic_protocol_id, active_dtc_*, previously_active_dtc_*, compliance_*, cf_functionality_*, product_ident_*).
• TECU Class3: command_mode (direct/periodic/both), valve_count.
• TECU Server: tecu_class (1–3), installed-feature parameters, aux_valve_count (0–16), and input_timeout_ms. Physical tractor values are measurement topics rather than parameters.
• TIMClient: auth_mode (None/Dummy/AuthLib), tim.enable_*, tim.aux_*, command_mode (direct/periodic/both).
• NMEA2000 Client: frame_id for published messages. Server: transmit priority (0–7).
• VTClient: xml_file, sa_local, sa_vt, vt_session_timeout_ms, vt_session_retries, vt_aux_n_support, and AUX preferred-assignment options.
• TestPanel: control_interface (tecu/tim).

Contributing

Patches welcome—extend PGN coverage, improve robustness, or add AEF‑compliant behaviours. Please send PRs with clear test notes.