TI mmWave ROS Driver Users Guide

Table of Contents

Purpose

This document exists to aid TI mmWave Evaluation Module (EVM) users who wish to leverage the Robot Operating System (ROS) framework for their applications. ROS allows a standardized platform that makes it easy to do research and prototyping between multiple devices, and with this TI ROS Driver you can have the mmWave sensor communicate with and other ROS enabled device.

Objectives

Prerequisite

Before continuing with this lab, users should first run the Out-Of-Box demo for the EVM. This will enable users to gain familiarity with the sensor’s capabilities as well as the various tools used across all labs in the Radar Toolbox.

Hardware Requirements

The ROS Driver is compatible with the following mmWave Radar EVMs.

Quantity Item Description
1 IWR6843ISK EVM Choose only one EVM
1 IWR6843AOP EVM
1 IWRL6432BOOST EVM No supplemental power needed
1 IWR1843BOOST EVM Requires supplemental power through the DC power jack for CCS based debugging.
1 IWR1642BOOST EVM Requires supplemental power through the DC power jack for CCS based debugging.
1 IWR1443BOOST EVM Requires supplemental power through the DC power jack for CCS based debugging.
1 Micro USB Cable
1 OPTIONAL: Industrial mmWave Carrier Board (ICBOOST) This is needed for Code Composer Studio (CCS) based debugging such as using breakpoints (6843 ONLY)
1 OPTIONAL: 5V 2.5A Power Supply If required for your EVM’s ability to debug.

🛑 IWR6843 ES2.0 Only
This lab is only compatible with ES2.0 version of IWR6843. On ISK or ODS, the device version can be checked on the IWR6843 by using the on-chip device markings as shown below

  1. If line 4 reads 678A, this is an ES2 device. In this case, this lab is compatible with the EVM.
  2. If line 4 reads 60 GHZi, this is an older ES1 device. In this case, the lab is NOT compatible with the EVM. ES2 IWR6843ISK/IWR6843ISK-ODS boards are purchasable from the EVM link above.

On AOP, the EVM must be Rev F or later. This can be distinguished by the shape of the EVM if it is as shown below.

🛑 AoP ES2.0 EVM only
The IWR6843 AoP version of this lab is only compatible with ES2.0 silicon and the corresponding EVM. Ensure that the EVM is the same as in the below image.

Software Requirements

The mmWave ROS Driver has separate packages for ROS1 and ROS2. Only one needs to be built and run.

Host Machine

    git clone https://git.ti.com/git/mmwave_radar/mmwave_ti_ros.git

Compatibility

The ros1_driver ti_mmwave_rospkg source code has been tested with ROS Melodic and ROS Noetic on an x86_64 machine with Ubuntu 18.04 or 20.04. It has also been tested under an Ubuntu LTS VirtualBox Virtual Machine (VM) under Windows 7 and Windows 10. Follow all of the instructions in the Tips for usage with an Ubuntu Virtual Machine section if using an Ubuntu Virtual Machine.

The ros2_driver was tested on Ubuntu 22.04 on a non-VM environment. No issues are expected using a virtual machine for the ROS2 driver.

Why ROS?

The Robot Operating System (ROS) is a flexible framework for writing robot software. It is a collection of tools, libraries, and conventions that aim to simplify the task of creating complex and robust robot behavior across a wide variety of robotic platforms. From a high level perspective the TI mmWave demo binaries provides these functions:

Because the ROS framework and libraries support point cloud data, ROS is useful for developing and prototyping with the mmWave EVMs for robotics applications.

Installing ROS1

Before installing ROS make sure the Ubuntu host machine is working properly. If an Ubuntu virtual machine is being used, the Tips for usage with an Ubuntu Virtual Machine section covers prerequisite steps that should be done before installing ROS. To install ROS1 on a machine follow the instructions provided on the following webpage. Select the full desktop (ros-melodic-desktop-full) version. http://wiki.ros.org/melodic/Installation/Ubuntu After installation, if new to ROS it will be helpful to read and complete the tutorials found at the following link to gain experience with the framework. http://wiki.ros.org/ROS/Tutorials

