Skip to content

Intro to Car Hardware and Sensor Bring-Up

Overview

Get your autonomous racecar powered on, connected to the network, and streaming sensor data. By the end you will recognize each onboard component, teleoperate the car, and visualize the camera, lidar, and robot state in RViz.

Prerequisites

  • Install WireGuard on your computer by following the WireGuard setup guide
  • Set up your SSH keys for accessing the car by following the SSH key setup guide
  • Install the TurboVNC viewer on your computer by following the VNC guide
  • The car powered off, with a charged battery

Learning Objectives

  • Be able to identify core components and run scripts to interact with the platform
  • Establish an ssh connection over WireGuard to the car
  • Identify major compute, sensing, and actuation subsystems
  • Teleoperate the car
  • View camera, lidar, and robot TF data in RViz

Tutorial

1. Identifying the Physical Components

Familiarize yourself with the main hardware components on the car by reviewing the Hardware Overview documentation.

Important components include:

  1. The onboard computer (NVIDIA Jetson Orin Nano) which runs the Robot Operating System (ROS2) and all autonomy software

    Orin

  2. HDMI display and touchscreen used to monitor system status and interact with the car

    Display

  3. The power system which distributes power from the battery to the various components on the car

    Power Board

  4. Hokuyo LiDAR UST-10LX, which has a 270-degree field of view

    Lidar

  5. IMU (Inertial Measurement Unit) mounted near the center of the car to measure acceleration and angular velocity

    IMU

  6. Raspberry PI camera module 2 with an IMX219 sensor plugged into the CSI port CAM0 of the Jetson Orin

    Camera

  7. The VESC motor driver which controls the throttle and steering actuators on the car

    VESC

  8. The two power switches on the car, the motor enable switch (top) and the master power switch (bottom). The motor enable switch allows power to the motor driver to be enabled or disabled, while the master power switch controls power to the entire vehicle. The motor enable switch should be left in the ON (up) position during normal operation. If you need to quickly stop the car, you can flip the motor enable switch to the OFF (down) position to cut power to the motor driver without turning off the onboard computer.

    Switches

    Note that the top switch enables or disables the motor driver, providing a way to emergency stop the car if it goes out of control without turning off the onboard computer. The bottom switch is the master power switch that controls power to the entire vehicle.

  9. Battery placed properly in the compartment located on the left side of the car

    Battery Compartment

2. Safety

It is critical that you understand the potential safety risks of operating the autonomous racecar platform.

Battery Safety

Your car uses a lithium polymer (LiPo) battery to power the onboard computer and sensors. LiPo batteries can be dangerous if mishandled, overcharged, punctured, shorted, or over-discharged. Always follow these safety guidelines:

  • Never leave the battery unattended while charging or discharging. This means:
    • Do not leave the battery unattended while it is connected to a charger.
    • Do not leave the car unattended while it is powered on.
  • Charge the battery on a non-flammable surface away from flammable materials.

To ensure your car is not left unattended while powered on, it will beep periodically as a reminder. When the battery voltage drops below a safe threshold, the car will emit a continuous alarm until powered off. When this occurs, first shut down the car via the power button on the display or the sudo shutdown -h now command if connected to the car via an SSH session, then flip the master power switch to the off position. When the master power switch is turned off, the car can be left unattended, even if there is a battery plugged in.

Your car uses a 3-cell (called a "3S") LiPo battery. The safe voltage range for the 3S LiPo battery used in the car is 9.6V to 12.6V. The car is designed to protect the battery from over-discharge by monitoring the voltage and alerting the user when the voltage drops below a safe threshold.

Battery Emergency Procedures

LiPo batteries can swell, emit smoke, or catch fire if they are damaged or improperly handled. Should they catch fire, they emit toxic fumes and can be very difficult to extinguish. Therefore, the Battery Safety guidelines must be followed at all times.

Should your battery begin to swell, emit smoke, or catch fire, follow these emergency procedures:

  1. If safe to do so, immediately disconnect the battery from the car.
  2. If safe to do so, move the battery to a safe location, away from flammable materials. If a battery bag is available, place the battery in the battery bag and seal the bag. If possible, place the battery outdoors on a non-flammable surface such as concrete.
  3. Move away from the battery and call emergency services if necessary.

