A121 Sparse IQ Service

User Guide
 A121 Sparse IQ Service

A121 Sparse IQ Service

User Guide

Author: Acconeer AB

Version:a121-v1.6.0

Acconeer AB April 19, 2024

© 2024 by Acconeer AB - All rights reserved Page 1 of 22

 A121 Sparse IQ Service

Contents

1 Acconeer SDK Documentation Overview 4

2 Introduction 5

3 IQ Radar Data 5

4 API Usage 5
4.1 Initializing the System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
4.2 Setting up the Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
4.2.1 Register HAL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
4.2.2 Create Config . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
4.2.3 Create Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
4.2.4 Allocate Memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
4.2.5 Create Sensor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
4.2.6 Calibrate Sensor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
4.2.7 Prepare Sensor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
4.3 Data Retrieval and Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
4.3.1 Measure and Read Data from Sensor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
4.3.2 Data Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
4.4 Shutdown and Memory De-allocation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
4.5 Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
4.5.1 Number of Subsweeps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
4.5.2 Continuous Sweep Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
4.5.3 Idle States . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
4.5.4 Double Buffering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

5 Sensor Calibration 12
5.1 Sensor Re-calibration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
5.2 Sensor Calibration Caching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

6 Indication Handling 12
6.1 Data Saturated . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
6.2 Frame Delayed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
6.3 Calibration Needed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
6.4 Temperature . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

7 Examples 13
7.1 Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
7.2 Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
7.3 Advanced Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
7.4 Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

8 Communication Issues 14

9 Advanced Sensor Control 14

9.1 Sequential vs Parallel Control Flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
9.2 Inter Frame and Inter Sweep Idle States . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
9.2.1 Deep Sleep . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
9.2.2 Sleep . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
9.2.3 Ready . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
9.3 Double Buffering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
9.4 Continuous Sweep Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
9.5 High Speed Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

10 Memory 19
10.1 Flash . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
10.2 RAM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

11 A121 vs A111 19

© 2024 by Acconeer AB - All rights reserved Page 2 of 22

 A121 Sparse IQ Service

12 Sparse IQ Configuration Parameters 21

13 Disclaimer 22

© 2024 by Acconeer AB - All rights reserved Page 3 of 22

 A121 Sparse IQ Service

1 Acconeer SDK Documentation Overview

To better understand what SDK document to use, a summary of the documents are shown in the table below.

Table 1: SDK document overview.

Name Description When to use

RSS API documentation (html)
- RSS application implementation
rss api The complete C API documentation.
- Understanding RSS API functions
User guides (PDF)
Describes the Acconeer assembly - Bring-up of HW/SW
A121 Assembly Test
test functionality. - Production test implementation
A121 Breathing Describes the functionality of the - Working with the Breathing
Reference Application Breathing Reference Application. Reference Application
Describes usage and algorithms
A121 Distance Detector - Working with the Distance Detector
of the Distance Detector.
Describes how to implement each
- SW implementation of
A121 SW Integration integration function needed to use
custom HW integration
the Acconeer sensor.
Describes usage and algorithms
A121 Presence Detector - Working with the Presence Detector
of the Presence Detector.
A121 Smart Presence Describes the functionality of the - Working with the Smart Presence
Reference Application Smart Presence Reference Application. Reference Application
Describes usage of the Sparse IQ
A121 Sparse IQ Service - Working with the Sparse IQ Service
Service.
A121 Tank Level Describes the functionality of the - Working with the Tank Level
Reference Application Tank Level Reference Application. Reference Application
A121 Touchless Button Describes the functionality of the - Working with the Touchless Button
Reference Application Touchless Button Reference Application. Reference Application
A121 Parking Describes the functionality of the - Working with the Parking
Reference Application Parking Reference Application. Reference Application
Describes the flow of taking an
A121 STM32CubeIDE Acconeer SDK and integrate into - Using STM32CubeIDE
STM32CubeIDE.
Describes how to develop for
A121 Raspberry Pi Software - Working with Raspberry Pi
Raspberry Pi.
Describes how to develop for - Working with Ripple
A121 Ripple
Ripple. on Raspberry Pi
Describes how to develop for
XM125 Software - Working with XM125
XM125.
Describes how to develop for
XM126 Software - Working with XM126
XM126.
Describes the functionality of the - Working with the
I2C Distance Detector
I2C Distance Detector Application. I2C Distance Detector Application
Describes the functionality of the - Working with the
I2C Presence Detector
I2C Presence Detector Application. I2C Presence Detector Application
Describes the functionality of the - Working with the
I2C Breathing Reference Application
I2C Breathing Reference Application. I2C Breathing Reference Application
Handbook (PDF)
Describes different aspects of the
- To understand the Acconeer sensor
Handbook Acconeer offer, for example radar
- Use case evaluation
principles and how to configure
Readme (txt)
Various target specific information
README - After SDK download
and links

