Skip to content

Split driver stack setup into ROS 2 Jazzy and Humble paths - #84

Open
MLN-MNJ wants to merge 1 commit into
f1tenth:mainfrom
MLN-MNJ:jazzy-noble-driver-stack
Open

Split driver stack setup into ROS 2 Jazzy and Humble paths#84
MLN-MNJ wants to merge 1 commit into
f1tenth:mainfrom
MLN-MNJ:jazzy-noble-driver-stack

Conversation

@MLN-MNJ

@MLN-MNJ MLN-MNJ commented Aug 27, 2026

Copy link
Copy Markdown
Collaborator

The driver stack page documents only Ubuntu 22.04 with ROS 2 Humble. Humble has no
Ubuntu 24.04 build and never will — the buildfarm only produces Jammy packages for it,
and it reaches EOL in May 2027 without ever targeting Noble. Jetsons on JetPack 7
(L4T R39, Ubuntu 24.04) therefore need Jazzy, and there is currently nothing in the docs
for them.

Section 2 now splits into two self-contained pages, and the reader follows only the one
matching their JetPack version:

2. RoboRacer Driver Stack Setup
   ├── 1. Ubuntu 24.04 - ROS 2 Jazzy     (JetPack 7)
   └── 2. Ubuntu 22.04 - ROS 2 Humble    (JetPack 5-6)

Both cover the same seven steps in the same order, so there is no cross-referencing
between them mid-procedure.

Pages

File What it is
drive_workspace.rst Reduced to a chooser — a JetPack → Ubuntu → ROS 2 table plus the notes explaining why Jazzy needs a patch and when a Humble container is the better call. Keeps the doc_drive_workspace, lidar_setup and doc_firmware_hokuyo10 labels so the existing references from faq.rst and the Docker page still resolve.
drive_workspace_jazzy.rst New. Noble apt repository setup, the CMake patch, and why the F710 udev rule is obsolete under Jazzy.
drive_workspace_humble.rst New, but content-preserving — the existing Humble procedure, including the F710 udev rule and the D/X product-id note from #80.

The one substantive Jazzy difference

f1tenth_system has no Jazzy branch — the repo offers foxy-devel, humble-devel,
melodic and braking, and the vesc / ackermann_mux submodules stop at humble
and master. Every apt dependency the stack needs is already released for Jazzy, so the
documented procedure is to clone humble-devel and patch it:

  • vesc_driver, vesc_ackermann and ackermann_mux pin CMAKE_CXX_STANDARD 14, but
    Jazzy's rclcpp, serial_driver and diagnostic_updater require C++17.
  • The same packages declare cmake_minimum_required(VERSION 3.5), which CMake 3.28 on
    Noble deprecates loudly and CMake 4 rejects outright.

The page is explicit that a ros:humble-ros-base container is the better choice for any
car that has to interoperate with f1tenth_gym_ros or f1tenth_labs, since those are
Humble-targeted too. The native port is recommended only for a standalone vehicle.

Fixes that apply to both distributions

  • udevadm trigger needs --action=add. A bare udevadm trigger fires a change
    event while the rules match ACTION=="add", so it silently does nothing and the
    symlink never appears. The old page said sudo udevadm trigger, which meant the VESC
    symlink would not show up until an unrelated reboot or replug.
  • SICK LiDAR section expanded with nmcli setup for headless installs, the 2111 /
    2112 service-port check, the scanner_type mismatch failure mode (the node connects
    and then fails during scan configuration), and a standalone sick_generic_caller
    test with the expected 15 Hz / 270° / 0.33° scan so the LiDAR can be isolated from the
    rest of the stack.
  • A joypad section, which the docs did not previously have: the F710 as the reference
    pad, the 8BitDo Ultimate 2C deadman indices (6 and 8, not 4 and 5), how to read
    indices off /joy for any other pad, and the mandatory rebuild — f1tenth_stack is an
    ament_python package, so config/ and launch/ are copied into install/, not
    symlinked, and editing the source alone changes nothing at runtime.

drive_manual.rst gains a pre-drive checklist to run with the car on a stand, and the
/joy/teleop/ackermann_drive chain for locating where teleop stops, plus the
note that jstest and joy_node indices disagree because joy uses SDL2 while jstest
reads raw joydev.

Provenance

Everything on the Jazzy page was written while setting up an actual JetPack 7 car — the
CMake patch, the --action=add behaviour, the ping cap_net_raw quirk and the
--symlink-install failure are all things that were hit and worked through, not
inferred from release notes.

Checks

sphinx-build -W --keep-going -b html produces no new warnings — output is identical
to the current main baseline, and every :ref: resolves.

One note unrelated to this PR: main currently emits 9 Duplicate explicit target name: "here" warnings from index.rst, faq.rst, software_host.rst and gap_finding.rst
when built against current docutils. CI last ran green in July, but requirements.txt is
unpinned, so the strict build may now fail on main for reasons predating this branch.
Happy to fix those in a separate PR — it's ___ on the affected links.

The driver stack page documented only Ubuntu 22.04 with ROS 2 Humble, which
has no build for Ubuntu 24.04 and never will. Jetsons on JetPack 7 (L4T R39,
Noble) need Jazzy, so section 2 now splits into two self-contained pages and
the reader follows only the one matching their JetPack version.

drive_workspace.rst becomes a short chooser: a JetPack -> Ubuntu -> ROS 2
table, and notes explaining why the Jazzy path needs a patch and when a
Humble container is the better option. It keeps the doc_drive_workspace,
lidar_setup and doc_firmware_hokuyo10 labels so existing cross-references
from faq.rst and the Docker page still resolve.

drive_workspace_jazzy.rst is new and covers the Noble apt repository, the
CMAKE_CXX_STANDARD 14 -> 17 and cmake_minimum_required 3.5 -> 3.16 patch
f1tenth_system needs to build against Jazzy, and why the F710 udev rule is
obsolete now that the joy node uses SDL2 and device_id.

drive_workspace_humble.rst preserves the existing Humble procedure,
including the F710 udev rule and the D/X product-id note.

Both pages also pick up fixes that are not distribution specific:

- udevadm trigger needs --action=add. A bare trigger fires a change event
  while the rules match ACTION=="add", so it silently does nothing and the
  symlink never appears.
- The SICK section gains the nmcli setup for headless installs, the 2111 and
  2112 port check, the scanner_type mismatch failure mode, and a standalone
  sick_generic_caller test with the expected 15 Hz / 270 deg / 0.33 deg scan.
- A joypad section covering the F710, the 8BitDo Ultimate 2C deadman indices
  (6 and 8 rather than 4 and 5), reading indices off /joy for any other pad,
  and the mandatory rebuild after editing config or launch files.

drive_manual.rst gains a pre-drive checklist to run with the car on a stand
and the /joy -> /teleop -> /ackermann_drive chain for locating where teleop
stops, plus the jstest and joy_node index disagreement caused by SDL2.

sphinx-build -W is clean; this change adds no new warnings.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant