mmWaveRadar

Connect to Texas Instruments mmWave radar sensors, and read object detections and other measurements

Since R2023b

expand all in page

Description

The mmWaveRadar System object™ connects to Texas Instruments® (TI) mmWave radar sensors and reads object detections and related measurements. You can read position and velocity of objects (object detection reports) and also other radar measurements of interest such as range profile, noise profile, and so on, as read from the mmWave radar sensors.

To read radar data from mmWave sensor:

  1. Create the mmWaveRadar object and set its properties.

  2. Call the object with arguments, as if it were a function.

To learn more about how System objects work, see What Are System Objects?

Creation

Syntax

rdr = mmWaveRadar(boardname)
rdr = mmWaveRadar(boardname, ConfigPort = cfgPort, DataPort = dataPort)
rdr = mmWaveRadar()
rdr = mmWaveRadar(boardname,Name=Value)

Description

rdr = mmWaveRadar(boardname) connects to a TI mmWave Radar Sensor specified by boardname and connected to the serial port of the host computer. The rdr connection object has default property values. When you use this syntax, MATLAB® automatically detects the serial port at which the TI mmWave radar sensor is connected. Use this syntax when only one TI mmWave radar sensor is connected to the host computer.

rdr = mmWaveRadar(boardname, ConfigPort = cfgPort, DataPort = dataPort) connects to a TI mmWave radar sensor specified by boardname and connected to the serial port of the host computer as specified using ConfigPort and DataPort arguments. Use this syntax if multiple TI mmWave radar sensors are connected to the host computer.

rdr = mmWaveRadar() recreates the last successful connection to the TI mmWave radar sensor.

  • Use this syntax to reconnect to the same board that you used with MATLAB previously, and then you cleared. The properties of the object created using this syntax are the same as the properties set for the previously created object before it was locked. mmWaveRadar System object gets locked after calling the mmWaveRadar System object for the first time after object creation, or after the first call to mmWaveRadar System object after calling the release function.

  • After running Hardware Setup screens, use this syntax to reconnect to the same board that uses the serial ports that you had specified in Flash Binary or Test Connection screen (whichever action you performed last using the Hardware Setup screens).

If no successful previous connection exists, this syntax errors out.

rdr = mmWaveRadar(boardname,Name=Value) sets Properties using one or more name-value arguments.

For example, rdr = mmWaveRadar("TI 6843ISK",ConfigFile = "configurations.cfg") connects to the IWR6843ISK board connected to your host computer and prepares for reading data by using the configuration specified in the file configurations.cfg in the MATLAB search path.

Input Arguments

expand all

Name of the Texas Instruments mmWave radar sensor Evaluation Module (EVM) connected to the host computer.

Data Types: string

