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
- Bring up ROS on a Linux machine
- Build the ti_mmwave_rospkg package in the ROS workspace
- Launch the ti_mmwave_rospkg node to start the mmWave EVM
- Visualize the Radar point cloud using RViz
- Reconfigure the mmWave EVM with mmWaveQuickConfig node (optional)
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
- If line 4 reads
678A
, this is an ES2 device. In this case, this lab is compatible with the EVM.- 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
- Ubuntu 18.04 or 20.04 LTS operating system (native Linux machine preferred but will also work with Linux virtual machine running under Windows 7/Windows 10)
- ROS Melodic for 18.04 or ROS Noetic for 20.04
- ROS Humble for ROS2 on any supported operating system. Refer to the ROS Humble documentation for a full list of compatible operating systems.
- Source code from ti_mmwave_rospkg repository
Download Link for mmWave ROS Driver
- The mmWave ROS Driver with ti_mmwave_rospkg package can be downloaded by cloning the public repository.
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:
- Be able to specify desired FMCW Radar chirp profile through command line interface (CLI) on a UART port
- Do 1D, 2D, CFAR, Azimuth and Elevation processing and stream out intensity, relative radial velocity and three spatial coordinates (x,y,z) of the detected objects in real-time.
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
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
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
Change directory to the ROS Driver lab. This is the workspace directory.
cd mmwave_ti_ros/ros1_driver/
Build the lab.
catkin_make
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
Close all previously opened Terminal windows/shells (since they may have old/stale environment variables)
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.
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.
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.
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
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.
- For the TI mmWave 6843AOP or 6443 EVM use one of the following commands:
3-D configuration with elevation info:
$ roslaunch ti_mmwave_rospkg 6843AOP_multi_3d_0.launch
To add the second EVM in 3-D configuration, open a new terminal and enter the command:
$ roslaunch ti_mmwave_rospkg 6843AOP_multi_3d_1.launch
2-D configuration without elevation info:
$ roslaunch ti_mmwave_rospkg 6843AOP_multi_2d_0.launch
To add the second EVM in 2-D configuration, open a new terminal and enter the command:
$ roslaunch ti_mmwave_rospkg 6843AOP_multi_2d_1.launch
- For the TI mmWave 6843 EVM use one of the following commands:
3-D configuration with elevation info:
$ roslaunch ti_mmwave_rospkg 6843_multi_3d_0.launch
To add the second EVM in 2-D configuration, open a new terminal and enter the command:
$ roslaunch ti_mmwave_rospkg 6843_multi_3d_1.launch
2-D configuration without elevation info:
$ roslaunch ti_mmwave_rospkg 6843_multi_2d_0.launch
To add the second EVM in 2-D configuration, open a new terminal and enter the command:
$ roslaunch ti_mmwave_rospkg 6843_multi_2d_1.launch
- For the TI mmWave 1843BOOST EVM use one of the following commands:
3-D configuration with elevation info:
$ roslaunch ti_mmwave_rospkg 1843_multi_3d_0.launch
To add the second EVM in 2-D configuration, open a new terminal and enter the command:
$ roslaunch ti_mmwave_rospkg 1843_multi_3d_1.launch
2-D configuration without elevation info:
$ roslaunch ti_mmwave_rospkg 1843_multi_2d_0.launch
To add the second EVM in 2-D configuration, open a new terminal and enter the command:
$ roslaunch ti_mmwave_rospkg 1843_multi_2d_1.launch
⚠️ 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
- Click Add->PointCloud2
- Select /mmWaveDataHdl/RScan from the Topic field dropdown for the PointCloud2 on the left hand panel The following figure shows an example RViz window for the 6843 or 6843AOP sensor in a 3D configuration. In the initial perspective shown, the view is setup with the TI mmWave EVM in the back-middle edge of the grid facing toward you. The color of each point is based on its Z-axis elevation relative to the grid. The perspective can be adjusted by moving the mouse while holding down the left mouse button while the mouse is over the visualizer display. Use the mouse scroll wheel to zoom in/out. Holding down the center scroll wheel allows panning.
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.
- Establishes a ROS Service which receives a CLI command and parameters in the form of a std_msgs::string
- Uses ‘serial’ library (dependency) to open/read a COM port in Linux
- Sends the string out to the mmWave board over UART
- Returns the response from the EVM in the form of a std_msgs::string
- mmWaveQuickConfig node uses this service to load a full .cfg file to the EVM.
mmWaveDataHdl Nodelet
This nodelet reads and sorts the incoming radar data from the mmWave EVM.
- Uses ‘serial’ library to read incoming data from the mmWave device via a COM port on Linux
- Multi-Threaded Double Buffered read & sort of incoming packets
- readIncomingData thread : reads incoming data, looks for start-of-packet signal
- sortIncomingData thread : sorts the incoming data based off of the package structure sent from the mmWave device
- syncedBufferSwap thread : when 1) and 2) have finished, swaps data buffers so the sorting thread can operate on new data
- Publishes output as a PointCloud
type ROS message
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
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
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
Change directory to the ROS Driver lab. This is the workspace directory.
cd mmwave_ti_ros/ros2_driver/
Build the lab.
colcon build
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
Once the ROS2 Driver is built, Close all previously opened Terminal windows/shells (since they may have old/stale environment variables)
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.
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.
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.
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
Navigate to the launch directory within
<workspace_dir>/src/ti_mwave_rospkg/launch/
Open the launch file of your choice in a text editor
Change the
path
parameter to match where the configuration file is located within your workspace directory, and save.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 ofros2 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).
- Click “Add” button on the bottom left side of the rviz2 visualizer.
- Click “By topic”
- Select the mmWave topics that are being published The following figure shows an example RViz window for the 6843 or 6843AOP sensor in a 3D configuration. In the initial perspective shown, the view is setup with the TI mmWave EVM in the back-middle edge of the grid facing toward you. The color of each point is based on its Z-axis elevation relative to the grid. The perspective can be adjusted by moving the mouse while holding down the left mouse button while the mouse is over the visualizer display. Use the mouse scroll wheel to zoom in/out. Holding down the center scroll wheel allows panning.
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.
ti_mmwave_rospkg_msgs/msg/radar_scan
ti_mmwave_rospkg_msgs/msg/radar_occupancy
ti_mmwave_rospkg_msgs/srv/mmwave_cli
mmWaveCommSrv Node
This node provides the mmWave UART Command Line Interface as a ROS Service.
- Establishes a ROS Service which receives a CLI command and parameters in the form of a std_msgs::msg::String
- Uses ‘serial’ library (dependency) to open/read a COM port in Linux
- Sends the string out to the mmWave board over UART
- Returns the response from the EVM in the form of a std_msgs::msg::String
- mmWaveQuickConfig node uses this service to load a full .cfg file to the EVM.
ParameterParser Node
This node reads the configuration file sent to the mmWave device and does calculations of several useful chirp design parameters.
- Number of Range Samples
- Number of Chirps
- End Frequency
- Bandwidth
- Max Range
- Range Resolution
- Max Doppler Speed
- Doppler Resolution
DataHandlerClass Node
This component reads and sorts the incoming radar data from the mmWave EVM.
- Uses serial library to read incoming data from the mmWave device via a COM port on Linux
- Multi-Threaded Double Buffered read & sort of incoming packets
- readIncomingData thread : reads incoming data, looks for start-of-packet signal
- sortIncomingData thread : sorts the incoming data based off of the package structure sent from the mmWave device
- syncedBufferSwap thread : when 1) and 2) have finished, swaps data buffers so the sorting thread can operate on new data
- Publishes output as a PointCloud
type ROS message - Any additional TLV that is output from the sensor and is desired to have a ROS output would be added here
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.
- Services
- MmwaveCli
- Requests
- std_msgs::msg::String comm
- Response
- std_msgs::msg::String resp
- Messages
- Sensor_msgs::msg::PointCloud2
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).
- The Windows PC should have more than 12GB of free hard drive space to install the VM and all required software on the VM
- The driver was successfully tested using an Ubuntu 18.04 LTS and Ubuntu 20.04 Virtual Machine running under Oracle Virtualbox www.virtualbox.org on Windows 7 and Windows 10. The following instructions are specific to Oracle Virtualbox but should be useful for other virtual machine managers as well.
Steps for Starting Virtual Machine
Instructions are for 18.04 but also works with 20.04
- Download and install Oracle Virtualbox using the link above (to download click the Download button on the webpage and then click the download link for Windows hosts)
- Open Virtualbox and click the button to create a new virtual machine (VM)
- Create the VM in Virtualbox using the following settings:
- Name: Ubuntu 18.04
- If not already selected, use Type: “Linux” and Version: “Ubuntu (64-bit)” and click Next
- Select at least 2048 MB for the RAM memory size and click Next
- Choose “Create a Virtual Hard Disk now” when prompted and click Create
- For the following prompts select “VDI”, “Dynamically allocated”, and increase the size to at least 12GB and then click Create
- Download the Ubuntu 18.04 installer ISO image (1.5 GB) from the following link: https://releases.ubuntu.com/18.04/
- Start the newly created VM and point it to the downloaded ISO image when prompted for a startup disk
- Follow the prompts to install Ubuntu on the VM
- It is not required to check the box to “Install third-party software”
- Use the default selected option “Erase disk and install Ubuntu” when prompted
- Press “Continue” when prompted to write changes to disk
- Press “Restart Now” when prompted
- After logging into the Ubuntu VM using the newly created username and password, a Terminal window can be opened by clicking on the icon on the top of the left bar and searching for “Terminal”, then clicking on the Terminal icon (right-click the Terminal icon on the left bar and choose to lock it to the Launcher bar if desired)
- Whenever the mmWave EVM is connected or power-cycled, the VM will need to regain access to 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 following picture:
- Enable the VM to access the internet by going to the “Devices->Network->Network Settings” menu at the top of the VM window and then select “Bridged Adapter” and pick the active network adapter so the VM can access the network
- If behind a corporate firewall, proper Linux proxy configurations are needed to allow operation of GIT, web browsing, and software installation using apt-get.
- Do not enable the “Display->Enable 3D Acceleration” option in the VM settings (it is normally disabled by default) or it may cause RViz (ROS visualizer) to crash
- (Optional) Enabling the Bi-directional Shared Clipboard gives the ability to copy/paste text between Windows and the Linux VM. This can be done via the “Devices->Shared Clipboard” menu.
- (Optional) Enabling a Shared Folder gives the ability to share files between Windows and the Linux VM. This can be done via the “Devices->Shared Folders” menu. The Linux VM will need a restart after adding a new shared folder to make it show up in the Linux file browser.
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.”
- Make sure your user account is a member of the “dialout” unix group in order to have access to the serial ports on Linux
- You can fix this by running
sudo adduser <your_username> dialout
and then logging out of and then back into your computer. Starting a new terminal window might suffice as well.
I see “not recognized as a CLI command” errors when I start the driver
- This type of error is typically seen when the wrong firmware or firmware version is running on the mmWave EVM and is not compatible with the parameters being sent to it over serial. An example error message would be:
Error Message “mmWaveCommSrv: Received response from sensor: ‘clutterRemoval 0 ’clutterRemoval’ is not recognized as a CLI command”
- Reflash the mmWave EVM with the proper firmware from the bin/ folder located at
<MMWAVE_ROS_DRIVER_INSTALL_DIR>/ros<x>_driver/src/ti_mmwave_rospkg/bin/
using the steps in the How do I reflash the TI mmWave EVM with a binary FAQ Section
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
- Make sure the mmWave EVM is powered on and connected to the PC. It may take up to 20 seconds for Linux to completely initialize the serial ports for usage after the EVM is plugged in.
- If using a Virtual Machine, make sure the steps listed in the Tips for usage with an Ubuntu Virtual Machine section regarding the USB serial port access has been reviewed.
- If the mmWave EVM is connected via different serial ports, follow the steps in the Running the ROS driver section within the EVM Connection Issues warning to modify the launch file that specifies the ports for the driver to use
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.
- Download Uniflash, TI’s flashing software, via the following link: https://www.ti.com/tool/UNIFLASH
- 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
- 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
- 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
- Install the following mmWave SDK dependency:
$ sudo apt-get install libc6:i386
- 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
- Make sure there is no power to the mmWave EVM and place a jumper on the SOP2 header
- Run Uniflash to see the following screen:
Click mmWave and in the list select your device.
- 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
Supply power and connect the mmWave EVM to the computer with a microUSB cable
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.
On the left-hand pane in Uniflash, select Settings and Utilities. Enter the serial port corresponding to the first COM port (typically /dev/ttyACM0)
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.
- 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
- The configuration files are included in
<MMWAVE_ROS_DRIVER_INSTALL_DIR>/ros<x>_driver/src/ti_mmwave_rospkg/cfg
. - To change a parameter, edit and save the file using a text editor.
- For example to update the demo to run using the IWR6843ISK and configuration file for Occupancy
- Edit and make the desired changes to “6843ISK_Occupancy.cfg” configuration file using parameters compatible with Occupancy demo.
- Flash the IWR6843ISK with the correct binary based off of the README.txt in
bin/
folder. - Run the demo via launch file that uses the newly edited configuration file for 6843 EVM.