# AVSS Settings Reference

## Overview

The AVSS (ANURA Vibration Sensing Service) settings structure defines all configurable parameters for ANURA vibration sensors. This document provides a complete reference for each setting, organized by functional category.

## Settings Index

The following table lists all settings ordered by numeric id in the AVSS protocol with links to detailed descriptions.

```{list-table} AVSS Settings Structure
:header-rows: 1
:widths: 10 40 50

* - Index
  - Field Name
  - Description
* - 0
  - [`base_sample_rate_hz`](#base-sample-rate)
  - Base sample rate in Hz
* - 1
  - [`base_axis_enable`](#base-axis-enable)
  - Axis enable bitmask
* - 2
  - [`snippet_interval_ms`](#snippet-interval)
  - Interval between snippets in milliseconds
* - 3
  - [`snippet_length`](#snippet-length)
  - Number of samples per snippet
* - 4
  - [`health_interval_ms`](#health-interval)
  - Health data reporting interval in milliseconds
* - 5
  - [`snippet_mode`](#snippet-mode)
  - Snippet capture mode
* - 6
  - [`motion_threshold_rms_g`](#motion-threshold)
  - Motion detection threshold in g (RMS)
* - 7
  - [`motion_standby_delay_ms`](#motion-standby-delay)
  - Delay before entering standby in milliseconds
* - 8
  - [`wom_sample_rate_hz`](#wom-sample-rate)
  - Wake-on-motion sample rate in Hz
* - 9
  - [`wom_threshold_g`](#wom-threshold)
  - Wake-on-motion threshold in g
* - 10
  - [`capture_mode`](#capture-mode)
  - Data capture mode
* - 11
  - [`capture_buffer_length`](#capture-buffer-length)
  - Capture buffer length in samples
* - 12
  - [`events_motion_start_enable`](#events-motion-start-enable)
  - Enable motion start event detection
* - 13
  - [`events_motion_start_capture`](#events-motion-start-capture)
  - Enable capture on motion start
* - 14
  - [`events_motion_start_capture_duration_ms`](#events-motion-start-capture-duration)
  - Motion start capture duration in milliseconds
* - 15
  - [`aggregates_mode`](#aggregates-mode)
  - Aggregated metrics computation mode
* - 16
  - [`aggregates_interval_ms`](#aggregates-interval)
  - Aggregates computation interval in milliseconds
* - 17
  - [`aggregates_sample_rate_hz`](#aggregates-sample-rate)
  - Sample rate for aggregates computation in Hz
* - 18
  - [`aggregates_hpf_mode`](#aggregates-hpf-mode)
  - High-pass filter mode for aggregates
* - 19
  - [`aggregates_hpf_cutoff`](#aggregates-hpf-cutoff)
  - High-pass filter cutoff frequency in Hz
* - 20
  - [`aggregates_fft_mode`](#aggregates-fft-mode)
  - FFT computation mode
* - 21
  - [`aggregates_fft_length`](#aggregates-fft-length)
  - FFT length in samples
* - 22
  - [`aggregates_param_enable_0_31`](#aggregates-param-enable-0-31)
  - Bitmask enabling parameters 0-31
* - 23
  - [`aggregates_param_enable_32_63`](#aggregates-param-enable-32-63)
  - Bitmask enabling parameters 32-63
```

## Setting Categories

(base-sampling-configuration)=
## Base Sampling Configuration

This group controls the fundamental sampling behavior of the vibration sensor.

(base-sample-rate)=
### base_sample_rate_hz

**Type:** `uint32_t`
**Index:** 0
**Unit:** Hz

The base sample rate for vibration measurements. This determines the number of vibration samples per second. All vibration data-consuming modules in the sensor (captures, snippets) are downstream of this processing stage, and are thus affected by this setting.

**Valid Values:**
- 512 Hz
- 1024 Hz
- 2048 Hz
- 4096 Hz
- 8192 Hz
- 16384 Hz

**Considerations:**
- Higher sample rates capture higher frequency content, but increase data bandwidth usage. You may need to adjust the [snippet interval](#snippet-interval) and/or [snippet length](#snippet-length) to avoid exceeding the available data bandwidth, which causes data loss.
- The maximum frequency that is theoretically possible to capture with a samplerate of `f_s` is `f_s / 2` (Nyquist frequency). In practice, we recommend using a sample rate that is at least three to four times the maximum frequency of interest.

(base-axis-enable)=
### base_axis_enable

**Type:** `uint32_t` (bitmask)
**Index:** 1

Bitmask to enable or disable individual accelerometer axes (X, Y, Z). Disabling unused axes reduces data volume and therefore also power consumption.

**Bit Mapping:**
- Bit 0 (least significant bit): X-axis enable
- Bit 1: Y-axis enable
- Bit 2: Z-axis enable

**Example:** `0x07` (binary: 111) enables all three axes.

(snippet-interval)=
### snippet_interval_ms

**Type:** `uint32_t`
**Index:** 2
**Unit:** milliseconds

Time interval between raw vibration data snippets. This controls how frequently the sensor captures and transmits raw acceleration data.

**Typical Values:**
- 60000 ms (1 minute) - Standard monitoring
- 300000 ms (5 minutes) - Low-frequency monitoring
- 10000 ms (10 seconds) - High-frequency monitoring

**Considerations:**
- Shorter intervals increase data bandwidth usage. You may need to adjust the [base sample rate](#base-sample-rate) and/or [snippet length](#snippet-length) to avoid exceeding the available data bandwidth, which causes data loss.

(snippet-length)=
### snippet_length

**Type:** `uint32_t`
**Index:** 3
**Unit:** samples

Number of samples in each raw vibration data snippet.

**Choosing length in seconds:**
```
snippet_length = base_sample_rate_hz × <duration in seconds>
```

**Examples:**
- At 1024 Hz for 3 seconds: `1024 × 3 = 3072 samples`
- At 8192 Hz for 5 seconds: `8192 × 5 = 40960 samples`

**Considerations:**
- Longer snippets increase data bandwidth usage. You may need to adjust the [base sample rate](#base-sample-rate) and/or [snippet interval](#snippet-interval) to avoid exceeding the available data bandwidth, which causes data loss.
- Must fit within available memory buffer

---

(health-monitoring)=
## Health Monitoring

(health-interval)=
### health_interval_ms

**Type:** `uint32_t`
**Index:** 4
**Unit:** milliseconds

Time interval for health monitoring data updates. Health data includes temperature, RSSI, battery voltage, and harvesting voltage.

**Typical Values:**
- 60000 ms (1 minute) - Standard monitoring
- 300000 ms (5 minutes) - Low-frequency monitoring
- 10000 ms (10 seconds) - Useful for diagnostics

**Considerations:**
- More frequent health updates increase power consumption slightly

---

## Snippet Mode

(snippet-mode)=
### snippet_mode

**Type:** `uint32_t` (enumeration)
**Index:** 5

Operating mode for snippet generation. Snippets are vibration waveforms captured with a specified interval, or continuously.

**Valid Values:**
- 0: Disabled
- 1: Interval
- 2: Continuous

**Usage:**

In _interval_ mode, snippets are captured at a specified interval (cf. `snippet_interval_ms`).

In _continuous_ mode, snippets are captured continuously. They can be joined into a continuous waveform, i.e. the first sample of snippet _n+1_ is captured _1/f\_s_ after the last sample of snippet _n_.

---

(motion-detection-power-management)=
## Motion Detection & Power Management

This group controls the sensor's motion detection and automatic transition to Stand-by Mode.

(motion-threshold)=
### motion_threshold_rms_g

**Type:** `float`
**Index:** 6
**Unit:** g (RMS)

RMS acceleration threshold above which the sensor actively measures, processes and transmits vibration data. When vibration falls below this threshold for the duration specified by `motion_standby_delay_ms`, the sensor enters Stand-by Mode.

**Default Value:** 0.05 g

**Considerations:**
- Set based on the minimum vibration level when machine is operating
- Too low: May inadvertently start due to ambient vibrations, even when the machine is stopped
- Too high: May enter Stand-by while machine is still running

(motion-standby-delay)=
### motion_standby_delay_ms

**Type:** `uint32_t`
**Index:** 7
**Unit:** milliseconds

Duration of continuous no-motion condition (vibration below `motion_threshold_rms_g`) required before the sensor enters Stand-by Mode.

**Typical Values:**
- 5000 ms (5 seconds) - Quick response
- 30000 ms (30 seconds) - Standard
- 60000 ms (1 minute) - Conservative

**Considerations:**
- Prevents the sensor from entering standby mode during brief periods of lower vibration amplitude
- Shorter delays conserve battery as the sensor exits sampling mode faster

(wom-sample-rate)=
### wom_sample_rate_hz

**Type:** `uint32_t`
**Index:** 8
**Unit:** Hz

**Valid Values:**
- 500 Hz
- 200 Hz
- 100 Hz
- 50 Hz
- 25 Hz
- 13 Hz

Accelerometer sample rate used in Stand-by Mode for wake-on-motion condition evaluation.

**Considerations:**
- Lower rates reduce power consumption in Stand-by Mode

(wom-threshold)=
### wom_threshold_g

**Type:** `float`
**Index:** 9
**Unit:** g

**Valid Values:**
0 to 1

Acceleration (at `wom_sample_rate_hz`) required to wake the sensor from Stand-by Mode back to Sampling Mode. Measured from the acceleration that was prevalent when the sensor entered Stand-by Mode.

---

(capture-system)=
## Capture System

This group controls _capture_ features and buffer management. The capture system produces vibration waveforms, like snippets, but are triggered by specific events or conditions instead of a time-based schedule.

(capture-mode)=
### capture_mode

**Type:** `uint32_t` (enumeration)
**Index:** 10

**Valid Values:**
- 0: Disabled
- 1: Enabled

**Usage:** Must be enabled to use capture features.

(capture-buffer-length)=
### capture_buffer_length

**Type:** `uint32_t`
**Index:** 11
**Unit:** samples

Length of each capture report. A continuous waveform may be sent as multiple reports, for example if `capture_buffer_length` is shorter than `events_motion_start_capture_duration_ms` times `base_sample_rate_hz`.

---

(event-detection)=
## Event Detection

This group enables detection of specific vibration events. The events can be configured to trigger functions in the sensor, such as capturing a waveform.

(events-motion-start-enable)=
### events_motion_start_enable

**Type:** `bool`
**Index:** 12

Enable or disable detection of the _motion start_ event. When enabled, the sensor generates an event when motion begins (transition from Stand-by to Sampling Mode).

**Valid Values:**
- `true` - Enabled
- `false` - Disabled

(events-motion-start-capture)=
### events_motion_start_capture

**Type:** `bool`
**Index:** 13

Enable or disable vibration waveform capture when motion start event occurs. Requires `events_motion_start_enable` and `capture_mode` to be enabled.

**Valid Values:**
- `true` - Enabled
- `false` - Disabled

**Usage:** Useful for capturing machine behaviour during the transient run-up phase.

(events-motion-start-capture-duration)=
### events_motion_start_capture_duration_ms

**Type:** `uint32_t`
**Index:** 14
**Unit:** milliseconds

Duration of vibration waveform capture triggered by motion start event.

**Considerations:**
- Longer durations increase data volume
- May include pre-trigger data from capture buffer

---

(aggregated-metrics)=
## Aggregated Metrics

This group controls the computation and transmission of aggregated vibration metrics.

(aggregates-mode)=
### aggregates_mode

**Type:** `uint32_t` (enumeration)
**Index:** 15

Operating mode for aggregated metrics computation. Determines if aggregated metrics are computed and transmitted.

**Valid Values:**
- 0: Disabled
- 1: Enabled

(aggregates-interval)=
### aggregates_interval_ms

**Type:** `uint32_t`
**Index:** 16
**Unit:** milliseconds

Time interval for aggregated metrics calculation and transmission.

**Valid Values:**
Minimum 1000 (will be set to 1000 if a lower value is provided)

(aggregates-sample-rate)=
### aggregates_sample_rate_hz

**Type:** `uint32_t`
**Index:** 17
**Unit:** Hz

Sample rate used for aggregated metrics computation.

**Valid Values:**

Must be lower than or equal to `base_sample_rate_hz`.

- 512 Hz
_(currently only one value available)_

(aggregates-hpf-mode)=
### aggregates_hpf_mode

**Type:** `uint32_t` (enumeration)
**Index:** 18

Mode for high-pass filter applied to data before computing aggregated metrics.

**Valid Values:**
- 1: First-order IIR
_(currently only one value available)_

(aggregates-hpf-cutoff)=
### aggregates_hpf_cutoff

**Type:** `float`
**Index:** 19
**Unit:** Dimensionless

Decides the cutoff for the high-pass filter used in aggregates processing. Higher number => more attentuation at low frequencies.

**Valid Values:**
From 0.01 to 0.1

(aggregates-fft-mode)=
### aggregates_fft_mode

**Type:** `uint32_t` (enumeration)
**Index:** 20

FFT (Fast Fourier Transform) computation mode for frequency domain analysis in aggregated metrics. When enabled, the sensor uses the FFT method to calculate the frequency of the highest vibration amplitude in the signal.

**Valid Values:**
- 0: Disabled
- 1: Enabled

(aggregates-fft-length)=
### aggregates_fft_length

**Type:** `uint32_t`
**Index:** 21
**Unit:** samples

Number of samples used for FFT computation in aggregated metrics. Requires `aggregates_fft_mode` to be enabled.

**Valid Values:**
- 256 samples
- 512 samples

**Frequency Resolution:**
```
frequency resolution in Hz = aggregates_sample_rate_hz / aggregates_fft_length
```

(aggregates-param-enable-0-31)=
### aggregates_param_enable_0_31

**Type:** `uint32_t` (bitmask)
**Index:** 22

Bitmask to enable individual aggregated parameters 0 through 31. Each bit enables/disables a specific computed metric.

**Parameter Mapping:**
- Bit 0: Acceleration RMS X
- Bit 1: Acceleration RMS Y
- Bit 2: Acceleration RMS Z
- Bit 3: Acceleration Peak X
- Bit 4: Acceleration Peak Y
- Bit 5: Acceleration Peak Z
- Bit 6: Velocity RMS X
- Bit 7: Velocity RMS Y
- Bit 8: Velocity RMS Z
- Bit 9: Velocity Peak X
- Bit 10: Velocity Peak Y
- Bit 11: Velocity Peak Z
- Bit 12: Displacement Peak-to-Peak X
- Bit 13: Displacement Peak-to-Peak Y
- Bit 14: Displacement Peak-to-Peak Z
- Bit 15: Stroke A XY
- Bit 16: Stroke A YZ
- Bit 17: Stroke A XZ
- Bit 18: Stroke B XY
- Bit 19: Stroke B YZ
- Bit 20: Stroke B XZ
- Bit 21: FFT Peak Frequency X
- Bit 22: FFT Peak Frequency Y
- Bit 23: FFT Peak Frequency Z
- Bit 24: Acceleration Crest Factor X
- Bit 25: Acceleration Crest Factor Y
- Bit 26: Acceleration Crest Factor Z
- Bits 27-31: Reserved

**Usage:** Enable only needed parameters to reduce computation load and transmission overhead.

(aggregates-param-enable-32-63)=
### aggregates_param_enable_32_63

**Type:** `uint32_t` (bitmask)
**Index:** 23

Bitmask to enable individual aggregated parameters 32 through 63. Extends the parameter enable space for future metrics.

**Parameter Mapping:** All bits reserved for future use.