Installing ROS2

Similar to ROS1, before installing ROS make sure the Ubuntu host machine is working properly. If an Ubuntu virtual machine is being used, the Tips for usage with an Ubuntu Virtual Machine section covers prerequisite steps that should be done before installing ROS.

To install ROS2 on a machine follow the instructions provided on the following webpage. https://docs.ros.org/en/humble/Installation.html After installation, if new to ROS2 it will be helpful to read and complete the tutorials found at the following link to gain experience with the framework. https://docs.ros.org/en/humble/Tutorials.html.

Differing from the ROS1 driver, the message and service files are separated into their own package under the name ti_mmwave_rospkg_msgs. Running colcon build when inside the ros2_driver on the singular src/ folder will build ti_mmwave_rospkg, ti_mmwave_rospkg_msgs, and serial packages.

Using the ti_mmwave_rospkg ROS1 Driver

User Permissions

Your user account must be a member of the “dialout” unix group in order to have access to the serial ports on Linux. To check if you are a member of this group run the “groups” command. If you are already a member of the “dialout” group the output should list “dialout” (in addition to other groups). If you are not a member of the “dialout” group, run the following command to add your user account to that group and then logout and login to Linux to make the change take effect:

$ sudo adduser <your_username> dialout

After executing this command, logout and login to Linux so the change will take effect.

Building the TI mmWave ROS1 Driver

  1. The packages for all ROS labs are held on git.ti.com, and no longer hosted through the toolbox. To download the packages, first ensure that git is installed.

    sudo apt-get install git

  2. Next, clone the git repository from git.ti.com if not done already.

    git clone https://git.ti.com/git/mmwave_radar/mmwave_ti_ros.git

  3. Change directory to the ROS Driver lab. This is the workspace directory.

    cd mmwave_ti_ros/ros1_driver/

  4. Build the lab.

    catkin_make

  5. Source the setup.bash file

    source devel/setup.bash

If all of the installation steps were followed and both ROS environment scripts were sourced, the driver should build successfully and the terminal should print something similar to the following at the end of the output. The terminal output may look slightly different depending on several factors, but should still include “[100%]”.

build Successful 
[100%] Linking CXX executable /home/username/catkin_ws/devel/lib/ti_mmwave_rospkg/ti_mmwave_rospkg
[100%] Built target ti_mmwave_rospkg Scanning dependencies of target ti_mmwave_rospkg_generate_messages
[100%] Built target ti_mmwave_rospkg_generate_messages

Running the ROS1 Driver

  1. Close all previously opened Terminal windows/shells (since they may have old/stale environment variables)

  2. If a brand new TI mmWave EVM is being used, it may come preflashed with an older version of the Out-of-Box Demo. Since the ROS driver is only compatible with binaries listed in the ROS Driver’s bin/ folder’s README, the EVM should be reflashed with the proper binary. The EVM will also need to be reflashed if it has been re-programmed with a different flash image or if there are communication issues. Follow the steps in the How do I reflash the TI mmWave EVM with a binary section to reflash the EVM with the proper binary.

  3. For ICBOOST, make sure the SOP2 jumper on the TI mmWave EVM has been removed or switched to the off position and then power it using the 5VDC power supply (which must be rated for at least 2.5Amps) and connect the EVM via USB (port labeled “XDS110 USB” on the MMWAVEICBOOST) to the host machine.

  4. If using an Ubuntu virtual machine (VM) running under Windows, whenever the mmWave EVM is connected or power-cycled enable the VM to access the mmWave EVM serial ports by going to the Devices menu along the top of the VM window, going to Devices->USB and selecting the Texas Instruments XDS110 option as shown in the picture in the Tips for usage with an Ubuntu Virtual Machine section. This is not necessary for native Linux machines.

  5. Open a new Terminal window/shell. If there are no commands to source the two ROS environment scripts used during the Building the TI mmWave ROS driver section to your ~/.bashrc file, then they should be manually sourced now using the following commands (make sure to change <workspace_dir> to the actual workspace directory):

    ROS1
