Envelope

The Envelope service provides data related to the received energy at different distances from the radar sensor. One envelope measurement is performed by transmitting a sequence radar pulses and measuring the energy content in the returning echoes for a set of time delays from pulse transmission.

The envelope data is a set of \(N_D\) real valued samples represented as \(x[d]\), where \(d\) is the delay sample index and each value sample has an amplitude \(x[d] = A_d\) representing the received energy from a specific distance, \(d\).

To stabilize the signal and increase the SNR, the sweeps in the Envelope Service can be time filtered. This can be configured by setting the running average factor between 0 and 1, where high number indicates more filtering. The filtering is a standard exponential smoothening filter with default setting of 0.7. Note, for very low update rates below a few hertz, the signal from an object moving fast, or suddenly disappearing, remain in the sweep.

The filtering of data in the Envelope Service applies a low-pass filter in the range dimension. This leads to some filter edge effects in the first few centimeters of the sweep. For very short sweeps, approx. 3 cm for Profile 1 and approx 6 cm for Profile 2-5, these edge effects affects the magnitude of the whole sweep. The Power Bins, with only a few bins, is recommended for short sweeps.

The Envelope service can be configured with different pulse length profiles, see Profiles.

examples/a111/services/envelope.py contains example code on how this service can be used.

For further reading on the envelope service we refer to the Envelope documentation on the Acconeer developer page.

Configuration parameters

class acconeer.exptool.a111.EnvelopeServiceConfig

running_average_factor

The time smoothing factor for Envelope sweeps. With the running average factor larger than zero, consecutive sweeps are averaged using an exponential window function. A running average factor of 0.0 corresponds to no time filtering of sweeps and close to 1.0 results in more filtering.

Envelope sweep number \(s\) returned by RSS, \(E_s(r)\), is calculated from the measured sweep, \(e_s(r)\), according to

\[E_s(r) = \text{RAF} \cdot E_{s-1}(r) + (1 - \text{RAF}) \cdot e_{s}(r),\]

where RAF is the running average factor.

Type: float

Default value: 0.7

