To understand the data output from the EVM, it is important to understand how the device itself works. The mmWave radar sensor is a Frequency-Modulated Continuous Wave (FMCW) radar sensor that is able to detect the range, velocity, and angle of objects. To operate this device, configurations determining the properties of the chirps transmitted from the radar are sent via configuration commands/files in a Command Line Interface (CLI) to the device via UART.
When the chirp returns after bouncing off an object, it is mixed with the original transmit chirp to determine range, velocity, and angle. The resulting signal is digitized and organized into a Type Length Value structure (TLV) based on the demo being run. This information is then packed into an output structure and sent back to the computer via UART. The current UART output is sent out every frame as a packet containing a frame header and TLV.
Each TLV item in the packet payload contains a data type and value (payload) containing information describing that type of information. The length of the packet can depend on the number of detected objects and vary from frame to frame. To maintain uniformity amongst packets, each packet is padded so that the length is a multiple of 32 bytes. The UART information is sent out from the EVM board to the USB port of the computer and then parsed to process and display the results onto a GUI visualizer.
📝NOTE: For more information on xWRLx432 TLVs and output data (SDK 5.x) refer to section 13 of the implementation guide located at /docs/MotionPresenceDetectionDemo_documentation.pdf.
Frame Header
Length: 40 Bytes
A Frame Header is sent at the start of each packet. Use the Magic Word to find the start of each packet. The frame header is setup differently than the output TLVs. The frame header is setup to be rigid as it will always come first and always be in the same format, as a result it is based off of its own struct named MmwDemo_output_message_header with defined struct members.
Value
Type
Bytes
Details
Magic Word
uint16_t
8
Output buffer magic word (sync word). It is initialized to {0x0102,0x0304,0x0506,0x0708}
Version
uint32_t
4
SDK Version represented as (MajorNum x 2^24 + MinorNum x 2^16 + BugfixNum x 2^8 + BuildNum)
Total Packet Length
uint32_t
4
Total packet length including frame header length in Bytes
Platform
uint32_t
4
Device type (ex 0xA6843 for IWR6843 devices)
Frame Number
uint32_t
4
Frame number (resets to 0 when device is power cycled or reset. Not when sensor stop/start is issued.)
Time [in CPU Cycles]
uint32_t
4
Time in CPU cycles when the message was created.
Num Detected Obj
uint32_t
4
Number of detected objects (points) for the frame
Num TLVs
uint32_t
4
Number of TLV items for the frame.
Subframe Number
uint32_t
4
0 if advanced subframe mode not enabled, otherwise the sub-frame number in the range 0 to (number of subframes - 1)
TLV Header
Length: 8 Bytes
The number of TLVs in the frame packet is extracted from the Frame Header. For each TLV in the packet, there is a TLV Header containing Type and Length information. The Type identifier indicates what kind of information is contained in the payload. The Length value gives the length of the payload.
Value
Type
Bytes
Details
Type
uint32_t
4
Indicates types of message contained in payload.
Length
uint32_t
4
Length of the payload in Bytes (does not include length of the TLV header)
TLV Toggling with guiMonitor
The parameters in the CLI command guiMonitor are used to enable or disable whether the TLV type is included in the output frame packet. The parameters are as follows: guiMonitor <subFrameIdx> <detected objects> <log magnitude range> <noise profile> <rangeAzimuth(Elevation)HeatMap> <rangeDopplerHeatMap> <statsInfo>
For the Out of Box demo, if type contains the following value then the payload contains the information listed under value type and should be parsed accordingly.
Type Identifier
Value Type
Condition for output
1
Detected Points
<detected objects> is set to 1 or 2 AND there are detected objects for the frame, else this type is not sent for that frame
2
Range Profile
<log magnitude range> is set to 1; occurs every frame
3
Noise Floor Profile
<noise profile> is set to 1; occurs every frame
4
Azimuth Static Heatmap
<rangeAzimuth(Elevation)HeatMap> is set to 1 AND demo is not for AOP or ODS which use AOA2D; occurs every frame
5
Range-Doppler Heatmap
<rangeDopplerHeatMap> is set to 1; occurs every frame
6
Statistics (Performance)
<statsInfo> is set to 1; occurs every frame
7
Side Info for Detected Points
<detected objects> is set to 2 AND there are detected objects for the frame, else this type is not sent for that frame
8
Azimuth/Elevation Static Heatmap
<rangeAzimuth(Elevation)HeatMap> is set to 1 AND demo is for AOP or ODS which use AOA2D; occurs every frame
9
Temperature Statistics
<statsInfo> is set to 1; occurs every frame
Availability of Universal TLV’s in Labs
The list below covers TLVs that can be found across all mmWave radar example demos. Clicking on a type name will take you to the appropriate section. Note that TLVs with similar functions will have different type identifer based off of the source. Some demos will have TLVs only from one of the SDKs and others will have TLVs from both the SDK and Radar Toolbox.
Array of profile points at 0th Doppler (stationary objects). The points represent the sum of log2 magnitudes of received antennas expressed in Q9 format.
xWRLx432
Range Profile Major
Type Identifier
Type Value
Length
Value
302
MMWDEMO_OUTPUT_EXT_MSG_RANGE_PROFILE_MAJOR
(Number Of Range Bins) x (4 Bytes)
Array of 32-bit unsigned linear values of range bins for major motion. The length is equal to number of range bin elements
Range Profile Minor
Type Identifier
Type Value
Length
Value
303
MMWDEMO_OUTPUT_EXT_MSG_RANGE_PROFILE_MINOR
(Number Of Range Bins) x (4 Bytes)
Array of 32-bit unsigned linear values of range bins for major motion. The length is equal to number of range bin elements
Noise Profile
Type Identifier
Type Value
Length
Value
3
MMWDEMO_OUTPUT_MSG_NOISE_PROFILE
(Range FFT size) x (2 Bytes)
Array of profile points at max Doppler bin. In general for stationary scene, there would be no objects or clutter at maximum speed so the range profile at such speed represents the receiver noise floor.
Azimuth Static Heatmap
Type Identifier
Type Value
Length
Value
4
MMWDEMO_OUTPUT_MSG_AZIMUT_STATIC_HEAT_MAP
(Range FFT size) x (Number of “azimuth” virtual antennas) x (4 Bytes)
Samples to calculate static azimuth heatmap (no moving object signal). This is a 2D FFT array in range direction (x[numRangeBins][numVirtualAntAzim]), at doppler index 0.
The antenna data are complex symbols, with imaginary first and real second in the following order:
Imag(ant 0, range 0), Real(ant 0, range 0),…,Imag(ant N-1, range 0),Real(ant N-1, range 0)
…
Imag(ant 0, range R-1), Real(ant 0, range R-1),…,Imag(ant N-1, range R-1),Real(ant N-1, range R-1)
This means the first 4 bytes of the payload is the radar cube complex value of the first range bin for the first virtual antenna(N=1). The last 4 bytes is for the last range bin (R) and the last virtual antenna (N). The values from the radar cube are used to construct the range-azimuth heatmap in the visualizer.
Range-Doppler Heatmap
Type Identifier
Type Value
Length
Value
5
MMWDEMO_OUTPUT_MSG_RANGE_DOPPLER_HEAT_MAP
(Range FFT size) x (Doppler FFT size) x (2 Bytes)
Range/Doppler detection matrix.
X(range bin 0, Doppler bin 0),…,X(range bin 0, Doppler bin D-1),
…
X(range bin R-1, Doppler bin 0),…,X(range bin R-1, Doppler bin D-1)
Statistics
Type Identifier
Type Value
Length
Value
6
MMWDEMO_OUTPUT_MSG_STATS
24 Bytes
Statistical performance information from data path.
See the doxygen for detailed explanation of each stat.
Value
Type
Bytes
interFrameProcessingTime [usec]
uint32_t
4
transmitOutputTime[usec]
uint32_t
4
interFrameProcessingMargin [usec]
uint32_t
4
interChirpProcessingMargin [usec]
uint32_t
4
activeFrameCPULoad [%]
uint32_t
4
interFrameCPULoad [%]
uint32_t
4
Side Info for Detected Points
Type Identifier
Type Value
Length
Value
7
MMWDEMO_OUTPUT_MSG_DETECTED_POINTS_SIDE_INFO
4 Bytes x Num Detected Obj
Provides side info which includes the Signal-to-Noise Ratio (SNR) and Noise
The payload consists of 4 bytes for EACH point in the point cloud. The values for snr and noise are measured in multiples of 0.1dB.
(Range FFT size) x (Number of all virtual antennas) x (4 Bytes)
Samples to calculate static azimuth or elevation heatmap (no moving object signal). This is a 2D FFT array in range direction (x[numRangeBins][numVirtualAntAzim]), at doppler index 0.
The antenna data are complex symbols, with imaginary first and real second in the following order:
Imag(ant 0, range 0), Real(ant 0, range 0),…,Imag(ant N-1, range 0),Real(ant N-1, range 0)
…
Imag(ant 0, range R-1), Real(ant 0, range R-1),…,Imag(ant N-1, range R-1),Real(ant N-1, range R-1)
📝NOTE: The demo will only output either the Azimuth Static Heatmap OR the Azimuth/Elevation Static Heatmap
Temperature Statistics
Type Identifier
Type Value
Length
Value
9
MMWDEMO_OUTPUT_MSG_TEMPERATURE_STATS
28 Bytes
Temperature report - snapshot taken just before shipping data over UART.
Table of each temperature reading sent is shown below:
Value
Type
Bytes
tempReportValid (used to know if values are valid)
uint32_t
4
time (radarSS local Time from device powerup) [1LSB = 1ms]
uint32_t
4
tmpRx0Sens [1 LSB = 1 deg C]
uint16_t
2
tmpRx1Sens [1 LSB = 1 deg C]
uint16_t
2
tmpRx2Sens [1 LSB = 1 deg C]
uint16_t
2
tmpRx3Sens [1 LSB = 1 deg C]
uint16_t
2
tmpTx0Sens [1 LSB = 1 deg C]
uint16_t
2
tmpTx1Sens [1 LSB = 1 deg C]
uint16_t
2
tmpTx2Sens [1 LSB = 1 deg C]
uint16_t
2
tmpPmSens [1 LSB = 1 deg C]
uint16_t
2
tmpDig0Sens [1 LSB = 1 deg C]
uint16_t
2
tmpDig1Sens [1 LSB = 1 deg C] (Not valid for devices without DSP)
uint16_t
2
Detected Points Compressed
Type Identifier
Type Value
Length
Value
301
MMWDEMO_OUTPUT_EXT_MSG_DETECTED_POINTS
20 Bytes + (10 Bytes x Num Detected Obj)
Compressed version of the point cloud in Cartesian coordinates
Every point value must be multiplied by its appropriate point cloud unit value to get true value.
Example: A point’s real x coordinate will be x * xyzUnit
Consists of two dimensional array of 32-bit unsigned magnitude values.
The matrix is arranged as:
X[rangeInd*azimuthFftSize+azimuthInd], rangeInd = 0, numRangeBins - 1, azimuthInd = 0, azimuthFftSize – 1
Statistics Performance
Type Identifier
Type Value
Length
Value
306
MMWDEMO_OUTPUT_EXT_MSG_STATS
24 Bytes
Statistical performance information from data path.
See the doxygen for detailed explanation of each stat.
Value
Type
Bytes
interFrameProcessingTime [usec]
uint32_t
4
transmitOutputTime[usec]
uint32_t
4
powerMeasured[4] (1LSB = 100 uW)
uint16_t[4]
8
tempReading[4] (1LSB = 1*C)
uint16_t[4]
8
Micro Doppler Raw Data
Type Identifier
Type Value
Length
Value
310
MMWDEMO_OUTPUT_EXT_MSG_MICRO_DOPPLER_RAW_DATA
numTrackedObjects x numDopplerBins x 4 Bytes
Array of micro-Doppler spectra of the tracked targets, corresponding to target IDs sent in the tracker data TLV. The samples are stored in float format as dopplerData[targetIndex][DopplerIndex].
This TLV contains micro-Doppler spectra of the tracked objects. Note that this TLV is sent to host when all of the following conditions are satisfied:
The group tracker is enabled in the CLI command trackingCfg,
The micro-Doppler DPU is enabled in the CLI command microDopplerCfg,
The tracking data enable bit is enabled in the CLI command guiMonitor,
The micro-Doppler data enable bit is enabled in the CLI command guiMonitor,
The number of tracking objects in the current frame is greater than zero.
Micro Doppler Feature Extraction
Type Identifier
Type Value
Length
Value
311
MMWDEMO_OUTPUT_EXT_MSG_MICRO_DOPPLER_FEATURES
numTrackedObjects x numberOfFeatures x 4 Bytes
Array of features sets, corresponding to target IDs sent in the tracker data TLV. The features are stored in a floating point format as features[targetIndex][featureIndex]
This TLV contains features extracted from the micro-Doppler FFT. It is sent out along with the Micro-Doppler Raw Data TLV, and thus must satisfy the same configuration requirements.
Radar Cube Major
Type Identifier
Type Value
Length
Value
312
MMWDEMO_OUTPUT_EXT_MSG_RADAR_CUBE_MAJOR
Size of a frame of input data
The radar cube can be used for debugging and verification. The demo must run in test mode, where the ADC samples are taken from the file, and after the frame processing the radar cube data are sent to host for verification against a MATLAB reference.
Radar Cube Minor
Type Identifier
Type Value
Length
Value
313
MMWDEMO_OUTPUT_EXT_MSG_RADAR_CUBE_MINOR
Size of a frame of input data
The radar cube can be used for debugging and verification. The demo must run in test mode, where the ADC samples are taken from the file, and after the frame processing the radar cube data are sent to host for verification against a MATLAB reference.
This TLV contains the presence information for number of zones defined in the radar scene. The information for each zone is represented with 2 bits, packed in bytes starting from LSB position towards MSB.
0 – no detection
1 – minor motion detected
2 – major motion detected
3 – major and minor motion detected
ADC Samples
Type Identifier
Type Value
Length
Value
316
MMWDEMO_OUTPUT_EXT_MSG_ADC_SAMPLES (xWRx843)
NumADCSamples x NumRxChannels x NumTxChannels * 4 Bytes
Sends last two chirps for two TX and last one chirp for one TX recorded and stored in ping/pong buffer for xWRx843
316
MMWDEMO_OUTPUT_EXT_MSG_ADC_SAMPLES (xWRLx432)
NumADCSamples x NumRxChannels x NumTxChannels * 2 Bytes
Sends last two chirps for two TX and last one chirp for one TX recorded and stored in ping/pong buffer for xWRLx432
Array of classifier outcome in Q7 format, packed as classOutcome[targetIndex][classIndex]
This TLV is sent to host when all of the following conditions are satisfied:
The group tracker is enabled in the CLI command trackingCfg,
The micro-Doppler DPU is enabled in the CLI command microDopplerCfg,
The tracking data enable bit is enabled in the CLI command guiMonitor,
The micro-Doppler data enable bit is enabled in the CLI command guiMonitor,
The number of tracking objects in the current frame is greater than zero.
RX Channel Compensation Info
Type Identifier
Type Value
Length
Value
318
MMWDEMO_OUTPUT_EXT_MSG_RX_CHAN_COMPENSATION_INFO
4 Bytes + (4 Bytes x (2 x Num TX Antennas x Num RX Channels))
Array of RX Channel compensations coefficients, in Q20 format
Array is in the form of X[NumTX][NumRX] where
RX order is 0,1,….SYS_COMMON_NUM_RX_CHANNEL - 1 and
TX order is 0,1,….SYS_COMMON_NUM_TX_ANTENNAS - 1
Spherical Coordinates
Type Identifier
Type Value
Length
Value
1000
MMWDEMO_OUTPUT_MSG_SPHERICAL_POINTS
Number of Points x 16 Bytes
Point cloud in spherical coordinates
The payload consists of 4 elements for each point in the point cloud: Range(meters), Azimuth(radians), Elevation(radians), and Doppler(meters/second). Each element is 4 bytes.
Value
Type
Bytes
Range [m]
float
4
Azimuth [rad]
float
4
Elevation [rad]
float
4
Doppler [m/s]
float
4
3D Target List
xWR6843
Type Identifier
Type Value
Length
Value
1010
MMWDEMO_OUTPUT_MSG_TRACKERPROC_3D_TARGET_LIST
Number of Targets x 112 Bytes
Set of values that describe the 3 dimensional position and motion of the target being tracked, include position, velocity, acceleration, as well as error measurements for the track.
xWRLx432
Type Identifier
Type Value
Length
Value
308
MMWDEMO_OUTPUT_EXT_MSG_TARGET_LIST
Number of Targets x 112 Bytes
Set of values that describe the 3 dimensional position and motion of the target being tracked, include position, velocity, acceleration, as well as error measurements for the track.
Tracker Proc struct
Value
Type
Bytes
tid - Track ID
uint32_t
4
posX - Target Position (meters) in X dimension
float
4
posY - Target Position (meters) in Y dimension
float
4
posZ - Target Position (meters) in Z dimension
float
4
velX - Target Velocity (meters/second) in X dimension
float
4
velY - Target Velocity (meters/second) in Y dimension
float
4
velZ - Target Velocity (meters/second) in Z dimension
float
4
accX - Target Acceleration (meters/second^2) in X dimension
float
4
accY - Target Acceleration (meters/second^2) in Y dimension
float
4
accZ - Target Acceleration (meters/second^2) in Z dimension
float
4
ec[16] - Tracking error covariance matrix
float
64
g - Gating function gain
float
4
confidenceLevel
float
4
Target Index
xWR6843
Type Identifier
Type Value
Length
Value
1011
MMWDEMO_OUTPUT_MSG_TRACKERPROC_TARGET_INDEX
Number of Points x 1 Byte
Contains target ID, allocating every point to a specific target or no target
xWRLx432
Type Identifier
Type Value
Length
Value
309
MMWDEMO_OUTPUT_EXT_MSG_TARGET_INDEX
Number of Points x 1 Byte
Contains target ID, allocating every point to a specific target or no target
Target Height
Type Identifier
Type Value
Length
Value
1012
MMWDEMO_OUTPUT_MSG_TRACKERPROC_TARGET_HEIGHT
Number of Points x 12 Bytes
Contains target ID, then then the maximum Z estimate given as a float and the minimum Z estimate given as a float.
Value
Type
Bytes
targetID - Target ID
uint32_t
4
maxZ - Target maxZ estimate
float
4
minZ - Target minZ estimate
float
4
3D Spherical Compressed Point Cloud
Type Identifier
Type Value
Length
Value
1020
MMWDEMO_OUTPUT_MSG_COMPRESSED_POINTS
20 Bytes + (8 Bytes x Number of Points)
Contains the compressed point cloud and corresponding unit values needed to get actual coordinate
Defines the point cloud and corresponding elements. It is split into two structs, one that defines the point cloud, and one that defines that the individual points in the cloud. The unit value acts as a scale for individual point values. By splitting the value into unit/range values, we reduce how much information needs to be parsed, at the cost of some accuracy.
Point Cloud struct
Value
Type
Bytes
elevationUnit
float
4
azimuthUnit
float
4
dopplerUnit
float
4
rangeUnit
float
4
snrUnit
float
4
Point struct
Value
Type
Bytes
elevation
int8
1
azimuth
int8
1
doppler
int16
2
range
uint16
2
snr
uint16
2
Presence Detection
Type Identifier
Type Value
Length
Value
1021
MMWDEMO_OUTPUT_MSG_PRESCENCE_INDICATION
4 Bytes
Indicates whether some presence has been detected in the field of view of the radar
Occupancy State Machine Output
Type Identifier
Type Value
Length
Value
1030
MMWDEMO_OUTPUT_MSG_OCCUPANCY_STATE_MACHINE
4 Bytes
Bitmask indicating which zone is occupied during small object detection.
If bit 1 is set to 1, zone 1 is occupied, and if zone 1 is 0, zone 1 is not occupied
