Ripple Demo

Table of Contents

• Ripple Overview
• TI Ripple Architecture
• Directory Structure
• Supported Ripple HAL Layer APIs
• Limitations
• How to Build the Demo
• How to Run the Demo
• Data Validation

Ripple Overview

Ripple is an open radar API standard to enable hardware / software interoperability and accelerate the growth of applications for general purpose consumer radar. This standard was developed by the Consumer Technology Association (CTA)’s Ripple Technical Project Group. Ripple APIs provide numerous benefits of Standardized calls, Software library that can work across various radar hardware implementations ensuring reusability and easier firmware Upgrades. With an open API standard, it's easier for integrators to get started, develop, and distribute radar solutions. Standardized software that works across all radar applications can simplify experimentation and prototyping; making radar more accessible to students, startups, academics, and researchers.

Ripple will enable developers to create specialized extensions so that they can build on the standard to support their own differentiated use cases. These extensions can be incorporated as official interfaces in future versions of the standard.

TI Ripple Architecture

TI Ripple Architecture

Ripple Demo on xWRL6432 provides a Hardware Abstraction Layer (HAL) of API library and test application that follows the standards defined in Ripple Radar Sensor API Version 1.1, CTA Specification as of June 2022.

Ripple Demo Consists of the following Layers:

• Ripple HAL Layer: A Hardware Abstraction Layer that consist of an API Library that has APIs that follow ripple standards and can be used to configure and collect ADC data from xwrL6432 TI radar. These APIs are only supported on Linux or Raspberry PI OS. These APIs take user input for configurations and converts it into radar device understood CLI commands.

• Ripple HAL Demo: Simple test application that uses APIs from Ripple HAL Layer to Configure the radar and collect raw ADC data over UART in hexadecimal format to a text File. This demo is only supported to run on Linux or Raspberry PI OS.

• Ripple Demo: Application that needs to be running on the radar’s system to support the APIs called from ripple HAL layer. This application reads the CLI commands coming from HAL Layer and make the corresponding firmware calls to configure the radar’s frontend. When the user starts data streaming, this application writes raw ADC data to UART port after each chirp.

Directory Structure

Directory	Description
ripple_demo	Package that contains both linux level library and corresponding device application
HAL-Demo	A test application that uses Ripple APIs from HAL-Lib. It configures and collects data from radar for a predefined configuration
HAL-Lib	The library that contains definitions to the Ripple defined APIs
ripple_cli	Contains code for command line interface of device application
ripple_flash	Contains code for flash interface of device application
ripple_link	Contains code for control library of device application, this library makes the firmware calls
ripple_pwr	Contains code for power management framework of device application, it helps to set device power modes

Supported Ripple HAL Layer APIs