$ source /opt/ros/melodic/setup.bash
catkin_make
$ source <workspace_dir>/devel/setup.bash

  6. Launch the TI mmWave ROS node and RViz visualizer as follows. Note that the roslaunch command will automatically start a “roscore” ROS master process if there is not one started already.

⚠️ EVM Connection Issues
The EVM must be power cycled or reset when switching from a 3-D configuration to a 2-D configuration (or from 2-D to 3-D). Otherwise, it will produce an error and stop working until it has been power cycled or reset.

After up to 20 seconds the LED (labeled ‘GPIO_2’ on the 6843 EVM) should light up (or pulse off then on if it was already lit up) points should start being displayed in the RViz visualizer window as shown in the pictures in the Visualizing the Data section. To stop the roslaunch command press CTRL-C in the Terminal window.

If the mmWave EVM was not running the proper binary or did not successfully connect to the PC via the default Linux serial ports (/dev/ttyACM0 and /dev/ttyACM1) the command above will produce errors in the Terminal window and no points will show in the RViz visualizer window. Press CTRL-C in the Terminal window to stop the roslaunch command.

In case the EVM was not in a good state, try resetting the EVM by pressing the ‘NRST’ button on the EVM and then run the desired roslaunch command again.

To check that the mmWave EVM is connected and that both COM ports show up, use the command

ll /dev/serial/by-id

from a Linux Terminal window as shown in the following image.

If using the default (/dev/ttyACM0 and /dev/ttyACM1) ports for a different USB device or the TI mmWave EVM is connected to different ports you can open the file <$WORKSPACE>/src/ti_mmwave_rospkg/launch/ti_mmwave_sensor.launch and edit the following lines to use the proper serial ports instead of the default ports:

Setting the serial port <param name=“command_port” value=“/dev/ttyACM0” />

<param name=“data_port” value=“/dev/ttyACM1” />

Setting the serial port with SI Labs transceiver <param name=“command_port” value=“/dev/ttyUSB0” />

<param name=“data_port” value=“/dev/ttyUSB1” />

See the Frequency Asked Questions section for more troubleshooting hints if needed.

When running the demo in multi-EVM mode the offset and position of the EVM relative to the other needs to be set. The launch files utilize a static_transform_publisher to keep track of 3D coordinates over time. static_transform_publisher x y z yaw pitch roll frame_id child_frame_id period_in_ms X, Y and Z refer to the offset position of the sensor in meters. Yaw, pitch and roll refer to the angle offset of the sensor in radians (yaw is rotation about Z, pitch is rotation about Y and roll is rotation about X). The period in milliseconds specifies how often to send a transform (100 ms = 10 Hz). Set these arguments relative to one another for each of the sensors. For example, use multi_<sensor>_0 as the baseline (0 0 0 0 0 0) and update the arguments in multi_<sensor>_1 to describe the position of the second sensor relative to the baseline sensor.

To display the axes, add the axes feature to the map as shown below. This enables the axes display located at the origin of the target frame, red - x green - y blue -z

Visualizing the Data on ROS1

Once the sensor is running, the point cloud will be displayed in the RViz visualizer window. The previous roslaunch command will automatically launch RViz, but it can also be launched manually if needed using the following command in a new Terminal window/shell (after sourcing the ROS environment scripts).

$ rosrun rviz rviz

The previous roslaunch command loads a default RViz configuration but feel free to modify the visualization settings in the RViz window as desired. The PointCloud2 point size and shape can be changed by setting the Size (m) parameter and Style parameter. The points can be colored based on elevation (used by default in the 3-D configurations) or by intensity (used by default in the 2-D configurations). Changing the Decay option to a non-zero value will cause RViz to accumulate and display points over a specified number of seconds (it is set to 0.25 sec in the provided default configurations). Try changing this parameter and note the change in the displayed output.