© 2024 by Acconeer AB - All rights reserved Page 4 of 22

 A121 Sparse IQ Service

2 Introduction

The Sparse IQ Service is used to control the Acconeer A121 sensor and retrieve radar data from it. Below is an overview
image of how to use the Service API together with the HAL integration in an application.

The focus of this User Guide is the Service API.

It is recommended to use this Guide together with example service.c located in the SDK package. The full API
specification, rss api.html, provided in the SDK package is also good to use with this Guide.

3 IQ Radar Data

The Sparse IQ Service provides radar data in a complex format. In order to make sense of the data some kind of processing
usually needs to be done. Examples of processing can be found in the processing examples provided in the SDK. This
includes, among others, amplitude, mean, and interpolation processing.
To read more about how to interpret the IQ data, see docs.acconeer.com.
It is highly recommended to use the Acconeer Exploration Tool together with an Acconeer Evaluation Kit, EVK, to
explore how the IQ data looks like and how it can be used. For more information on the Acconeer EVKs, see
www.acconeer.com/products. For more information on Exploration Tool, see
github.com/acconeer/acconeer-python-exploration.

4 API Usage

The Service API can be divided into five SW modules. See image below.

© 2024 by Acconeer AB - All rights reserved Page 5 of 22

 A121 Sparse IQ Service

RSS:
• Initialize the RSS library by registering integration functions
• Get memory size needed by RSS for a specific config
• Set log level

Config:
• Get and set Service configuration
• Print current configuration

Sensor:
• Communicate with the sensor, examples include
– Calibrate the sensor
– Configure the sensor
– Do a measurement
– Read raw data from sensor

Processing
• Convert unreadable raw data to Sparse IQ data
• Convert unreadable raw data to indications

HAL Integration:
• Retrieve integration functions needed by RSS library
• Direct pin communication with the sensor, such as
– Enable / disable sensor
– Wait for interrupt

4.1 Initializing the System

The HAL must be registered to the Radar System Software (RSS) before any other calls are done. The registration
requires a pointer to an acc hal a121 t struct which contains information on the hardware integration and function
pointers to hardware driver functions needed by RSS. The acc hal a121 t struct is retrieved by the function
acc hal rss integration get implementation(). See the “Software Integration” chapter in the document “A121 SW
Integration User Guide” for more information on how to integrate the driver layer and populate the hal struct.

© 2024 by Acconeer AB - All rights reserved Page 6 of 22

 A121 Sparse IQ Service

4.2 Setting up the Service

Below is a step by step guide of how to setup and configure the Service.

4.2.1 Register HAL

The HAL must be registered to the Radar System Software (RSS) before any other calls are done.
const acc_hal_a121_t * hal = a c c _ h a l _ r s s _ i n t e g r a t i o n _ g e t _ i m p l e m e n t a t i o n () ;

if (! a c c _ r s s _ h a l _ r e g i s t e r ( hal ) )
{
/* Handle error */
}

4.2.2 Create Config

A Config handle must be created before configuration of the sensor can be done.
The Config handle contains default settings at creation. They can be printed by calling the acc config log()
function.
For more information about configuration, see docs.acconeer.com.
acc_config_t * config = ac c_conf ig_cre ate () ;
if ( config == NULL )
{
/* Handle error */
}

/* Here the configuration can be changed */

a c c _ c o n f i g _ s t a r t _ p o i n t _ s e t ( config , 80) ;
a c c _ c o n f i g _ n u m _ p o i n t s _ s e t ( config , 160) ;

4.2.3 Create Processing

A Processing handle needs to be created in order to make sense of the data retrieved from the sensor. The processing
handle needs the Config handle to be created.
The Processing creation provides metadata that can be used by the application. Example of metadata is ‘frame data
length’, ‘sweep data length’, and ‘maximum sweep rate’.
a c c _ p r o c e s s i n g _ m e t a d a t a _ t proc_meta ;

acc_processing_t * processing = a c c _ p r o c e s s i n g _ c r e a t e ( config , & proc_meta ) ;

if ( processing == NULL )
{
/* Handle error */
}

4.2.4 Allocate Memory

The memory size needed by RSS depends on the configuration. The acc rss get buffer size() function will get the
needed memory size and the acc integration mem alloc() function will allocate the “buffer size” number of bytes for the
buffer.
uint32_t buffer_size ;
if (! a c c _ r s s _ g e t _ b u f f e r _ s i z e ( config , & buffer_size ) )
{
/* Handle error */
}