API:	RadarHandle* radarCreate(int32_t id)
Description:	This API creates and allocates the internal structure(s) required to manage the radar and return a handle for other functions in this API to use to access a specific radar’s capabilities.
Implementation:	This function opens the device serial com ports returns a pointer to a structure that contains serial port file descriptors. This function also sets the default values for vendor specific operating Parameters.
API:	RadarReturnCode radarDestroy(RadarHandle* handle)
Description:	The API provides function to destroy a previously created radar instance.
Implementation:	This function closes device serial ports and clears the radar handle structure created by radar create API.
API:	RadarReturnCode radarSetMainParam(RadarHandle* handle, uint32_t slot_id, RadarMainParam id, uint32_t value)
Description:	The API provides a function to configure main operating parameters.
Implementation:	This function takes main configuration parameters and store the configuration in various structures on the HAL level. The following are the main parameters that should be set: Id Radar Main Param Description CLI Config Command 0 RADAR_PARAM_UNDEFINED A default undefined value that should be used at initialization. - 1 RADAR_PARAM_AFTERBURST_POWER_MODE Power mode for after the burst period. 1 means after burst low power mode is enabled. 0 Means Desabled lowPowerCfg 2 RADAR_PARAM_INTERCHIRP_POWER_MODE Power mode for the period between chirps. Not Supported 3 RADAR_PARAM_BURST_PERIOD_US Duration between the start times of two consecutive bursts. FrameCfg "framePeriodicity" 4 RADAR_PARAM_CHIRP_PERIOD_US Duration between the start times of two consecutive chirps "idleTime" + "rampEndTime" 5 RADAR_PARAM_CHIRPS_PER_BURST Number of chirps within the burst. FrameCfg "NumberOfLoops" 6 RADAR_PARAM_SAMPLES_PER_CHIRP The number of ADC sample values captured for each chirp. chirpComnConfig "numAdcSamples" 7 RADAR_PARAM_LOWER_FREQ_MHZ The lower frequency at what TX antenna starts emitting the signal. chirpTimingCfg "startFreq" 8 RADAR_PARAM_UPPER_FREQ_MHZ The upper frequency at what TX antenna stops emitting the signal. "upperFreq" = ("rampEndTime"*"slope") + "startFreq" 9 RADAR_PARAM_TX_ANTENNA_MASK Bit mask for enabled TX antennas. channelCfg "txChannelEn" 10 RADAR_PARAM_RX_ANTENNA_MASK Bit mask for enabled RX antennas channelCfg "rxChannelEn" 11 RADAR_PARAM_UNUSED_0 Unused parameter. - 12 RADAR_PARAM_ADC_SAMPLING_HZ ADC sampling frequency. chirpComnCfg "digOutSampleRate"
API:	RadarReturnCode radarGetMainParam(RadarHandle* handle, uint8_t slot_id, RadarMainParam id, uint32_t* value)
Description:	The API provides a function to retrieve main operating parameters.
Implementation:	the function returns main operating parameter values stored in the local structures.
API:	RadarReturnCode radarSetTxParam(RadarHandle* handle, uint8_t slotid, uint32_t antenna_mask, RadarTxParam id ,uint32_t value)
Description:	The API provides a function to configure TX antenna specific operating parameters.
Implementation:	This function takes TX antenna specific operating parameters and store the configuration in various structures on the HAL level. The following are the TX antenna specific operating parameters that should be set: Id Radar Tx Param Description CLI Configuration command 0 TX_PARAM_UNDEFINED A default undefined value that should be used at initialization. - 1 TX_PARAM_POWER_DB A TX antenna’s emitting power in dB. factoryCalibCfg "txOutPower"
API:	RadarReturnCode radarGetTxParam(RadarHandle* handle, uint8_t slot_id, uint32_t antenna_mask, RadaRxParam id, uint32_t* value)
Description:	The API provides a function to retrieve TX antenna specific operating parameters.
Implementation	The function returns TX antenna specific operating parameter values stored in the local structures.
API:	RadarReturnCode radarSetRxParam(RadarHandle* handle, uint8_t slotid, uint32_t antenna_mask, RadarRxParam id ,uint32_t value)
Description:	The API provides a function to configure RX antenna specific operating parameter.
Implementation:	This function takes RX antenna specific operating parameters and store the configuration in various structures on the HAL level. The following are the TX antenna specific operating parameters that should be set: Id Radar Rx Param Description CLI Configuration command 0 RX_PARAM_UNDEFINED A default undefined value that should be used at initialization. - 1 RX_PARAM_VGA_DB Variable Gain Amplifiers (VGA) in dB. factoryCalibCfg "rxGain" 2 RX_PARAM_HP_GAIN_DB High Pass (HP) filter gain in dB. NOT Supported 3 RX_PARAM_HP_CUTOFF_KHZ High Pass (HP) cut off frequency in kHz. NOT Supported
API:	RadarReturnCode radarGetRxParam(RadarHandle* handle, uint8_t slot_id, uint32_t antenna_mask, RadaRxParam id, uint32_t* value)
Description:	The API provides a function to retrieve RX antenna specific operating parameters.
Implementation:	The function returns RX antenna specific operating parameter values stored in the local structures.
API:	RadarReturnCode radarSetVendorParam(RadarHandle* handle, uint32_t slot_id, RadarVendorParam id, uint32_t value)
Description:	The API provides a function to configure the TI specific sensor operating parameters.
Implementation:	This function takes vendor specific operating parameters and store the configuration in various structures on the HAL level. Although the vendor specific parameters are configured to their default values, so they are not required to be set for basic operation of device. Id Radar Vendor Specific Parameter Description Default Values 0 RADAR_VENDOR_PARAM_UNDEFINED A default undefined value that should be used at initialization. - 1 RADAR_VENDOR_PARAM_CHIRP_IDLE_TIME Time period Between Ramp End and Ramp Start time (in us). It is used to calculate and configure chirp’s Ramp End time. 2950 us 2 RADAR_VENDOR_PARAM_NUM_OF_BURST Number of bursts that the user wants to receive can be configured. If set to 0 it means infinite bursts. 5 Bursts
API:	RadarReturnCode radarGetVendorParam(RadarHandle* handle, uint8_t slot_id, RadarVendorParam id, uint32_t* value)
Description:	The API provides a function to retrieve vendor specific operating parameters.
Implementation:	The function returns vendor specific operating parameter values stored in the local structures.
API:	RadarReturnCode radarActivateConfig(RadarHandle* handle, int8_t slot_id)
Description:	The API provide a function to activate the configurations.
Implementation:	The Function converts all the configurations set by radarSetMainParam, radarSetTxParam, radarSetRxParam and radarSetVendorParam to CLI commands by performing necessary calculations when required. The function then sends the CLI Commands to the radar.
API:	RadarReturnCode radarStartDataStreaming(RadarHandle* handle)
Description:	The API provides a function to start running the radar with the provided configuration and starts emitting data.
Implementation:	The function sends the CLI command “sensorStart” to the radar.
API:	RadarReturnCode radarReadBurst(RadarHandle* handle, RadarBurstFormat* format, uint8_t* buffer, uint32_t* read_bytes, timespec_t timeout)
Description:	The API provides a function to read a single data burst.
Implementation:	The function reads data from serial port of exact size equivalent of one burst into buffer.
API:	RadarReturnCode radarSetBurstReadyCb(RadarHandle* handle, RadarBurstReadyCB cb, void* user_data)
Description:	The API provides a means to register a callback to be invoked when Burst Data is ready to be read.
Implementation:	The function registers the OnBurstReady callback which calls radarReadBurst function to read Burst data from the radar. OnBurstReady callback is invoked for each newly available set of burst data.
API:	RadarReturnCode radarStopDataStreaming(RadarHandle* handle)
Description:	The API provides a function to stop running the radar which will stop capturing and sending data from radar.
Implementation:	The function writes the CLI command “sensorStop” to the radar.