The following figure shows an example RViz window for the 6843 or 6843AOP sensor in a 2D configuration. The initial perspective is a top-down (bird’s eye) view with the sensor at the top-middle of the grid facing downward. The color of each point represents the intensity of the reflection where dark blue represents the lowest intensity points displayed and white represents the highest intensity points being displayed. This is configurable in the RViz settings for the PointCloud2.

ROS1 ti_mmwave_rospkg Details

This node is a nodelet manager which is loaded with the two nodelets listed below when initiated. It must be instantiated with the parameters listed below.

Parameters
command_port : Linux port used for the mmWave User UART port
command_rate: Baud rate for the command_port (115200)
data_port: Linux port used for the mmWave Data UART port
data_rate: Baud rate for the data_port (921600)

mmWaveCommSrv Nodelet
This nodelet provides the mmWave UART Command Line Interface as a ROS Service.

mmWaveDataHdl Nodelet
This nodelet reads and sorts the incoming radar data from the mmWave EVM.

mmWaveQuickConfig

This node will read a user specified radar chirp profile line-by-line and send each line to the mmWaveCommSrv nodelet to configure the mmWave EVM.

Services

mmWaveCLI

Requests

Std_msgs::String comm

Response

Std_msgs::String resp

Messages

Sensor_msgs::PointCloud2
/mmwaveDataHdl/RScan

Using the ti_mmwave_rospkg ROS2 Driver

User Permissions

Your user account must be a member of the “dialout” unix group in order to have access to the serial ports on Linux. To check if you are a member of this group run the “groups” command. If you are already a member of the “dialout” group the output should list “dialout” (in addition to other groups). If you are not a member of the “dialout” group, run the following command to add your user account to that group and then logout and login to Linux to make the change take effect:

$ sudo adduser <your_username> dialout

After executing this command, logout and login to Linux so the change will take effect.

Building the TI mmWave ROS2 Driver

  1. The packages for all ROS labs are held on git.ti.com, and no longer hosted through the toolbox. To download the packages, first ensure that git is installed.

    sudo apt-get install git

  2. Next, clone the git repository from git.ti.com if not done already.

    git clone https://git.ti.com/git/mmwave_radar/mmwave_ti_ros.git

  3. Change directory to the ROS Driver lab. This is the workspace directory.

    cd mmwave_ti_ros/ros2_driver/

  4. Build the lab.

    colcon build

  5. Source the setup.bash file

    source install/setup.bash

    Note you might run into some warnings. Currently these are expected and will not affect the driver’s compatibility or performance. You will know if the building has been successful if the terminal output mentions three finished packages with none of them being aborted. They might mention having stderr output but that is currently okay as long as all three packages finish.

    Starting >>> serial  
Starting >>> ti_mmwave_rospkg_msgs
Finished <<< serial [0.52s]                                                                          
Finished <<< ti_mmwave_rospkg_msgs [1.39s]                     
Starting >>> ti_mmwave_rospkg
Finished <<< ti_mmwave_rospkg [0.49s]                    

Summary: 3 packages finished [2.32s]

Running the ROS2 Driver

  1. Once the ROS2 Driver is built, Close all previously opened Terminal windows/shells (since they may have old/stale environment variables)

  2. If a brand new TI mmWave EVM is being used, it may come preflashed with an older version of the Out-of-Box Demo. Since the ROS2 driver is only compatible with binaries listed in the ROS Driver’s bin/ folder’s README, the EVM should be reflashed with the proper binary. The EVM will also need to be reflashed if it has been re-programmed with a different flash image or if there are communication issues. Follow the steps in the How do I reflash the TI mmWave EVM with a binary section to reflash the EVM with the proper binary.

  3. For ICBOOST, make sure the SOP2 jumper on the TI mmWave EVM has been removed or switched to the off position and then power it using the 5VDC power supply (which must be rated for at least 2.5Amps) and connect the EVM via USB (port labeled “XDS110 USB” on the MMWAVEICBOOST) to the host machine.

  4. If using an Ubuntu virtual machine (VM) running under Windows, whenever the mmWave EVM is connected or power-cycled enable the VM to access the mmWave EVM serial ports by going to the Devices menu along the top of the VM window, going to Devices->USB and selecting the Texas Instruments XDS110 option as shown in the picture in the Tips for usage with an Ubuntu Virtual Machine section. This is not necessary for native Linux machines.

  5. Open a new Terminal window/shell. If there are no commands to source the two ROS environment scripts used during the Building the TI mmWave ROS driver section to your ~/.bashrc file, then they should be manually sourced now using the following commands (make sure to change <workspace_dir> to the actual workspace directory):

    $ source /opt/ros/humble/setup.bash