void * buffer = a c c _ i n t e g r a t i o n _ m e m _ a l l o c ( buffer_size ) ;

if ( buffer == NULL )
{

© 2024 by Acconeer AB - All rights reserved Page 7 of 22

 A121 Sparse IQ Service

/* Handle error */
}

4.2.5 Create Sensor

A Sensor handle must be created before communication with the sensor can be done. At creation, the ASIC ID is read
through SPI. Therefore the sensor must be powered on and enabled before the create function is called.
/* Power on sensor */
a c c _ h a l _ i n t e g r a t i o n _ s e n s o r _ s u p p l y _ o n ( SENSOR_ID ) ;

/* Enable sensor */
a c c _ h a l _ i n t e g r a t i o n _ s e n s o r _ e n a b l e ( SENSOR_ID ) ;

/* Create Sensor */
acc_sensor_t * sensor = ac c_sens or_cre ate ( SENSOR_ID ) ;
if ( sensor == NULL )
{
/* Handle error */
}

4.2.6 Calibrate Sensor

The sensor needs to be calibrated before radar data can be retrieved. The calibration has multiple steps, so it needs to be
done in a loop where the acc sensor calibrate() function is called interleaved with waiting for the sensor interrupt.
/* Calibrate Sensor */
bool status ;
bool cal_complete = false ;
acc_cal_result_t cal_result ;

do
{
status = a c c _ s e n s o r _ c a l i b r a t e ( sensor , & cal_complete , & cal_result , buffer
, buffer_size ) ;

if ( status && ! cal_complete )

{
status = a c c _ h a l _ i n t e g r a t i o n _ w a i t _ f o r _ s e n s o r _ i n t e r r u p t ( SENSOR_ID ,
SENS OR_TIM EOUT_ MS ) ;
}
} while ( status && ! cal_complete ) ;

if (! status )
{
/* Handle error */
}

/* Reset sensor after calibration by disabling it */

a c c _ h a l _ i n t e g r a t i o n _ s e n s o r _ d i s a b l e ( SENSOR_ID ) ;

4.2.7 Prepare Sensor

The configuration is loaded to the sensor by calling the acc sensor prepare() function. The sensor must be powered on
and enabled before the acc sensor prepare() function is called.
a c c _ h a l _ i n t e g r a t i o n _ s e n s o r _ e n a b l e ( SENSOR_ID ) ;

if (! acc _s en so r_ pr ep ar e ( sensor , config , & cal_result , buffer , buffer_size ) )

{
/* Handle error */
}

© 2024 by Acconeer AB - All rights reserved Page 8 of 22

 A121 Sparse IQ Service

4.3 Data Retrieval and Processing

4.3.1 Measure and Read Data from Sensor
The radar measurement is started when the acc sensor measure() function is called. The sensor will generate an interrupt
to the host by setting the interrupt pin high when the radar measurement is done. After the interrupt is received, the
acc sensor read() can be called to read raw data from the sensor over SPI.
if (! acc _s en so r_ me as ur e ( sensor ) )
{
/* Handle error */
}

if (! a c c _ h a l _ i n t e g r a t i o n _ w a i t _ f o r _ s e n s o r _ i n t e r r u p t ( SENSOR_ID ,
SEN SOR_TI MEOUT_ MS ) )
{
/* Handle error */
}

if (! acc_sensor_read ( sensor , buffer , buffer_size ) )

{
/* Handle error */
}

4.3.2 Data Processing

To make sense of the raw data, it must be processed with acc processing execute(). This converts the raw data to a Sparse
IQ frame and indications. The result is called a ‘processing result’.
a c c _ p r o c e s s i n g _ r e s u l t _ t proc_result ;

ac c _ p r o c e s s i n g _ e x e c u t e ( processing , buffer , & proc_result ) ;

uint16_t sweeps_per_frame = a c c _ c o n f i g _ s w e e p s _ p e r _ f r a m e _ g e t ( config ) ;

uint16_t sweep_length = proc_meta . swee p_data _lengt h ;

for ( uint16_t sweep_index = 0; sweep_index < sweeps_per_frame ; sweep_index

++)
{
for ( uint16_t distance_index = 0; distance_index < sweep_length ;
distance_index ++)
{
uint16_t index_in_frame = sweep_index * sweep_length +
distance_index ;

printf ( " % " PRIi16 " +% " PRIi16 " i \ n " , proc_result . frame [
index_in_frame ]. real , proc_result . frame [ index_in_frame ]. imag ) ;
}
}