Limitations

• As UART is used for burst data transfer, the Baud rate is limited to 1250000bps as a result chirp idle time get limited to 2200us for lossless data transfer. Chirp Size should be kept less than 256 bytes. When Baud rate of 833333bps is used the chirp idle time should be kept at least 2950us.
• Chirp Size = Number of Rx * Number of ADC Samples * 2

How to Build the Demo

1. Steps to build the Host (Linux/Raspberry pi) Demo:
   • Open the terminal in “HAL-Demo” directory and run the command “make”
2. Steps to build the device Demo:
   • Install the MMWAVE-L-SDK
   • Build the target files using following command.

     gmake -s -C examples/ripple_demo/xwrL64xx-evm/m4fss0-0_freertos/ti-arm-clang all

How to Run the Demo

1. Flash the target ‘ripple_demo.release.appimage’ built in examples/ripple_demo/xwrL64xx-evm/m4fss0-0_freertos/ti-arm-clang to the device using visualizer tool.
2. Switch the device to Functional mode and keep the following switch settings:

   S1.1	S1.2	S1.3	S1.4	S1.5	S1.6
   On	Off	On	Off	On	On

   S4.1	S4.2	S4.3	S4.4
   Off	Off	Off	On

3. Connect xWRL6432 to your Linux/Raspberry Pi host.
4. Open the terminal in the HAL_Demo directory and run the demo using "./Demo" command.
5. Enter the Application/UART COM Port Number "/dev/ttyxxxx" and press Enter.
6. Enter the Auxiliary Data COM Port Number "/dev/ttyxxxx" and press Enter.
7. Burst data collected will be saved in rawADCHex.txt file inside HAL_Demo directory.

Data Validation

1. Matching the last chirp data from Memory: The last received chirp matched exactly to ones from memory starting from ADC Buffer Start Address.

2. Range-Doppler Heat Map: We collected two sets of burst data, one without any object in front of radar and other with a corner reflector and performed range and doppler Fast Fourier Transforms on both the datasets and plotted the Heat map. We observed a sharp object in the one with corner reflector. The following is a Snapshot of both plots: