Obstacle Detection AOP Users Guide

Table of Contents

Overview

This lab demonstrates the use of TI mmWave sensors to detect objects that are within close proximity of a vehicle. Using the AWR1843-AoP (Antenna on Package) device, algorithms run onboard the single-chip device to create Range-Azimuth and Range-Elevation heatmaps, then performs object detection with CFAR, angle of arrival estimation and clustering on configured range rows in the heatmaps.

This version of the lab also supports a secondary peak search, so that more than one peak can be detected on a single range bin.

Quickstart

The quickstart contains:

• Precompiled binaries for flashing the device using Uniflash
• Visualizer as .exe

1. Hardware and Software Requirements

Hardware

Software

2. Physical Setup

For best results, the EVM should be positioned at car door height, with no objects in the configured range of the sensor except those objects that are under test.

In order to provide +/-70deg FOV in azimuth and +/-70deg FOV in elevation, the AoP EVM must be placed with antenna at the top as shown in the following picture. This positions the Tx antennas vertically along the left side of the chip with the Rx antennas along the top.

3. Flash the Device

• Power on the EVM using a 5V/2.5A power supply.
• Flash the following image using Uniflash

Steps for flashing via uniflash can be found here

4. Run the Lab Visualizer

Before running the demo, you will need to know the COM port numbers for the EVM’s User and Data UART ports. This is discussed in the pulldown section above titled “Expand for help using Uniflash”. Once found, the COM port numbers will usually not change from run to run or boot to boot. You can run the visualizer either from DOS or within Matlab:

• The following steps assume the AWR1843 AoP EVM is flashed with the Obstacle Detection firmware.
• Mount the EVM as shown above in the Test Setups.
• Attach the micro USB cable from the EVM to the host PC.
• Attach the 5V power adapter cable to the EVM.
• Open a DOS Command Window, and cd to <RADAR_TOOLBOX_INSTALL_DIR>\tools\visualizers\Automotive_Obstacle_Detection_GUI.
• At the DOS prompt, enter this command: (there are no command line arguments)
  • ods_3d_visualizer
• After a moment, the visualizer will look like this:

To start the radar chirp processing, perform the following steps:

• Fill in the two COM port numbers, then click the “Connect” button.
• Browse to the provided configuration file: <RADAR_TOOLBOX_INSTALL_DIR>\source\ti\examples\Automotive_Body_Sensors\obstacle_detection_aop\chirp_configs\ods_aop_config.cfg.
• Click the “Load” button.
• The visualizer will now begin displaying detected objects and clusters.

To modify the display, the widgets in the “Plot Settings” window can be modified:

• The “Detected Objects” and “Clusters” buttons can be clicked at any time to enable/disable their display.
• To change the display from 3D to a 2D projection, open the “Plot Type” drop-down menu, make a selection, then click the “Apply All” button.
• To change the overall display limits, modify the values in “Plot axis limits” and click the “Apply All” button.
• To change the grid limits, modify the values in “Display grid limits and size” and click the “Apply All” button.

To modify the rendered image orientation and size:

• Select one of the icons shown here, then drag the mouse either up/down or left/right over the image. If you hover over an icon, a message will tell you what the button does. The button shown here in blue allows the size of the image to change. Drag the mouse up over the image (with the left button down) to increase the size, and down to decrease the size.

5. Understanding the Output

By default, detected objects and clusters are displayed. Detected objects are shown as dots in the 3D space, and clusters are shown as boxes. Cluster box sizes are obtained from the DSP’s clustering algorithm. Detected objects are updated at the configured frame rate, and clusters are updated at a slower rate, typically once every four frames. Note that detected objects and clusters can be disabled from being output from the EVM. This is enabled in the “guiMonitor” command, discussed in the “Visualizer Source Files” section below.

First, there is a banner line over the plot area. This banner displays the current frame number, the number of detected objects for the frame, and the number of clusters for the current frame. The number in parentheses is the number of clusters that are derived from a single point.

The detected object (dot) colors are determined by their Z distance (height) from the antenna. Cluster colors are red if the center is within 1 meter of the antenna, and green if outside 1 meter.

Each 2D display shows a flat projection along two of the three planes. Shown here is the “top-down” display that shows objects and clusters in the X-Y plane. Object point colors are still rendered according to Z position:

Developer’s Guide

Building the Firmware from Source Code