The ‘proc meta’ above is retrieved from the function ‘acc processing create()’, described in the Create Processing
section.
As can be seen above, the IQ frame layout is in the order sweep and then distance. One could think of the layout as having
sweeps in the rows and distances in the columns. If more than one subsweep is used, the layout is in the order sweep,
subsweep, and distance. See below.
uint16_t sweeps_per_frame = a c c _ c o n f i g _ s w e e p s _ p e r _ f r a m e _ g e t ( config ) ;
uint8_t n um b e r_ o f _s u b sw e e ps = a c c _ c o n f i g _ n u m _ s u b s w e e p s _ g e t ( config ) ;
uint16_t sweep_length = proc_meta . swee p_data _lengt h ;

for ( uint16_t sweep_index = 0; sweep_index < sweeps_per_frame ; sweep_index

++)

© 2024 by Acconeer AB - All rights reserved Page 9 of 22

 A121 Sparse IQ Service

{
for ( uint8_t subsweep_index = 0; subsweep_index < n u mb e r _o f _ su b s we e p s ;
subsweep_index ++)
{
for ( uint16_t distance_index = 0; distance_index < proc_meta .
s u b s w e e p _ d a t a _ l e n g t h [ subsweep_index ]; distance_index ++)
{
uint16_t index_in_frame = sweep_index * sweep_length + proc_meta
. s u b s w e e p _ d a t a _ o f f s e t [ subsweep_index ] + distance_index ;

printf ( " % " PRIi16 " +% " PRIi16 " i \ n " , proc_result . frame [
index_in_frame ]. real , proc_result . frame [ index_in_frame ]. imag )
;
}
}
}

For more information on the indications that are received from a ‘processing result’, see section Indication
Handling.

4.4 Shutdown and Memory De-allocation

When the radar measurement is done, the handles can be destroyed and the resources can be returned to the system.
/* Disable Sensor */
a c c _ h a l _ i n t e g r a t i o n _ s e n s o r _ d i s a b l e ( SENSOR_ID ) ;

/* Power off Sensor */

a c c _ h a l _ i n t e g r a t i o n _ s e n s o r _ s u p p l y _ o f f ( SENSOR_ID ) ;

if ( sensor != NULL )
{
ac c_ se ns or _d es tr oy ( sensor ) ;
}

if ( processing != NULL )
{
a c c _ p r o c e s s i n g _ d e s t r o y ( processing ) ;
}

if ( config != NULL )
{
ac c_ co nf ig _d es tr oy ( config ) ;
}

if ( buffer != NULL )
{
a c c _ i n t e g r a t i o n _ m e m _ f r e e ( buffer ) ;
}

4.5 Configuration
The sensor can be configured with multiple different settings to allow for optimized usage for a specific use case. Each
configuration can be set using a function on the format acc config [setting] set(). See the Sparse IQ Configuration
Parameters section for a condensed list of the configurations that can be set.
Some configurations apply to the whole service, such as ‘num subsweeps’ and ‘inter frame idle state’. Some
configurations apply to the radar data, such as ‘start point’ and ‘hwaas’.
For more information about configuration, see docs.acconeer.com.
For a complete description of all configurations, see rss api.html provided in the SDK package.

© 2024 by Acconeer AB - All rights reserved Page 10 of 22

 A121 Sparse IQ Service

4.5.1 Number of Subsweeps

This configuration sets the number of subsweeps to use. See docs.acconeer.com for more information on the concept of
subsweeps.
The configurations that apply for the radar data can be set for each subsweep. The only difference is that subsweep is
added to the get/set function names.
How to set number of subsweeps.
void a c c _ c o n f i g _ n u m _ s u b s w e e p s _ s e t ( acc_config_t * config , uint8_t
num_subsweeps ) ;
uint8_t a c c _ c o n f i g _ n u m _ s u b s w e e p s _ g e t ( const acc_config_t * config ) ;

Example of how to set a subsweep config.

void a c c _ c o n f i g _ s u b s w e e p _ s t a r t _ p o i n t _ s e t ( acc_config_t * config , int32_t
start_point , uint8_t index ) ;
int32_t a c c _ c o n f i g _ s u b s w e e p _ s t a r t _ p o i n t _ g e t ( const acc_config_t * config ,
uint8_t index ) ;

4.5.2 Continuous Sweep Mode

In continuous sweep mode the timing will be identical over all sweeps, not just the sweeps in a frame. The continuous
sweep mode will only work when:
More information about continuous sweep mode can be found in the Advanced Sensor Control section.
void a c c _ c o n f i g _ c o n t i n u o u s _ s w e e p _ m o d e _ s e t ( acc_config_t * config , bool enabled
);
bool a c c _ c o n f i g _ c o n t i n u o u s _ s w e e p _ m o d e _ g e t ( const acc_config_t * config ) ;

4.5.3 Idle States

The sensor can enter three different idle states between frames and sweeps. The idle states are DEEP SLEEP, SLEEP
and READY. READY is the shallowest idle state and consumes the most power. DEEP SLEEP is the deepest state and
consumes the least power. The idle states affect how fast the sensor can measure. READY is the fastest and DEEP SLEEP
is the slowest. So setting an idle state is a trade-off between power consumption and measurement speed.
More information about idle states can be found in the Advanced Sensor Control section.
Inter Frame Idle State
void a c c _ c o n f i g _ i n t e r _ f r a m e _ i d l e _ s t a t e _ s e t ( acc_config_t * config ,
a c c _ c o n f i g _ i d l e _ s t a t e _ t idle_state ) ;
a c c _ c o n f i g _ i d l e _ s t a t e _ t a c c _ c o n f i g _ i n t e r _ f r a m e _ i d l e _ s t a t e _ g e t ( const
acc_config_t * config ) ;

Inter Sweep Idle State

void a c c _ c o n f i g _ i n t e r _ s w e e p _ i d l e _ s t a t e _ s e t ( acc_config_t * config ,
a c c _ c o n f i g _ i d l e _ s t a t e _ t idle_state ) ;
a c c _ c o n f i g _ i d l e _ s t a t e _ t a c c _ c o n f i g _ i n t e r _ s w e e p _ i d l e _ s t a t e _ g e t ( const
acc_config_t * config ) ;

4.5.4 Double Buffering

If enabled, the sensor can start a new measurement while the host is reading data from the sensor. It can be used to
decrease the idle time in between frames from the sensor.
More information about double buffering can be found in the Advanced Sensor Control section.
void a c c _ c o n f i g _ d o u b l e _ b u f f e r i n g _ s e t ( acc_config_t * config , bool enable ) ;
bool a c c _ c o n f i g _ d o u b l e _ b u f f e r i n g _ g e t ( const acc_config_t * config ) ;

© 2024 by Acconeer AB - All rights reserved Page 11 of 22

 A121 Sparse IQ Service

5 Sensor Calibration

The sensor needs to be calibrated before radar data can be retrieved. Without a successful calibration, the behavior of
the radar data is undefined. It can for example degrade the quality of the data or make the data completely useless. The
environment does not need to be known for the sensor calibration to work. This means that a (re)calibration can be done
at any time.
The sensor calibration is done in multiple steps. This means that during a calibration, multiple SPI transfers will be done.
An integration with a fast SPI will reduce the calibration time. As a reference, the calibration takes around 50 ms on the
XM125 module.
In each step, the calibration routine extracts data from the sensor and evaluates it. There are sanity checks of this sensor
data. A temporary external disturbance might affect the data which will trigger failures in the sanity checks. This should
only happen very rarely. If it happens, resetting the sensor (by setting enable low/high) and doing the calibration once
more should solve the issue. If the issue persists, there might be an issue with the sensor or integration.
The result of a calibration is stored as an uint32 t array in a result struct.
typedef struct
{
uint32_t data [ A C C _ C A L _ R E S U L T _ D A T A _ S I Z E / 4];
} acc_cal_result_t ;

This result is not portable between architectures. This means that the result must be used on the same platform as it was
produced.

5.1 Sensor Re-calibration

Sometimes, the sensor needs to be re-calibrated. This is indicated by the ‘calibration needed’ indication. It triggers if the
temperature difference between the last successful calibration and the current measurement exceeds 15 degrees Celsius.
For more information, see section Indication Handling.

5.2 Sensor Calibration Caching

To reduce time spent on calibration in an application, the calibration result can be cached. This means that a calibration
result is saved for a specific temperature. If the sensor needs to be re-calibrated, the saved calibration result can be used
instead of doing a new calibration. The saved calibration result should only be used if it was done within a temperature
range of at most +- 15 degrees Celsius from the current temperature.
The implementation of sensor calibration caching needs to be done in the application, i.e. it is not part of the RSS library
itself. To see an example of how it can be done, please look in ‘example service calibration caching.c’.
Sensor calibration caching is typically done to reduce power consumption in applications where temperature changes are
common.

6 Indication Handling

The result from a call to acc processing execute() includes both the radar data frame as well as indications. Below can be
seen how to fetch indications from the result.
a c c _ p r o c e s s i n g _ r e s u l t _ t proc_result ;

ac c _ p r o c e s s i n g _ e x e c u t e ( processing , buffer , & proc_result ) ;