class MUR(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

class PowerSaveMode(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

asynchronous_measurement

Enabling asynchronous measurements will result in a faster update rate but introduces a risk of interference between sensors.

Type: bool

Default value: True

downsampling_factor

The range downsampling by an integer factor. A factor of 1 means no downsampling, thus sampling with the smallest possible depth interval. A factor 2 samples every other point, and so on. In Envelope and IQ, the finest interval is ~0.5 mm. In Power Bins, it is the same but then further downsampled in post-processing. In sparse, it is ~6 cm.

The downsampling is performed by skipping measurements in the sensor, and therefore gives lower memory usage, lower power consumption, and lower duty cycle.

In sparse, setting a too large factor might result in gaps in the data where moving objects “disappear” between sampling points.

In Envelope, IQ, and Power Bins, the factor must be 1, 2, or 4. In sparse, it must be at least 1. Setting a factor greater than 1 might affect the range end point and for IQ and Envelope, also the first point.

Type: int

Default value: 1

gain

The receiver gain used in the sensor. If the gain is too low, objects may not be visible, or it may result in poor signal quality due to quantization errors. If the gain is too high, strong reflections may result in saturated data. We recommend not setting the gain higher than necessary due to signal quality reasons.

Must be between 0 and 1 inclusive, where 1 is the highest possible gain.

Note

When Sensor normalization is active, the change in the data due to changing gain is removed after normalization. Therefore, the data might seen unaffected by changes in the gain, except very high (receiver saturation) or very low (quantization error) gain.

Sensor normalization is not available for the Sparse service, but is enabled by default for the other services - Envelope, IQ, and Power Bins.

Type: float

Default value: 0.5

hw_accelerated_average_samples

Number of samples taken to obtain a single point in the data. These are averaged directly in the sensor hardware - no extra computations are done in the MCU.

The time needed to measure a sweep is roughly proportional to the HWAAS. Hence, if there’s a need to obtain a higher sweep rate, HWAAS could be decreased. Note that HWAAS does not affect the amount of data transmitted from the sensor over SPI.

Must be at least 1 and not greater than 63.

Type: int

Default value: 10

maximize_signal_attenuation

When measuring in the direct leakage (around 0m), this setting can be enabled to minimize saturation in the receiver. We do not recommend using this setting under normal operation.

Type: bool

Default value: False

mur

Sets the maximum unambiguous range (MUR), which in turn sets the maximum measurable distance (MMD).

The MMD is the maximum value for the range end, i.e., the range start + length. The MMD is smaller than the MUR due to hardware limitations.

The MUR is the maximum distance at which an object can be located to guarantee that its reflection corresponds to the most recent transmitted pulse. Objects farther away than the MUR may fold into the measured range. For example, with a MUR of 10 m, an object at 12 m could become visible at 2 m.

A higher setting gives a larger MUR/MMD, but comes at a cost of increasing the measurement time for a sweep. The measurement time is approximately proportional to the MUR.

This setting changes the pulse repetition frequency (PRF) of the radar system. The relation between PRF and MUR is

\[\text{MUR} = c / (2 * \text{PRF})\]

where c is the speed of light.

Setting	MUR	MMD	PRF
6	11.5 m	7.0 m	13.0 MHz
9	17.3 m	12.7 m	8.7 MHz

This is an experimental feature.

Default value: MUR.MUR_6

noise_level_normalization

With the SW version 2 release, a sensor signal normalization functionality is activated by default for the Power Bins, Envelope, and IQ Service. This results in a more constant signal for different temperatures and sensors. The radar sweeps are normalized to have similar amplitude independent of sensor gain and hardware averaging, resulting in only minor visible effect in the sweeps when adjusting these parameters.

We recommend this setting especially for applications, where absolute radar amplitudes are important, such as when comparing to a previously recorded signal or to a fixed threshold.

More technically, the functionality is implemented to collect data when starting the service, but not transmitting pulses. This data is then used to determine the current sensitivity of receiving part of the radar by estimating the power level of the noise, which then is used to normalize the collected sweeps. In the most low-power systems, where a service is created to collect just a single short sweep before turning off, the sensor normalization can add a non-negligible part to the power consumption.

Please note, that due to the nature of Sparse data, the Sparse service does not support noise level normalization. Instead, normalization during processing is recommended, such as done in the Presence detector.

Type: bool

Default value: True

power_save_mode

The power save mode configuration sets what state the sensor waits in between measurements in an active service. There are five power save modes. The modes differentiate in current dissipation and response latency, where the most current consuming mode Active gives fastest response and the least current consuming mode Off gives the slowest response. The absolute response time and also maximum update rate is determined by several factors besides the power save mode configuration.

In addition, the host capabilities in terms of SPI communication speed and processing speed also impact on the absolute response time. The power consumption of the system depends on the actual configuration of the application and it is recommended to test both maximum update rate and power consumption when the configuration is decided.

Power save mode	Current consumption	Response time
Off	Lowest	Longest
Hibernate	…	…
Sleep	…	…
Ready	…	…
Active	Highest	Shortest

Note

Hibernation has limited hardware support. It is not supported by the Raspberry Pi EVK:s and XM112.

Default value: PowerSaveMode.ACTIVE

profile

The main configuration of all the services are the profiles, numbered 1 to 5. The difference between the profiles is the length of the radar pulse and the way the incoming pulse is sampled. Profiles with low numbers use short pulses while the higher profiles use longer pulses.

Profile 1 is recommended for:

• measuring strong reflectors, to avoid saturation of the received signal

• close range operation (<20 cm), due to the reduced direct leakage

Profile 2 and 3 are recommended for:

• operation at intermediate distances, (20 cm to 1 m)

• where a balance between SNR and depth resolution is acceptable

Profile 4 and 5 are recommended for:

• for Sparse service only

• operation at large distances (>1 m)

• motion or presence detection, where an optimal SNR ratio is preferred over a high resolution distance measurement

The previous profile Maximize Depth Resolution and Maximize SNR are now profile 1 and 2. The previous Direct Leakage Profile is obtained by the use of the Maximize Signal Attenuation parameter.

Default value: Profile.PROFILE_2

range_interval

The measured depth range. The start and end values will be rounded to the closest measurement point available.

The the sweep range is limited to 7.0 m for the default “maximum unambiguous range” setting. To change this limitation, increase “maximum unambiguous range”.

Type: float

Unit: m

Default value: [0.18, 0.78]

repetition_mode

The RSS supports two different repetition modes. They determine how and when data acquisition occurs. They are:

• On demand / host driven: The sensor produces data when requested by the application. Hence, the application is responsible for timing the data acquisition. This is the default mode, and may be used with all power save modes.

• Streaming / sensor driven: The sensor produces data at a fixed rate, given by a configurable accurate hardware timer. This mode is recommended if exact timing between updates is required.

The Exploration Tool is capable of setting the update rate also in on demand (host driven) mode. Thus, the difference between the modes becomes subtle. This is why on demand and streaming are called host driven and sensor driven respectively in Exploration Tool.

Default value: RepetitionMode.HOST_DRIVEN

sensor

The sensor(s) to be configured.

Default value: [1]

tx_disable

Disable the radio transmitter. If used to measure noise, we recommended also switching off noise level normalization (if applicable).

Type: bool

Default value: False

update_rate

The rate \(f_f\) at which the sensor sends frames to the host MCU.

Attention

Setting the update rate too high might result in missed data frames.

In sparse, the maximum possible update rate depends on the sweeps per frame \(N_s\) and sweep rate \(f_s\):

\[\frac{1}{f_f} > N_s \cdot \frac{1}{f_s} + \text{overhead*}\]

* The overhead largely depends on data frame size and data transfer speeds.

Type: float

Unit: Hz

Default value: None