$ source <workspace_dir>/install/setup.bash

  6. Navigate to the launch directory within <workspace_dir>/src/ti_mwave_rospkg/launch/

  7. Open the launch file of your choice in a text editor

  8. Change the path parameter to match where the configuration file is located within your workspace directory, and save.

  9. To run the launch file you have now edited, make sure your terminal is in the <workspace_dir>/src/ti_mwave_rospkg/launch/ directory. Then run the following command in the pattern of ros2 launch <launch_file>.py

Visualizing the Data on ROS2

Once the sensor is running, the point cloud will be displayed in the rviz2 visualizer window. The launch file includes lines that will automatically launch rviz2 with a preset config, but it can also be launched manually if needed using the command rviz2 in a new Terminal window/shell (after sourcing the ROS environment scripts).

The previous roslaunch command loads a default RViz configuration but feel free to modify the visualization settings in the RViz window as desired. The PointCloud2 point size and shape can be changed by setting the Size (m) parameter and Style parameter. The points in the can be colored by intensity. In the default rviz2 config that launches with all mmWave ROS2 launch files, red points symbolize low SNR close to the threshold and green is high SNR from a reflective object. This coloring gradient can be changed by adjusting values in the rviz.rviz file which is in the launch. Changing the decay option to a non-zero value will cause RViz to accumulate and display points over a specified number of seconds (it is set to 0.25 sec in the provided default configurations). Try changing this parameter and note the change in the displayed output.

ROS2 ti_mmwave_rospkg Details

⚠️ ROS2 LAUNCH FILES
When running one of the ti_mmwave_rospkg launch files for the first time, make sure you first edit the “path” parameter to match the path of where your workspace is so that the configuration file of choice can be found and sent to the device

Parameters
path: Path to configuration file that will be sent to the device
device: Four digit mmWave sensor name
name: “/mmWaveCLI”
command_port : Linux port used for the mmWave User UART port
command_rate: Baud rate for the command_port (115200)
data_port: Linux port used for the mmWave Data UART port
data_rate: Baud rate for the data_port (921600)
my_package_dir: get_package_share_directory(‘ti_mmwave_rospkg’)

ti_mmwave_rospkg_msgs
Separate package defined to have the msg and srv files.

mmWaveCommSrv Node
This node provides the mmWave UART Command Line Interface as a ROS Service.

ParameterParser Node
This node reads the configuration file sent to the mmWave device and does calculations of several useful chirp design parameters.

  1. Number of Range Samples
  2. Number of Chirps
  3. End Frequency
  4. Bandwidth
  5. Max Range
  6. Range Resolution
  7. Max Doppler Speed
  8. Doppler Resolution

DataHandlerClass Node
This component reads and sorts the incoming radar data from the mmWave EVM.

mmWaveQuickConfig
This node will read a user specified radar chirp profile line-by-line and send each line to the mmWaveCommSrv node to configure the mmWave EVM.

Frequently Asked Questions (FAQ)

Tips for usage with an Ubuntu Virtual Machine

Here are some tips when using ROS and the TI mmWave ROS driver with an Ubuntu Virtual Machine (VM).

Steps for Starting Virtual Machine

Instructions are for 18.04 but also works with 20.04

I see “Failed to open User serial port with error: IO Exception (2): No such file or directory, file ~/mmwave_ti_ros/ros_driver/src/serial/src/impl/unix.cc, line 151.”

I see “not recognized as a CLI command” errors when I start the driver

Error Message “mmWaveCommSrv: Received response from sensor: ‘clutterRemoval 0 ’clutterRemoval’ is not recognized as a CLI command”