if ( proc_result . data_saturated )
{
// Handle data saturated indication
}

if ( proc_result . frame_delayed )
{
// Handle frame delayed indication
}

if ( proc_result . cal ib ra ti on _n ee de d )

© 2024 by Acconeer AB - All rights reserved Page 12 of 22

 A121 Sparse IQ Service

{
// Handle calibration needed indication
}

Some of the indications are good-to-have metadata while some are crucial to handle for stable operation of the sensor.
The full list of indications and appropriate handling of them is described below.

6.1 Data Saturated

Indication of sensor data being saturated, which causes data corruption.
This happens when a reflection is so strong that the ADC in the sensor gets saturated.
Handle by lowering the receiver gain configuration.
void a c c _ c o n f i g _ r e c e i v e r _ g a i n _ s e t ( acc_config_t * config , uint8_t gain ) ;
uint8_t a c c _ c o n f i g _ r e c e i v e r _ g a i n _ g e t ( const acc_config_t * config ) ;

6.2 Frame Delayed

Indication that a radar data frame is delayed.
This happens if a frame rate in the sensor has been set and the host doesn’t read out the data within the frame period.
Handle by lowering the frame rate.
void a c c _ c o n f i g _ f r a m e _ r a t e _ s e t ( acc_config_t * config , float frame_rate ) ;
float a c c _ c o n f i g _ f r a m e _ r a t e _ g e t ( const acc_config_t * config ) ;

Alternative solutions could be to enable the ‘double buffering’ mode or to reduce the radar data being read and processed.
This can be done by reconfiguring the sensor. The configurations impacting the size of the radar data the most are
• num points
• step length
• sweeps per frame

6.3 Calibration Needed

Indication that the sensor calibration isn’t valid anymore and needs to be redone.
This happens when the temperature has changed compared to when the calibration was done.
Handle by resetting sensor (setting enable low/high) and redo the calibration.

6.4 Temperature
Indication of the sensor temperature, in degree Celsius, for the current measurement.
Note that the absolute accuracy is poor and the temperature must only be used for relative comparisons.
The temperature indication can be used for different types of comparisons or compensations. As an example, the Distance
Detector uses temperature compensation, see ‘A121 Distance Detector User Guide’ for more information.

7 Examples

Multiple different examples are provided in the SDK. They are divided into four categories, see table below.

7.1 Getting Started

These examples show basic concepts and can help during bring-up.
• example bring up - Shows how RSS assembly test can be used during bring-up of custom hardware
• example service - Shows basic usage of the Sparse IQ Service
• example detector distance - Shows basic usage of the Distance Detector API
• example detector presence - Shows basic usage of the Presence Detector API
• example control helper - Shows how the control helper API can be used

© 2024 by Acconeer AB - All rights reserved Page 13 of 22

 A121 Sparse IQ Service

7.2 Processing
These examples show different ways to process the Sparse IQ Data. The name of each example correspond to the
processing demonstrated.
• example processing amplitude
• example processing coherent mean
• example processing noncoherent mean
• example processing peak interpolation
• example processing subtract adaptive bg

7.3 Advanced Control

These examples show different, more advanced, ways to use and configure the API. They are useful depending on use
case. The name of each example correspond to what is being demonstrated.
• Sparse IQ Service configuration examples
• Sparse IQ Service control examples
• Distance Detector configuration examples
• Presence Detector configuration examples
• Low power examples - only present in the XM125 SDK

7.4 Troubleshooting
These examples can be used when issues arise.
example diagnostic test - Shows how to use the RSS diagnostic test to get sensor diagnostic information

8 Communication Issues

All persistent communication issues should be solved during bring-up.

However, unexpected external disturbance can temporarily negatively affect the communication between host and sensor.
If this happens, RSS returns failure from its various communication functions or waiting for sensor interrupt times out.
Basic communication functions are
• acc sensor create()
• acc sensor calibrate()
• acc sensor prepare()
• acc sensor measure()
• acc sensor read()

When a temporary communication failure occurs the following should be done

• Reset sensor (setting enable low/high)
• Destroy the Sensor handle
• Call the above communication functions again

9 Advanced Sensor Control

9.1 Sequential vs Parallel Control Flow

The control flow described in section ‘Data Retrieval and Processing’ is sequential. This means that the sensor
measurement, read-out of data, and data processing in host are all done one after the other. See image below.

© 2024 by Acconeer AB - All rights reserved Page 14 of 22

 A121 Sparse IQ Service

This is the simplest control flow which is easy to follow as nothing happens in parallel. All examples are using this kind
of control flow. An alternative control flow is to let the host do data processing at the same time as the sensor is doing a
measurement. See image below.