Name of the serial port (COM#) used for passing configurations and binaries to the TI mmWave radar sensor. Typically, the Config port is named in your Device Manager as either Silicon Labs Dual CP2105 USB to UART Bridge: Enhanced COM Port or XDS110 Class Application/User UART. For details, see Finding COM Ports from Device Manager.

Name of the serial port (COM#) used to receive radar data from the TI mmWave radar sensor. For all boards except IWRL6432BOOST, typically, the Data COM Port is named in your Device Manager as either Silicon Labs Dual CP2105 USB to UART Bridge: Standard COM Port or XDS110 Class Auxiliary Data Port. For details, see Finding COM Ports from Device Manager.

IWRL6432BOOST board uses a single port, that is, the port identified as Config port for receiving configurations or binary and for sending data to the host PC. Therefore, for IWRL432BOOST, the port identified as Config port and Data port in MATLAB are the same. To specify a particular serial port for IWRL6432BOOST, specify only the ConfigPort (the port which appears in your Device Manager as either Silicon Labs Dual CP2105 USB to UART Bridge: Enhanced COM Port or XDS110 Class Application/User UART).

Property type: Immutable

Name-Value Arguments

expand all

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Example: rdr = mmWaveRadar("TI IWR6843ISK",ConfigFile = "configurations.cfg", RemoveStaticClutter = true)

Properties

expand all

If a property is nontunable, you can only change its value before calling the object or after calling the release function.

If a property is tunable, you can change its value at any time.

If a property is immutable, the property value is set during construction; you cannot change the value of an immutable property after the object is created. For the mmWaveRadar object, the properties BoardName, ConfigPort and DataPort are immutable.

Note

You can specify any of the properties on this page, and which are not read-only, as name-value pairs.

The values of the read-only properties are internally set. For the mmWaveRadar object, some of them are derived from the Configuration (.cfg) file (for example, Update Rate, Bandwidth, Resolution, and so on). Therefore, you can indirectly modify such properties by updating the Configuration file. To generate the configuration file, see Generating Configuration (.cfg) file.

For more information on changing property values, see System Design in MATLAB Using System Objects.

Hardware Connection

Name of the Texas Instruments mmWave radar sensor Evaluation Module (EVM) connected to the host computer.

Property type: Immutable

Data Types: string

Name of the serial port (COM#) used for passing configurations and binaries to the TI mmWave radar sensor. Typically, the Config port is named in your Device Manager as either Silicon Labs Dual CP2105 USB to UART Bridge: Enhanced COM Port or XDS110 Class Application/User UART. For details, see Finding COM Ports from Device Manager.

Property type: Immutable

Name of the serial port (COM#) used to receive radar data from the TI mmWave radar sensor. For all boards except IWRL6432BOOST, typically, the Data COM Port is named in your Device Manager as either Silicon Labs Dual CP2105 USB to UART Bridge: Standard COM Port or XDS110 Class Auxiliary Data Port. For details, see Finding COM Ports from Device Manager.

IWRL6432BOOST board uses a single port, that is, the port identified as Config port for receiving configurations or binary and for sending data to the host PC. Therefore, for IWRL6432BOOST, the port identified as Config port and Data port in MATLAB are the same. To specify a particular serial port for IWRL6432BOOST, specify only the ConfigPort (the port which appears in your Device Manager as either Silicon Labs Dual CP2105 USB to UART Bridge: Enhanced COM Port or XDS110 Class Application/User UART).

Property type: Immutable

Baud rate to read data through the serial port identified as Data port. If the baud rate is specified using the respective command in Configuration (.cfg) file, the value of the BaudRate property overrides the value specified in the Configuration File.

Property type: Nontunable

However, for IWRL6432BOOST, this property is read-only, and the value is derived from the Configuration (.cfg) file.

Data Types: double

Output Configuration

Option to read either the latest available readings or from the values accumulated from the beginning.

Use latest (default) to read the latest available data. During read, if 5 readings are available, first four is discarded and the fifth reading will appear in output. If no readings are available, the code waits for a new reading till a specified timeout. This mode might result in data loss if not read fast.

Use oldest to read the first data acquired from the radar which is not yet read using step(). During read, if 5 samples are available, then the first sample available will appear in output. In the next read, the next sample is read and so on. If you include an explicit call to flush() or release function, the samples accumulated, which have not been read yet, will not be discarded from the internal buffer. Unless there is a data drop in hardware or a buffer overflow on the hardware or host, this mode results in reading without losing data.

Property type: Nontunable

Data Types: string

Radar Configuration

File name with full path and the file extension to the Configuration (.cfg) file that stores information regarding configuration and settings of the device. If the file is in the MATLAB path, then no need to specify full file path (the filename with extension is enough).

For example, if the config file MaxRangResolution.cfg is in the MATLAB search path, you can set the property while doing object creation like this:

radarBoard = mmWaveRadar("TI IWR6843ISK", ConfigFile = "MaxRangResolution.cfg").

For more details, see Specifying Configuration File.

Property type: Nontunable

Data Types: string

Sensor update rate, in Hz (samples/sec), specified as a positive real scalar. The mmWave radar generates measurement data as frames at intervals defined by the reciprocal of the update rate.

The UpdateRate is derived from the Configuration (.cfg) file that you specified using the property ConfigFile. To modify the value of this property, update the config file before object creation or after releasing the object.

Property type: Read-only

Data Types: double

Azimuth resolution of the radar, in degrees, specified as a positive scalar. The azimuth resolution defines the minimum separation in azimuth angle at which the radar can distinguish between two targets.

The AzimuthResolution is derived from the Configuration (.cfg) file that you specified using the property ConfigFile. To modify the value of this property, update the config file before object creation or after releasing the object.

Property type: Read-only

Data Types: double

Elevation resolution of the radar, in degrees, specified as a positive scalar. The elevation resolution defines the minimum separation in elevation angle at which the radar can distinguish between two targets.

The ElevationResolution is derived from the Configuration (.cfg) file that you specified using the property ConfigFile. To modify the value of this property, update the config file before object creation or after releasing the object.

Property type: Read-only

Data Types: double

Range resolution of the radar, in meters, specified as a positive scalar. The range resolution defines the minimum separation in range at which the radar can distinguish between two targets.

The RangeResolution is derived from the Configuration (.cfg) file that you specified using the property ConfigFile. To modify the value of this property, update the config file before object creation or after releasing the object.

Property type: Read-only

Data Types: double

Range-rate resolution of the radar, in meters per second, specified as a positive real scalar. The range rate resolution defines the minimum separation in range rate at which the radar can distinguish between two targets.

The RangeRateResolution is derived from the Configuration (.cfg) file that you specified using the property ConfigFile. To modify the value of this property, update the config file before object creation or after releasing the object.

Property type: Read-only

Data Types: double

Center frequency of the radar band, specified as a positive scalar. Units are in Hz.

The CenterFrequency is derived from the Configuration (.cfg) file that you specified using the property ConfigFile. To modify the value of this property, update the config file before object creation or after releasing the object.

Property type: Read-only

Data Types: double

Radar waveform bandwidth, specified as a positive real scalar. Units are in Hz.

The Bandwidth is derived from the Configuration (.cfg) file that you specified using the property ConfigFile. To modify the value of this property, update the config file before object creation or after releasing the object.

Property type: Read-only

Data Types: double

Sensor Identification

Unique sensor identifier, specified as a positive integer. Use this property to distinguish between detections that come from different sensors in a multisensor system.

Property type: Tunable

Data Types: double

Sensor Mounting

Mounting location of the radar on the platform, in meters, specified as a 1-by-3 real-valued vector of the form [x y z]. This property defines the coordinates of the sensor along the x-axis, y-axis, and z-axis relative to the platform body frame.

Property type: Tunable

Data Types: double

Mounting rotation angles of the radar, in degrees, specified as a 1-by-3 real-valued vector of the form [z yaw y pitch x roll]. This property defines the intrinsic Euler angle rotation of the sensor around the z-axis, y-axis, and x-axis with respect to the platform body frame, where:

  • z yaw, or yaw angle, rotates the sensor around the z-axis of the platform body frame.

  • y pitch, or pitch angle, rotates the sensor around the y-axis of the platform body frame. This rotation is relative to the sensor position that results from the z yaw rotation.

  • x roll, or roll angle, rotates the sensor about the x-axis of the platform body frame. This rotation is relative to the sensor position that results from the z yaw and y pitch rotations.

These angles are clockwise-positive when looking in the forward direction of the z-axis, y-axis, and x-axis, respectively.

Property type: Tunable

Data Types: double

Detection Reporting Specifications

Coordinate system used to report detections, specified as one of these options:

  • 'Sensor rectangular' — Detections are reported in the sensor rectangular body coordinate system.

  • 'Body' — Detections are reported in the rectangular body system of the sensor platform.

  • 'Sensor spherical' — Detections are reported in a spherical coordinate system derived from the sensor rectangular body coordinate system. This coordinate system is centered at the sensor and aligned with the orientation of the radar on the platform.

For more information on how the detections are reported as per the property DetectionCoordinates, refer to dets.

Property type: Tunable

Eliminate static clutter from the scene for reporting detections. Use this option only when trying to detect moving objects in the scene and static objects need to be masked out.

If specified, this value overrides the value specified in the Config file. If not specified, the value is set as per the Config file.

Property type: Tunable

However, for IWRL6432BOOST, this property is read-only, and the value is derived from the Configuration (.cfg) file.

Data Types: logical

Enabling peak grouping in the range direction. With the peak-grouping scheme enabled, instead of reporting a cluster of detected neighboring points, only one point, the highest one, is reported. This reduces the total number of detected points per frame.

If specified, this value overrides the value specified in the Config file. If not specified, the value is set as per the Config file.

Property type: Tunable

However, for IWRL6432BOOST, this property is read-only, and the value is derived from the Configuration (.cfg) file.

Data Types: logical

Enabling peak grouping in the Doppler direction. With the peak-grouping scheme enabled, instead of reporting a cluster of detected neighboring points, only one point, the highest one, is reported. This reduces the total number of detected points per frame.

If specified, this value overrides the value specified in the Config file. If not specified, the value is set as per the Config file.

Property type: Tunable

However, for IWRL6432BOOST, this property is read-only, and the value is derived from the Configuration (.cfg) file.

Data Types: logical

Detection threshold specified in dB scale in the Range Direction.

If specified, this value overrides the value specified in the Config file. If not specified, the value is set as per the Config file.

Property type: Tunable

However, for IWRL6432BOOST, this property is read-only, and the value is derived from the Configuration (.cfg) file.

Data Types: numeric

Detection threshold specified in dB scale in the Doppler direction.

If specified, this value overrides the value specified in the Config file. If not specified, the value is set as per the Config file.

Property type: Tunable

However, for IWRL6432BOOST, this property is read-only, and the value is derived from the Configuration (.cfg) file.

Data Types: numeric

Specify the range limits for the detections reported by the radar. Specify limits as a two-element vector of the form [Rangemin Rangemax], where RangeMax is greater than RangeMin. The radar does not report detections for the targets that are outside this range limits. Below RangeMin and above RangeMax, radar will filter out the detected points. Units are in meters.

If specified, this value overrides the value specified in the Config file. If not specified, the value is set as per the Config file.

Property type: Tunable

However, for IWRL6432BOOST, this property is read-only, and the value is derived from the Configuration (.cfg) file.

Data Types: double

Specify the range rate limits for the detections reported by the radar. Specify limits as a two-element vector of the form [RangeRatemin RangeRatemax], where RangeRateMax is greater than RangeRateMin. The radar does not report detections for the targets that are outside this range limits. Below RangeRateMin and above RangeRateMax, radar will filter out the detected points. Units are in meters.

If specified, this value overrides the value specified in the Config file. If not specified, the value is set as per the Config file.

Property type: Tunable

However, for IWRL6432BOOST, this property is read-only, and the value is derived from the Configuration (.cfg) file.

Data Types: double

The minimum and maximum azimuth angle (in degrees) that specifies field of view in azimuth plane. Beyond this field of view, detected points will not be reported by radar.

If specified, this value overrides the value specified in the Config file. If not specified, the value is set as per the Config file.

Property type: Tunable

However, for IWRL6432BOOST, this property is read-only, and the value is derived from the Configuration (.cfg) file.

Data Types: double

The minimum and maximum elevation angle (in degrees) that specifies field of view in elevation plane. Beyond this field of view, detected points will not be reported by radar.

If specified, this value overrides the value specified in the Config file. If not specified, the value is set as per the Config file.

Property type: Tunable

However, for IWRL6432BOOST, this property is read-only, and the value is derived from the Configuration (.cfg) file.

Data Types: double

Others

Time stamp at which sensor starts sending the data in 'd-MMM-y HH:mm:ss.SSS ' format. The time is based on the system time of the host computer. The sensor starts sending at the execution of first step after object creation or after calling release(). If first step is not invoked, then start time shows the time of object creation.

Property type: Read-only

Data Types: datetime

mmWave SDK version of the binary running on the mmWave device. This information is set internally based on the response to the version command sent to the hardware after the first execution of step.

Property type: Read-only

Data Types: string

Usage

Syntax

[dets,timestamp,measurements,overruns] = rdr()

Description

[dets,timestamp,measurements,overruns] = rdr() reads and convert the data acquired from TI mmWaveRadar. System objects may be called directly like a function instead of using the step method. For example, y = step(obj) and y = obj() are equivalent.

Output Arguments

expand all

Detections returned as a cell array of objectDetection objects, which contains object detection report. Each objectDetection object contains an object detection report that was obtained by the radar for a single object. If no objects are detected by the radar, an empty cell array is returned.

If the radar is configured to output SNR and noise (using guiMonitor command in Config file), the SNR and noise for each detection is available in the property ObjectAttributes of the corresponding objectDetection object.

The format of the measurement states (MeasurementParameters property of the objectDetection object) is determined by the specifications of the ElevationResolution, AzimuthResolution and DetectionCoordinates properties.

There are two general types of detection or track coordinates:

  • Cartesian coordinates — Enabled by specifying the DetectionCoordinates property as 'Body', or 'Sensor rectangular'. The complete form of a Cartesian state is [x; y; z; vx; vy; vz], where x, y, and z are the Cartesian positions and vx, vy, and vz are the corresponding velocities.

  • Spherical coordinates — Enabled by specifying the DetectionCoordinates property as 'Sensor spherical'. The complete form of a spherical state is [az; el; rng; rr], where az, el, rng, and rr represent azimuth angle, elevation angle, range, and range rate, respectively.

When the ElevationResolution property is set to NaN, el  is removed from the spherical coordinates and vz and z are set as 0 in Cartesian coordinates ( 'Body' or 'Sensor rectangular').

When the ElevationResolution and AzimuthResolution properties are set to NaN, az and el are removed from the spherical coordinates, and y, z, vy, and vz are set as 0 in Cartesian coordinates ( 'Body', or 'Sensor rectangular').

The SensorIndex property of the objectDetection object is assigned as per the SensorIndex property of the mmWaveRadar object.

For more details, refer to MeasurementParameters.

You can use the objectDetection objects as the input to multi-object trackers in Sensor Fusion and Tracking Toolbox™.

The convention used by the mmWaveRadar object to report the detections is different from the convention used by Texas Instruments. Refer to Coordinate System for Object Detection Using mmWaveRadar for more information. By converting the detections to follow the convention used by the Radar Toolbox, the detections can be directly processed by tracking filters like the initcvekf function used by radarTracker.

Time in seconds from the time radar starts sending data. The radar starts sending data at the execution of first step after object creation or after calling release(). Upon calling release() or by clearing the mmWaveRadar object, radar stops sending the data.

Timestamp is calculated based on the CPU clock cycles and the frame number obtained from the radar. CPU clock cycles overflow after a period of time. In order to detect and correct the overflow, the frame number and Update Rate of the Radar is used. If the processing time of the radar frame is more than the reciprocal of Update Rate, frame overruns might happen resulting in incorrect time calculation.

Note

Ensure that the parameter required to output point cloud is enabled for the radar to get detections output using MATLAB function. This can be enabled by setting the parameter value corresponding to pointCloud and rangeProfile in the guiMonitor command in the Configuration (.cfg) File. For more details, refer to guiMonitor command description in xWRL6432 MMWAVE-L-SDK: Motion and Presence Detection OOB Demo (for IWRL6432BOOST board), and in the Configuration (.cfg) File Format section in MMWAVE SDK User Guide (for other supported boards).

SNR and noise value will be given as ObjectAttributes property of the corresponding objectDetections object, if the sideInfo output is enabled using guiMonitor command in the Configuration (.cfg) File.

Data Types: double

Structure containing other radar measurements.

Field Description
RangeProfile

Array of Range profile points at 0th Doppler (stationary objects). Use RangeProfile Data with RangeGrid element in the measurement output structure to plot Range Profile. For more details, refer to Read and Plot Position and Range Profile. The units are in dB.

NoiseProfile

Array of profile points at the maximum Doppler bin (maximum speed; objects). In general, for stationary scene, there are no objects or clutter at maximum speed; therefore, the range profile at such speed represents the receiver noise floor. NoiseProfile data with RangeGrid element in the measurement output structure is used to plot Noise Profile. The units are in dB.

IWRL6432BOOST board does not support reading NoiseProfile.

RangeDopplerResponse

Range Doppler detection matrix. Use RangeDopplerResponse, RangeGrid and DopplerGrid along with phased.RangeDopplerScope to visualize Range Doppler Response. For more details, refer Read and Plot Range Doppler Response and Range Azimuth Response. The units are in dB.

IWRL6432BOOST board does not support reading RangeDopplerResponse.

RangeAngleResponse

Range Azimuth Angle Response. Use RangeAngleResponse, RangeGrid and AngleGrid along with phased.RangeAngleScope to visualize Range Angle Response. For more details, refer Read and Plot Range Doppler Response and Range Azimuth Response. The units are in dB.

AOP EVMs and IWRL6432BOOST do not support reading RangeAzimuthResponse.

RangeGrid

Range grid values of response map. RangeGrid denotes the range values at which the response has been computed. The units are in m/s.

DopplerGrid

Doppler grid values of response map.

DopplerGrid denotes the Doppler values at which the response has been computed. The units are in m/s.

AngleGridAzimuth angle grid values of response map. The units are in degrees.

Note

Ensure that the parameter required for the fields corresponding to RangeProfile, NoiseProfile, RangeDopplerResponse and RangeAngleResponse properties are enabled for the radar to get the corresponding output using MATLAB function. These outputs are enabled by setting the parameter value corresponding to pointCloud and rangeProfile in the guiMonitor command in the Configuration (.cfg) File. For more details, refer to guiMonitor command description in xWRL6432 MMWAVE-L-SDK: Motion and Presence Detection OOB Demo (for IWRL6432BOOST board), and in the Configuration (.cfg) File Format section in MMWAVE SDK User Guide (for other supported boards).

Data Types: struct

Number of samples discarded between subsequent calls to the mmWaveRadar object to read data from the Radar.

If the ReadMode is ‘latest’, and if the subsequent reads are not fast enough, multiple output samples are accumulated and only the latest sample is available as output, discarding all the old samples. Overrun output is the number of discarded samples.

Overrun output is 0 if ReadMode is set as 'oldest' because this mode does not discard data, except when there is data drop in transport layer or at the radar board or when you explicitly flush the buffer.

Data Types: double

Note

If the mmWave radar sensor is not configured for a particular output, the syntax returns empty array for the particular output. guiMonitor command in the Configuration (.cfg) file is used to configure radar to provide a particular output.

Object Functions

To use an object function, specify the System object™ as the first input argument. For example, to release system resources of a System object named obj, use this syntax:

release(obj)

expand all

flushFlush the buffer created on the host computer to store Radar data for mmWaveRadar object
sendCommandSend raw serial command to TI mmWave Radar
releaseStop streaming radar data and release the mmWaveRadar object
infoProvides the information about the outputs the radar is configured to generate

Examples

Read Detections using TI IWR6843ISK Radar Sensor

Connect to a TI IWR6843ISK radar connected to the serial port.

rdr = mmWaveRadar("TI IWR6843ISK")
rdr = 

  mmWaveRadar with properties:

              BoardName: "TI IWR6843ISK"
             ConfigPort: "COM4"
               DataPort: "COM5"

             ConfigFile: "C:\ProgramData\MATLAB\SupportPackages\R2023b\toolbox\target\supportpackages\timmwaveradar\configfiles\xwr68xx_2Tx_BestRangeResolution_UpdateRate_10.cfg"
     MMWave SDK Version: "03.06.00.00"

            SensorIndex: 1

       MountingLocation: [0, 0, 0] (m)
         MountingAngles: [0, 0, 0] (degrees)

            UpdateRate: 10 (samples/s)
       RangeResolution: 4.517647e-02 (m)
   RangeRateResolution: 1.206534e-01 (m/s)
     AzimuthResolution: 1.447751e+01 (degrees) 
   ElevationResolution: NaN (degrees) 
          MaximumRange: 1.084235e+01 (m)
      MaximumRangeRate: 9.652273e-01 (m/s)

Show all properties all functions

Read object detections and other measurements from the radar.

[dets,timestamp,meas,overun] = rdr()
dets =

  1×4 cell array

    {1×1 objectDetection}    {1×1 objectDetection}    {1×1 objectDetection}    {1×1 objectDetection}


timestamp =

     0


meas = 

  struct with fields:

            RangeProfile: [88.8979 102.2561 109.1234 107.1479 96.6589 92.2140 85.1350 83.6534 82.6186 78.5735 … ] (1×256 double)
            NoiseProfile: [46.5656 48.3765 49.8111 45.7660 48.6116 47.8355 48.7763 48.4941 48.2589 46.2598 … ] (1×256 double)
    RangeDopplerResponse: []
      RangeAngleResponse: []
               RangeGrid: [0 0.0424 0.0847 0.1271 0.1694 0.2118 0.2541 0.2965 0.3388 0.3812 0.4235 0.4659 0.5082 … ] (1×256 double)
             DopplerGrid: []
               AngleGrid: []


overun =

     0

Version History

Introduced in R2023b

See Also

Topics