I see serial port errors when I start the driver or I do not see the mmWave EVM serial ports at /dev/ttyACM0 and /dev/ttyACM1

How do I ensure the EVM is properly configured

Make sure the correct binary was flashed in the device’s flashing mode, then set back to functional mode. The EVM Setup Operational Modes within the Hardware Guides section of the Radar Toolbox covers all modes

What binary do I flash to my mmWave Evaluation Module

Within the driver’s bin/ folder located at <MMWAVE_ROS_DRIVER_INSTALL_DIR>/ros1_driver/src/ti_mmwave_rospkg/bin/ is a set of binary files and the text document README.txt. This text document lists out all supported EVMs and compatible binaries.

How do I Reflash the TI mmWave EVM with a binary

A brand new TI mmWave EVM comes with a preflashed and older version of the Out-of-Box Demo. Since the ROS driver is only compatible with the binaries listed in the ROS Driver bin/ folder text document, the EVM should be reflashed with the proper binary. The EVM will need to be flashed again if it has been re-programmed with a different flash image or if you are running into issues. The following steps can be used to reflash the EVM.

  1. Download Uniflash, TI’s flashing software, via the following link: https://www.ti.com/tool/UNIFLASH
  2. Make sure the file “/lib/x86_64-linux-gnu/libudev.so.0” exists. If it does not exist execute the following command to generate a symbolic link necessary for Uniflash to work:
$ sudo ln -sf /lib/x86_64-linux-gnu/libudev.so.1 /lib/x86_64-linux-gnu/libudev.so.0
  1. Navigate to the download directory, make the file executable and run the Uniflash installer:
$ cd ~/Downloads
$ chmod +x uniflash_sl.4.2.1.1562.run
$ ./uniflash_sl.4.2.1.1562.run

Note: The Uniflash executable filename may differ once a newer version becomes available

  1. Download the Linux version of the mmWave SDK (required version listed in the ROS Driver release notes) via the following link: https://www.ti.com/tool/MMWAVE-SDK
  2. Install the following mmWave SDK dependency:
$ sudo apt-get install libc6:i386
  1. Navigate to the download directory, make the file executable and run the mmWave SDK installer (change “” to the proper version):
$ cd ~/Downloads
$ chmod +x mmwave_sdk_<ver>-Linux-x86-Install.bin
$ ./mmwave_sdk_<ver>-Linux-x86-Install.bin
  1. Make sure there is no power to the mmWave EVM and place a jumper on the SOP2 header
  2. Run Uniflash to see the following screen:

Click mmWave and in the list select your device.

  1. Specify the following flash image: For xWR6843AOP EVM:

Meta Image 1: <MMWAVE_ROS_DRIVER_INSTALL_DIR>/ros1_driver/src/ti_mmwave_rospkg/bin/xwr64xxAOP_mmw_demo.bin OR <MMWAVE_SDK3_INSTALL_DIR>/packages/ti/demo/xwr64xx/mmw/xwr64xxAOP_mmw_demo.bin

For xWR6843ISK/ODS EVM:

Meta Image 1: <MMWAVE_ROS_DRIVER_INSTALL_DIR>/ros1_driver/src/ti_mmwave_rospkg/bin/small_obstacle_detection_68xx.bin

  1. Supply power and connect the mmWave EVM to the computer with a microUSB cable

  2. Check that the mmWave EVM is connected and that both COM ports show up using the command “ll /dev/serial/by-id” from a Linux Terminal window as shown in the following image.

  3. On the left-hand pane in Uniflash, select Settings and Utilities. Enter the serial port corresponding to the first COM port (typically /dev/ttyACM0)

  4. Select Program in the left-hand pane and then click the “Load Images” button. When finished, the console should report “Program Load completed successfully” as in the following image.

Note: If Uniflash stops responding after clicking “Load Images”, re-start it and make sure EVM is power cycled after Uniflash is started.

  1. After Uniflash has finished flashing the device remove the power supply, remove the SOP2 jumper and reapply power to the EVM.

How do I edit the cfg file