Note that LiPo battery fires cannot be extinguished with water or a standard fire extinguisher. Use a Class D fire extinguisher if available.

3. Charging your Battery

  1. Plug the battery charger into a wall outlet.
  2. Connect the battery to the charger. There is only one way to connect the battery to the charger, so ensure the connectors are aligned properly.
  3. Press and hold the power button on the charger for 2 seconds to start charging. The charger will indicate that the battery is charging by blinking the middle, green color LED.
  4. When the battery is fully charged, the charger will make a chime noise and the middle LED will turn solid green.

Do not leave the battery charging unattended. Should you need to leave, disconnect the battery from the charger first.

Quiz

Complete the graded Car Safety Quiz.

4. Enable your WireGuard VPN

On your laptop, ensure WireGuard is installed and configured with the profile for your car. Then, enable the tunnel. If the tunnel is properly configured and connected, you will see data flowing in both directions.

5. Starting up Your Car

  1. With your charged battery, slide it into the battery compartment with the battery leads facing towards the front of the car. There is no latch for the battery, it should just rest in this slot.
  2. Plug in the battery connector to the power distribution board.
  3. Turn on the master power and wait for the onboard computer (Jetson Orin) to boot.

6. Build your Workspace

The car builds and launches its software with airfield, which wraps each ROS2 package in its own container image. You build the workspace once, and every package container then shares those compiled binaries.

Airfield requires a workspace that has been migrated to it. Check for the scripts/build file and a plans/ folder in ~/roboracer_ws. If your car does not have them, it is still on the older layout and you should follow the container shell instructions below instead. The full airfield reference for this workspace is the Airfield guide.

  1. ssh into your car using the command ssh orin07 (replace 07 with your car number if different).

    Read the SSH guide if you are unfamiliar with SSH.

  2. Change directory into the roboracer_ws folder: 
    cd ~/roboracer_ws
  3. Build the workspace: 
    scripts/build

    Note that scripts/build compiles each package serially into the shared workspace at .airfield/workspace/install. Building one package at a time keeps memory usage low enough for the Orin, which has 8 GB of RAM shared between the CPU and GPU. The first build takes a while; afterwards you only need to rebuild when the source code changes.

You only run this once. There is no container shell to enter first, and no need to build again before every launch.

An alternative: build with the container shell

The car previously used a ./container script and a Makefile. This flow still works if airfield is unavailable or the build above fails.

  1. ssh into your car using the command ssh orin07 (replace 07 with your car number if different).
  2. Change directory into the roboracer_ws folder: 
    cd ~/roboracer_ws
  3. Start the container shell: 
    ./container shell

    If you have questions about the container, read more in the guide on Containers.

  4. Inside the container, build the workspace: 
    make

    Note that make runs the command colcon build --cmake-args -DCMAKE_BUILD_MODE="Hardware". colcon build is the standard way to build the ROS2 workspace, and the additional CMAKE_BUILD_MODE is required to build the correct software packages for the car.

7. Run the Teleoperation Node via SSH

Read the tmux guide if you are unfamiliar with tmux.

These instructions show example commands for car 07. Adjust your commands accordingly if you are working with a different car.

Airfield groups the nodes needed for a task into a plan, and launches that plan as a tmux session with one pane per node. Teleoperation is the teleop plan.

  1. SSH into the car by running the following command in your terminal (ssh orin@10.1.0.107 or if you've configured your ssh and hosts file ssh orin07).
  2. Change directory into the roboracer_ws folder: 
    cd ~/roboracer_ws
  3. Launch the teleop plan: 
    airfield project up teleop

  4. Press the PS button on the PlayStation controller to connect your controller to the car. The light bar on the controller should turn on and stay on (not blinking) once the controller is bound.

    This will open a tmux session with multiple panes. One pane will open for each entry in the plan file ~/roboracer_ws/plans/teleop.yaml: the camera, leg detector, lidar, VESC motor driver, joystick, robot description, the GUI, the VNC desktop, and RViz. Each pane runs in its own container, so a pane whose hardware is missing fails on its own without taking down the rest of the stack.

    Teleop tmux session

    You will also see the GUI launch on the car's display showing the controller inputs. You should see all of the boxes in the GUI turn green if all of the nodes are running correctly and the controller is connected.

    On-car GUI

    Lab Notebook

    Include a photo of the GUI in your lab notebook titled "On-car GUI".

    To drive your car, hold the L1 button. Use the right joystick to control the linear velocity and the left joystick to control the steering angle.

  5. When you are done driving, tear the session down cleanly: 

    airfield project down

Always shut down with airfield project down rather than closing the tmux session. Killing the tmux server leaves the package containers running in the background.

Note that you can also manage the teleop tmux session directly on the car by using the touchscreen GUI.

An alternative: launch teleop with tmuxinator

The car previously launched teleop from a tmuxinator configuration inside the container shell. This flow still works if airfield is unavailable or the plan above fails to launch.

  1. SSH into the car by running the following command in your terminal (ssh orin@10.1.0.107 or if you've configured your ssh and hosts file ssh orin07).
  2. Enter the container shell: 
    cd ~/roboracer_ws
./container shell
  3. Change directory into teleop tmux configuration folder: 
    cd ~/roboracer_ws/tmux/teleop/
  4. Start the teleop tmux session: 
    tmuxinator
  5. Press the PS button on the PlayStation controller to connect your controller to the car, as described above.

This opens a tmux session with one pane for each command in the configuration file ~/roboracer_ws/tmux/teleop/.tmuxinator.yaml.

8. View the Sensors in RViz

The teleop plan you launched in the previous step also starts a remote desktop on the car, with RViz open on it. RViz is the standard ROS tool for looking at sensor data. You open the desktop from your laptop with the TurboVNC viewer, so leave the plan running.

  1. Make sure your WireGuard tunnel is on.

  2. Open the TurboVNC viewer on your laptop and connect to 10.1.0.107:5909 (substitute 07 for your car's id, if different). There is no password.

    TurboVNC Client

  3. You'll see RViz, already set up for this plan. In the middle is a model of your car with its coordinate frames, the red dots around it are the lidar's laser scan, and the camera image is in the panel on the left.

    RViz showing the car, the lidar, the camera, and the TF frames

    If the desktop is there but RViz isn't, give it up to a minute after the plan starts. If it still doesn't appear, see VNC troubleshooting.

Lab Notebook

Include screenshots of RViz showing the camera and lidar in your lab notebook with the title "Sensor Streams in RViz".

9. Validate Sensor Health

You can also check the publishing rate of the lidar and camera in the shell.

  • Check the lidar is publishing at the expected rate (~40 Hz), in your container shell: 

    [docker]:orin@orin06:~/roboracer_ws$ ros2 topic hz /scan
average rate: 39.971
        min: 0.017s max: 0.034s std dev: 0.00190s window: 41
average rate: 39.956
        min: 0.017s max: 0.034s std dev: 0.00138s window: 81
average rate: 39.951
        min: 0.017s max: 0.034s std dev: 0.00114s window: 121

  • Check the camera is publishing images at the expected rate (~30 Hz), in your container shell: 

    [docker]:orin@orin06:~/roboracer_ws$ ros2 topic hz /camera_0/image_raw
average rate: 29.969
        min: 0.031s max: 0.036s std dev: 0.00116s window: 31
average rate: 29.784
        min: 0.029s max: 0.046s std dev: 0.00221s window: 61
average rate: 29.988
        min: 0.027s max: 0.046s std dev: 0.00214s window: 92

  • Inspect the TF tree. In RViz's Displays panel, under TF, open Tree and click the arrows to unfold it. Confirm that camera_frame and laser are both connected to base_link (laser through hokuyo).

The TF tree in RViz: camera_frame and laser under base_link

Lab Notebook

Include screenshots of RViz showing the camera, lidar, and TF tree in your lab notebook with the title "Sensor Streams in RViz".

10. Safe Shutdown

Perform a safe shutdown of the car by closing the GUI and pressing the red power button on the display. Wait for the car to fully power down (the display will turn off) before flipping the master power switch to the off position.

Lab Notebook

Include a photo of the power-off car in your lab notebook titled "Powered-Off Car".