This control flow assumes that at least one measure and one wait for sensor interrupt has been done previously. Using the
parallel control flow increases the maximum possible update rate. It can also lower power consumption by handling the
data faster and thus letting the system go to sleep for a longer time.

9.2 Inter Frame and Inter Sweep Idle States

The sensor has different idle states to be able to either save power in and in between measurements or to be able to have
a high frame- and/or sweep-rate. The maximum frame-/sweep-rate will decrease when using Sleep and Deep Sleep idle
states due to transition time between the idle states.
The inter frame idle state is the state the sensor idles in between each frame. The inter sweep idle state is the state the
sensor idles in between each sweep.

© 2024 by Acconeer AB - All rights reserved Page 15 of 22

 A121 Sparse IQ Service

The inter frame idle state of the frame must be deeper or the same as the inter sweep idle state.
The graphs below show the power usage in between frames/sweeps depending on the inter frame and inter sweep idle
states.

9.2.1 Deep Sleep

Deep sleep is the deepest state where as much of the sensor hardware as possible is shut down, it is also the state that is
slowest to transition from.

9.2.2 Sleep
Sleep is a compromise between power save and transition time.

9.2.3 Ready
Ready is the shallowest state where most of the sensor hardware is kept on, it is also the state that is the fastest to transition
from.

9.3 Double Buffering

If enabled, the sensor buffer will be split in two halves reducing the maximum number of samples. A frame can be
read using the acc sensor read() function from one half of the sensor buffer while sampling is done into the other half.
Switching of buffers is done automatically by the acc sensor measure() function, so no extra functionality needs to be
implemented by the application.

© 2024 by Acconeer AB - All rights reserved Page 16 of 22

 A121 Sparse IQ Service

When using double buffering, measurements coinciding with SPI activity may have distorted phase. To mitigate this issue,
applying a median filter is recommended.
An example of how to do this median filtering can be found in acc algorithm.c provided in the Acconeer SW packages.
See example below of how to use it The function does not correct disturbances that may appear in the initial or final
sweeps.
/* *
* Brief example on how to use the double buffering median frame filter
*/

# include " acc_algorithm . h "

# define NUM_POINTS 60
# define SWEEPS_PER_FRAME 32

...

/* Create configuration */
config = acc _confi g_cre ate () ;
if ( config == NULL )
{
/* ERROR */
}

a c c _ c o n f i g _ n u m _ p o i n t s _ s e t ( config , NUM_POINTS ) ;
a c c _ c o n f i g _ s w e e p s _ p e r _ f r a m e _ s e t ( config , SWEEPS_PER_FRAME ) ;

...

int32_t work_buffer [ SWEEPS_PER_FRAME - 2];

/* Read sensor data */

if (! acc _s en so r_ me as ur e ( sensor ) )
{
/* ERROR */
}

if (! a c c _ h a l _ i n t e g r a t i o n _ w a i t _ f o r _ s e n s o r _ i n t e r r u p t ( SENSOR_ID ,
SEN SOR_TI MEOUT_ MS ) )
{
/* ERROR */
}

if (! acc_sensor_read ( sensor , buffer , buffer_size ) )

{
/* ERROR */
}

/* Process sensor data */

ac c _ p r o c e s s i n g _ e x e c u t e ( processing , buffer , & proc_result ) ;

/* Apply filter to frame */

a c c _ a l g o r i t h m _ d o u b l e _ b u f f e r i n g _ f r a m e _ f i l t e r ( proc_result . frame ,
SWEEPS_PER_FRAME , NUM_POINTS , work_buffer ) ;

The graph below show the timing and power for a double buffering configuration.

© 2024 by Acconeer AB - All rights reserved Page 17 of 22

 A121 Sparse IQ Service

9.4 Continuous Sweep Mode

With Continuous Sweep Mode (CSM), the sensor timing is set up to generate a continuous stream of sweeps even if more
than one sweep per frame is used. The interval between the last sweep in one frame to the first sweep in the next frame
becomes equal to the interval between sweeps within a frame (given by the sweep rate).
If only one sweep per frame is used, CSM has no use since a continuous stream of sweeps is already given (if a fixed
frame rate is used).
The main use for CSM is to allow reading out data at a slower rate than the sweep rate, while maintaining that sweep rate
continuously.
Note that in most cases, double buffering must be enabled to allow high rates without delays.
Constraints:
• frame rate must be 0 (unlimited)
• sweep rate must be > 0
• The inter frame idle state of the frame must be equal to inter sweep idle state
The graph below show the timing and power for a CSM configuration.

9.5 High Speed Mode

