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