3. F1TENTH Driver Stack Setup with Docker Containers

Equipment Required:

  • Fully built F1TENTH vehicle

  • Pit/Host computer OR

  • External monitor/display, HDMI cable, keyboard, mouse

Approximate Time Investment: 1.5 hour

Warning

Before you proceed, this specific section goes over how to set up the driver stack in Docker Containers if you have Jetsons before Xavier, or JetPack versions before 5.0 and wish to use ROS 2. For JetPack versions 5.0 and above on Jetson Xaviers and above, go to Driver Stack Setup and follow the instructions there.

Overview

We use Docker to containerize the software stack. You can find a tutorial on basic Docker concepts here. We’ll also utilize nvidia-docker to use the GPU onboard inside containers. Both of these dependencies should already come with JetPack after you’ve flashed your Jetson.

We use ROS 2 Foxy for communication and run the car. You can find a tutorial on ROS 2 here.

In the following section, we’ll go over how to set up the drivers for sensors and the motor control:

  1. Setting up udev rules for our sensors.

  2. Setting up docker containers and the driver stack.

  3. Launch teleoperation and the LiDAR.

Everything in this section is done on the Jetson NX so you will need to connect to it via SSH from the Pit laptop or plug in the monitor, keyboard, and mouse.

1. udev Rules Setup

When you connect the VESC and a USB lidar to the Jetson, the operating system will assign them device names of the form /dev/ttyACMx, where x is a number that depends on the order in which they were plugged in. For example, if you plug in the lidar before you plug in the VESC, the lidar will be assigned the name /dev/ttyACM0, and the VESC will be assigned /dev/ttyACM1. This is a problem, as the car’s configuration needs to know which device names the lidar and VESC are assigned, and these can vary every time we reboot the Jetson, depending on the order in which the devices are initialized.

Fortunately, Linux has a utility named udev that allows us to assign each device a “virtual” name based on its vendor and product IDs. For example, if we plug a USB device in and its vendor ID matches the ID for Hokuyo laser scanners (15d1), udev could assign the device the name /dev/sensors/hokuyo instead of the more generic /dev/ttyACMx. This allows our configuration scripts to refer to things like /dev/sensors/hokuyo and /dev/sensors/vesc, which do not depend on the order in which the devices were initialized. We will use udev to assign persistent device names to the lidar, VESC, and joypad by creating three configuration files (“rules”) in the directory /etc/udev/rules.d.

First, as root, open /etc/udev/rules.d/99-hokuyo.rules in a text editor to create a new rules file for the Hokuyo. Copy the following rule exactly as it appears below in a single line and save it:

KERNEL=="ttyACM[0-9]*", ACTION=="add", ATTRS{idVendor}=="15d1", MODE="0666", GROUP="dialout", SYMLINK+="sensors/hokuyo"

Next, open /etc/udev/rules.d/99-vesc.rules and copy in the following rule for the VESC:

KERNEL=="ttyACM[0-9]*", ACTION=="add", ATTRS{idVendor}=="0483", ATTRS{idProduct}=="5740", MODE="0666", GROUP="dialout", SYMLINK+="sensors/vesc"

Then open /etc/udev/rules.d/99-joypad-f710.rules and add this rule for the joypad:

KERNEL=="js[0-9]*", ACTION=="add", ATTRS{idVendor}=="046d", ATTRS{idProduct}=="c219", SYMLINK+="input/joypad-f710"

Finally, trigger (activate) the rules by running

sudo udevadm control --reload-rules
sudo udevadm trigger

Reboot your system, and you should find three new devices by running

ls /dev/sensors

and:

ls /dev/input

If you want to add additional devices and don’t know their vendor or product IDs, you can use the command

sudo udevadm info --name=<your_device_name> --attribute-walk

making sure to replace <your_device_name> with the name of your device (e.g. ttyACM0 if that’s what the OS assigned it. The Unix utility dmesg can help you find that). The topmost entry will be the entry for your device; lower entries are for the device’s parents.

2. Setting up the Driver Stack inside a Container

First, clone the repo in a convenient place (we’ll be using the home directory)

cd
git clone https://github.com/f1tenth/f1tenth_system.git

Next, run the script run_container.sh in the scripts directory in the repo. This pulls the pre-built image built for the car with ROS 2, and will create a persistent container on your car.

cd f1tenth_system/scripts
./run_contaianer.sh

You can find more details on how the drivers are set up in the README of the f1tenth_system repo.

If you need multiple bash sessions into the container, you can use tmux, which is included in the docker image. See a quick start guide on tmux.

Starting the container will also bind mount a ROS 2 workspace f1tenth_ws created in the car’s home directory.

3. Launching Teleop and Testing the LiDAR

This section assumes that the lidar has already been plugged in (either to the USB hub or to the ethernet port). If you are using the Hokuyo 10LX or a lidar that is connected via the ethernet port of the Orbitty, make sure that you have completed the Hokuyo 10LX Ethernet Connection section before preceding.

Before the bringup launch, you’ll have to set the correct parameters according to which LiDAR you’re using in the params file sensors.yaml. Depending on how you’ve set up docker, you might need root access to write to files in f1tenth_ws since it’s shared between the host and the container. All parameter files are located in the following location on your host:

$HOME/f1tenth_ws/src/f1tenth_system/f1tenth_stack/config/

And

/f1tenth_ws/src/f1tenth_system/f1tenth_stack/config/

In the container.

  1. If you’re using an ethernet based LiDAR, set the ip_address field to the corresponding ip address of your LiDAR.

  2. If you’re using a USB based LiDAR, comment out the ip_address field, and uncomment the line with the serial_port field. And set the value to the correct udev name from udev rules set up.

In your running container, run the following commands to source the ROS 2 underlay and our workspace’s overlay:

source /opt/ros/foxy/setup.bash
source /f1tenth_ws/install/setup.bash

Then, you can launch the bring up with:

ros2 launch f1tenth_stack bringup_launch.py

Running the bringup launch will start the VESC drivers, the LiDAR drivers, the joystick drivers, and all necessary packages for running the car. To see the LaserScan messages, in a new bash session inside the container, run

source /opt/ros/foxy/setup.bash
source /f1tenth_ws/install/setup.bash
rviz2

The rviz window should show up. Then you can add a LaserScan visualization in rviz on the /scan topic.