1. Prerequisites for Firmware

🛑 The software prerequisites must be met before continuing!

To verify proper installations, navigate to C:\ti and ensure that the following tools have been installed in the EXACT directory specified.

2. Import Lab Project

For the Obstacle Detection lab there are two projects, the DSS for the C674x DSP core and the MSS project for the R4F core. Both need to be imported to CCS and compiled to generate firmware for the xWR1843.

• Start CCS and setup workspace as desired.
• Import the projects below to CCS using either TI Resource Explorer in CCS or CCS Import Projectspecs method:
  • ods_aop_18xx_dss
  • ods_aop_18xx_mss

When importing projects to a workspace, a copy is created in the workspace. All modifications will only be implemented for the workspace copy. The original project downloaded from the Toolbox is not touched.

3. Build the Lab

Build DSS Project

The DSS project must be built before the MSS project.

⚠️ The DSS project must be built using compiler version 8.3.3.
To check the build settings, select ods_aop_18xx_dss and right click on the project to select Show build settings…. Under the General tab, the Advanced Settings section has a drop down menu for Compiler Version. Ensure that it reads TI v8.3.3.

With the ods_aop_18xx_dss project selected in Project Explorer, right click on the project and select Rebuild Project. Selecting Rebuild instead of Build ensures that the project is always re-compiled. This is especially important in case the previous build failed with errors.

Successful DSS Project Build In the Project Explorer panel, navigate to and expand ods_aop_18xx_dss > Debug directory. The project has been successfully built if the following files appear in the Debug folder:

• ods_aop_18xx_dss.bin
• ods_aop_18xx_dss.xe674

Build MSS Project

After the DSS project is successfully built, select ods_aop_18xx_mss in Project Explorer, right click on the project and select Rebuild Project.

Successful MSS Project Build In the Project Explorer panel, navigate to and expand ods_aop_18xx_mss > Debug directory. The project has been successfully built if the following files appear in the Debug folder:

• ods_aop_18xx_mss.bin
• ods_aop_18xx_mss.xer4f
• ods_aop_18xx.bin

⚠️ Build Fails with Errors
If the build fails with errors, please ensure that all the prerequisites are installed as mentioned in the mmWave SDK release notes.

4. Execute the Lab

There are two ways to execute the compiled code on the EVM:

• Deployment mode: the EVM boots autonomously from flash and starts running the bin image
  • Using Uniflash, flash the ods_aop_18xx.bin found at <PROJECT_WORKSPACE_DIR>\ods_aop_18xx_mss\Debug\ods_aop_18xx.bin
  • The same procedure for flashing can be use as detailed in the Quickstart Flash the Device section.
• Debug mode: enables connection with CCS while lab is running; useful during development and debugging

For more information on using CCS Debug, refer to the documentation here

After starting the lab on the AWR1843 using either method, the program will wait until a chirp configuration is sent to it via the “User” COM port.

Visualizer Source Files

⚠️ Working with and running the visualizer source files requires a full MATLAB license not just the MATLAB Runtime Engine

The detection processing chain is implemented in the C674x DSP core of the AWR1843 device. The visualizer serves to read the UART stream from the device and plots the detected objects and cluster information.

Source files are located at <RADAR_TOOLBOX_INSTALL_DIR>\tools\visualizers\Automotive_Obstacle_Detection_GUI.

• ods_3d_visualizer.m: the Matlab gui program which reads and parses the UART data for visualization.
• ods_3d_visualizer.exe: the DOS executable version of the gui program.

Chirp Configuration files are located at <RADAR_TOOLBOX_INSTALL_DIR>\source\ti\examples\Automotive_Body_Sensors\obstacle_detection_aop\chirp_configs\ods_aop_config.cfg. In addition to the normal mmWave chirp configuration CLI commands, there are a few commands that are specific to the Obstacle Detection Demo:

Please refer to the mmWave SDK’s user guide for details on the chirp (RF) related CLI configuration commands.

Data Packet Format

A TLV(type-length-value) encoding scheme is used with little endian byte order. For every frame, a packet is sent consisting of a fixed sized Frame Header and then a variable number of TLVs depending on what was selected via the guiMonitor command. There are 4 possible TLV types for the Obstacle Detection demo:

Frame Header

Size: 40 bytes