High speed mode means that the sensor is configured in a way where it can optimize its measurements to obtain as high
sweep rate as possible. In order for the sensor to operate in high speed mode, the following configuration constraints
apply:
• continuous sweep mode must be disabled
• inter sweep idle state must be Ready
• num subsweeps must be 1
• profile must be 3, 4 or 5
The graph below show the timing and power for a high speed mode configuration.

© 2024 by Acconeer AB - All rights reserved Page 18 of 22

 A121 Sparse IQ Service

10 Memory

10.1 Flash
The example application compiled from example service.c on the XM125 module requires around 70 kB.

10.2 RAM
The RAM can be divided into three categories, static RAM, heap, and stack. Below is a table for approximate RAM for
an application compiled from example service.c.

RAM Size (kB)

Static 1
Heap 4
Stack 5
Total 10

Note that heap is very dependent on the configuration. But the numbers in the table above is a pretty good estimate for
many configurations.
The configurations that have the largest impact on memory are ‘sweeps per frame’, ‘num points’, and
‘step length’.

11 A121 vs A111

The Service APIs for A121 and A111 are quite similar. They are both designed to control the sensor and retrieve data
from it.
The main updates to control for A121 compared to A111 are:
• The pin handling, like ENABLE, is completely handled by the application
• The majority of the memory is allocated in the application allowing for memory reuse between Services
• The Service handle is divided into a Sensor handle and a Processing handle
• The Sensor handle can be used to separately do a calibration
• The Sensor handle can be used to (re)configure the sensor faster using a ‘prepare’ function
• The get next function is replaced by a function sequence of ‘measure’ -> ‘wait for interrupt’ -> ‘read’ -> ‘process’

The main updates to radar data for A121 compared to A111 are:
• There is only one Service, the Sparse IQ Service, providing complex IQ data
• The radar data can be divided into subsweeps

The differences generally allow for:

© 2024 by Acconeer AB - All rights reserved Page 19 of 22

 A121 Sparse IQ Service

• More advanced multi-sensor scheduling

• Detailed sweep configuration
• More power optimized applications
• More memory optimized applications

Below is an image showing the differences in control flow.

For more differences, see docs.acconeer.com.

© 2024 by Acconeer AB - All rights reserved Page 20 of 22

 A121 Sparse IQ Service

12 Sparse IQ Configuration Parameters

Table 3: Sparse IQ Configuration Parameters

Name Type Default Value Min Max

start point int32 t 80
num points uint16 t 160
step length uint16 t 1 1
hwaas uint16 t 8 1 511
receiver gain uint8 t 16 0 23
enable tx bool true n/a n/a
phase enhancement bool false n/a n/a
enable loopback bool false n/a n/a
prf enum prf 15 6 mhz prf 5 2 mhz prf 19 5 mhz
profile enum profile 3 profile 1 profile 5
sweep rate float 0.0
frame rate float 0.0
sweeps per frame uint16 t 1
continuous sweep mode bool false n/a n/a
double buffering bool false n/a n/a
num subsweeps uint8 t 1 1 4
inter frame idle state enum deep sleep deep sleep ready
inter sweep idle state enum ready deep sleep ready

© 2024 by Acconeer AB - All rights reserved Page 21 of 22

 A121 Sparse IQ Service

13 Disclaimer

The information herein is believed to be correct as of the date issued. Acconeer AB (“Acconeer”) will not be responsible
for damages of any nature resulting from the use or reliance upon the information contained herein. Acconeer makes no
warranties, expressed or implied, of merchantability or fitness for a particular purpose or course of performance or usage
of trade. Therefore, it is the user’s responsibility to thoroughly test the product in their particular application to
determine its performance, efficacy and safety. Users should obtain the latest relevant information before placing orders.

Unless Acconeer has explicitly designated an individual Acconeer product as meeting the requirement of a particular
industry standard, Acconeer is not responsible for any failure to meet such industry standard requirements.

Unless explicitly stated herein this document Acconeer has not performed any regulatory conformity test. It is the user’s
responsibility to assure that necessary regulatory conditions are met and approvals have been obtained when using the
product. Regardless of whether the product has passed any conformity test, this document does not constitute any
regulatory approval of the user’s product or application using Acconeer’s product.

Nothing contained herein is to be considered as permission or a recommendation to infringe any patent or any other
intellectual property right. No license, express or implied, to any intellectual property right is granted by Acconeer
herein.

Acconeer reserves the right to at any time correct, change, amend, enhance, modify, and improve this document and/or
Acconeer products without notice.

This document supersedes and replaces all information supplied prior to the publication hereof.

© 2024 by Acconeer AB - All rights reserved Page 22 of 22