Ripple Demo

Table of Contents

• Ripple Overview
• TI Ripple Architecture
• Directory Structure
• Supported Ripple HAL Layer APIs
• How to Build the Demo
• How to Run the Demo
• Setting up ADC data capture via SPI
• Post Processing of ADC data
• Limitations

Ripple Overview

Ripple is an open radar API standard that enables hardware and software interoperability, accelerating the growth of applications for general-purpose consumer radar. This standard was developed by the Ripple Technical Project Group of the Consumer Technology Association (CTA). Ripple APIs offer several benefits, including standardized calls and a software library that can function across various radar hardware implementations, ensuring reusability and easier firmware upgrades. An open API standard makes it easier for integrators to begin, develop, and distribute radar solutions. Standardized software that works across all radar applications simplifies 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.

• 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 SPI 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 the 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.

How to Build the Demo

1. Install the MMWAVE-L-SDK on Host(Linux).
2. Steps to build the Host (Linux) demo:
   • Open the terminal in “HAL-Demo” directory and run the command “make”. This builds the host demo executable.
3. Steps to build the device(xwrLx4xx) demo (if not already built):
   • Build the target files using following command.

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

How to Run the Demo

1. Connect xWRL6432 to your host.
2. 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.
3. 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

4. Saleae logic analyzer (Logic Pro 8 or above) can be used to capture burst data (Raw ADC data) data. Details of setup can be found at 'Setting up ADC data capture via SPI' section below.
5. On Linux host, once the setup is ready as per previous step, start capture of SPI data in the Logic Software by pressing 'Start' button. Then, open the terminal in the HAL_Demo directory and run the demo using "./Demo" command.
6. Enter the Application/UART COM Port Number "/dev/ttyxxxx" and press Enter.

7. As the demo runs, SPI waveforms are captured in Logic software. Data received can be seen in 'Data' tab of 'Analyzers' window.

   

8. Export the data to a text file for post processing.

Setting up ADC data capture via SPI

• ADC data is transferred out via SPI after every chirp.
• Device configures SPI interface as follows:
  • Speed: 28Mhz
  • Data Width: 32 bits (MSB first)
  • Chip select: Active Low
  • SPI Mode: 0 (CPOL = 0, CPHA = 0)
• Connect the Saleae logic analyzer to device (xWRL6432) as shown below. On host, install the Logic software to capture the data.

• In Logic software, configure for SPI analyzer (as per configurations above) in 'analyzers' window to capture SPI data. Configure for sampling rate more than or equal to 100 MS/s.

Post Processing of ADC data

1. processAdcData.m is a matlab script that can be used for parsing the ADC data collected via SPI. It is placed at /examples/ripple_demo/ADCDataProcessing. This folder has reference ADC data file and reference config file as well.

2. Run the below command in the MATLAB command window:

   frameAdcData = processAdcData(<adcDataFname>, <cfgFname>);

   Two input arguments:
    a. adcDataFname: .txt file containing ADC data in hexadecimal format as described below (already streamed by SPI in this format)
   

   

    b. cfgFname: .cfg file containing the radar CLI used to collect the ADC data.
   Output:
    frameAdcData: It returns ADC data of a frame in format [RX*TX][Samples][Chirps].
   

3. The script does the following operations:
    a. Parse the ADC data of the format described above into ‘int16’ samples array.
    b. Parse the .cfg file used to collect the ADC data using the ripple demo.
    c. ADC data is reshaped in in format [RX*TX][Samples][Chirps].
    d. First FFT is done on samples to resolve the range, then FFT is done across the chirps to resolve the doppler.
    e. 2d-FFT plot (detection matrix) is plotted every frame and the range fft vs Chirps for all the frames is plotted at the last.
   

Sample Plots:

Limitations

• The ADC data for every chirp is transfered during chirp idle time. Hence, users have to ensure that sufficient chirp idle time is available so as to transfer all the SPI data. Eg: When 128 ADC samples (256 bytes) are configured per chirp, we need atleast ~140usec as chirp idle time.
• BPM-MIMO scheme is not supported by the Matlab post processing script.