frameHeaderStructType = struct(...
    'sync',             {'uint16', 8}, ... % syncPattern in hex is: '02 01 04 03 06 05 08 07'
    'version',          {'uint32', 4}, ... % SDK Version number
    'totalPacketLen',   {'uint32', 4}, ... % In bytes, including header and 32 byte padding
    'platform',         {'uint32', 4}, ... % 0xA1843 or 0xA1843
    'frameNumber',      {'uint32', 4}, ... % Starting from 1
    'timeCpuCycles',    {'uint32', 4}, ... % Time in DSP cycles when the message was created
    'numDetectedObj',   {'uint32', 4}, ... % number of detected objects
    'numTLVs' ,         {'uint32', 4}, ... % Number of TLVs in this message
    'subFrameIndex',    {'uint32', 4});    % always zero

TLVs

TLVs in this demo can be of type DETECTED_OBJECTS, CLUSTERS, RANGE_AZIMUTH_HEAT_MAP, or RANGE_ELEV_HEAT_MAP. Each TLV consists of a TLV header plus a unique data type.

TLV Header

Size: 8 bytes

% TLV Type: 01 = DetectedObjects, 02 = Clusters, 03 = RangeAzimuthHeatmap, 04 = RangeElevHeatmap
tlvHeaderStruct = struct(...
    'type',             {'uint32', 4}, ... % TLV object
    'length',           {'uint32', 4});    % TLV object Length, in bytes

Following the header are the TLV-type specific payloads

Detected Objects TLV

Type: DETECTED_OBJECTS

Size: 4 + (12 x numDetObj)

The following structure is only present if the TLV header.length is greater than zero.

featureVector = struct(...
    'numDetObj',  {'short', 2}, ... % Number of detected objects in the following sub-struct
    'xyzQFormat', {'short', 2}, ... % Q-point shift value to convert to meters
      %per object:
      'speedIdx', {'short', 2}, ... % Doppler index
      'x',        {'short', 2}, ... % x - coordinate in meters, divided by xyzQFormat
      'y',        {'short', 2}, ... % y - coordinate in meters, divided by xyzQFormat
      'z',        {'short', 2}, ... % z - coordinate in meters, divided by xyzQFormat
      'rangeIdx', {'short', 2}, ... % Range index
      'peakVal',  {'short', 2}, ... % Peak value

Cluster TLV

Type: CLUSTERS

Size: 4 + (12 x numClusters)

The following structure is only present if the TLV header.length is greater than zero. Note that cluster size can be adjusted by the “max distance” parameter of dbscanCfg.

featureVector = struct(...
    'numClusters',{'short', 2}, ... % Number of clusters in the following sub-struct
    'xyzQFormat', {'short', 2}, ... % Q-point shift value to convert to meters
      %per cluster:
      'x',        {'short', 2}, ... % x - coordinate in meters, divided by xyzQFormat
      'y',        {'short', 2}, ... % y - coordinate in meters, divided by xyzQFormat
      'z',        {'short', 2}, ... % z - coordinate in meters, divided by xyzQFormat
      'xsize',    {'short', 2}, ... % x size of the cluster, in meters, by xyzQFormat
      'ysize',    {'short', 2}, ... % y size of the cluster, in meters, by xyzQFormat
      'zsize',    {'short', 2}, ... % z size of the cluster, in meters, by xyzQFormat

The two ODS heatmaps are 2D array of floats, and will be the same size based on the current configuration. The size of the row is currently hardcoded in the target code and visualizer to be 180 degrees divided by the angular or elevation resolution, currently 3 degrees. So each row contains 60 points, and the row corresponds to a range from the antenna. The number of rows, Yr, is calculated by both the target code and visualizer code, based on the profileCfg and cfarCfg commands in the configuration file. First, the range resolution (in meters) is calculated from profileCfg, then the max detection range in cfarCfg is divided by the range resolution to obtain the number of range rows.

Range Azimuth Heatmap TLV

Type: RANGE_AZIMUTH_HEAT_MAP

Size: 60 x Yr x sizeof (float)

Range Elevation Heatmap TLV

Type: RANGE_ELEV_HEAT_MAP

Size: 60 x Yr x sizeof (float)

Need More Help?

• Find more details about ODS by referring to the ODS TI Design document
• Find answers to common questions on mmWave E2E FAQ
• Search for your issue or post a new question on the mmWave E2E forum