Audio Fallback

The audio fallback Module allows applications to dynamically reduce the audio packet size to increase output power settings in response to a degrading link. Without fallback, if the link degrades beyond a certain point, audio packets will be lost. With fallback enabled, we can avoid dropping packets by dynamically enabling processing stages which reduce the audio quality to help with link reliability. The reliability can be improved by reducing the audio packet size, which allows for higher transmit power settings to be used. Therefore, the effective range of the system is increased, at the cost of a lower quality audio stream. Smaller packets also reduce airtime and that could allow an application to increase the amount of CCA retries, resulting in more packets getting through.

Configuring the API

• An application can have up to eight fallback modes, which can switch between them according to the link’s quality.

• A fallback mode can be added using the sac_fallback_add_mode function. The mode’s index will be returned to the application for future reference.

  • A fallback mode is configured using the sac_fallback_mode_cfg_t structure, which contains parameters to define the thresholds for triggering and recovering from a fallback mode.

  typedef struct sac_fallback_mode_cfg {
      /*! Fallback algorithm sampling frequency in Hertz. */
      uint16_t sampling_frequency_hz;
      /*! ***  RECOVERY THRESHOLDS *** */
      /*! Default average link margin threshold to allow recovery. */
      uint8_t link_margin_threshold;
      /*! Link margin threshold hysteresis. */
      uint8_t link_margin_threshold_hysteresis;
      /*! Amount of time in seconds the link margin must be higher than the threshold to allow recovery. */
      uint32_t link_margin_good_time_sec;
      /*! Average CCA fail count threshold in percent of the maximum number of CCA tries possible on this connection to
       *  allow recovery to previous mode.
       */
      uint8_t cca_good_fail_count_threshold_perc;
      /*! Amount of time in seconds the CCA fail count must be lower than the threshold to allow recovery. */
      uint32_t cca_good_time_sec;
  
      /*! *** TRIGGER THRESHOLDS *** */
      /*! Average CCA fail count threshold in percent of the maximum number of CCA tries possible on this connection to
       *  trigger the next mode.
       */
      uint8_t cca_bad_fail_count_threshold_perc;
      /*! Amount of time in seconds the CCA fail count must be higher than the threshold to trigger the next mode. */
      float cca_bad_time_sec;
      /*! Audio transmitting pipeline consumer buffer load above which the next fallback mode is triggered. Value should
       *  be multiplied by 10. (ex: 1.3 is 13).
       */
      uint32_t consumer_buffer_load_threshold_tenths;
      /*! Number of samples to expect in a packet in this mode. This should be set to the expected number of samples of
       *  that specific fallback mode, if sample rate converter processing stage is added to that fallback mode.
       *
       *  It can also be used to track the expected sample count of each mode when using the accumulator processing stage.
       */
      uint32_t sample_count;
  } sac_fallback_mode_cfg_t;
  

  • The sac_fallback_mode_get_defaults function can be used to initialize the fallback mode configuration structure with default values.

• A processing stage can be assigned to a fallback mode using the sac_fallback_mode_assign_process function using the mode’s index and the processing stage handle.

• The system should be pessimistic at start up to optimize the chances of successful communication when the system is brought up in a poor link environment. As such, fallback state is initialized to the last mode on startup.

• If an application desires to force a certain fallback mode state (e.g. The user requires high reliability through an app.), it can do so using the sac_fallback_set_manual_mode function to disable the automatic mode switching. The fallback mode can be selected using the sac_fallback_set_current_mode function.

• When the sampling rate converter processing stage is used in a fallback mode, the sample count of the fallback mode must be set to the expected number of samples of that specific fallback mode. It can also be used to track expected sample count for each mode when using the accumulator processing stage.

Power setting configuration

The RF power transmitted by a SPARK UWB radio is determined by three settings: Pulse Count, Pulse Width and Pulse Gain (which is really an attenuation control). The table below shows how the power settings and CCA Try Count are influenced by payload size for the Audio Bidirectional Example Application:

SR1100

Table 60: Example Alternate Link Settings Used by Audio Bidirectional Fallback Mode

Parameter	Mode 0 (48 kHz 24-bit)	Mode 1 (48 kHz ADPCM)
Payload size	122 (Audio payload + SAC header)	28 (Audio payload + SAC header + ADPCM header)
Pulse Count	1	1
Pulse Width	1	6
Pulse Gain	1	0
CCA Try Count	7	12

A payload size of 122 requires the power settings to be configured as (1, 1, 1) with an airtime that allows for 7 CCA retries.

A reduced payload size of 28 allows the power settings to be increased to (1, 6, 0), allowing up to 12 CCA retries due to shorter airtime. The link benefits from an extended range as a result of the higher power configuration.

SR1000

Table 61: Example Alternate Link Settings Used by Audio Bidirectional Fallback Mode

Parameter	Mode 0 (48 kHz 24-bit)	Mode 1 (48 kHz ADPCM)
Payload size	122 (Audio payload + SAC header)	28 (Audio payload + SAC header + ADPCM header)
Pulse Count	1	2
Pulse Width	5	4
Pulse Gain	2	0
CCA Try Count	3	5

A payload size of 122 requires the power settings to be configured as (1, 5, 2) with an airtime that allows for 3 CCA retries.

A reduced payload size of 28 allows the power settings to be increased to (2, 4, 0), allowing up to 5 CCA retries due to shorter airtime. The link benefits from an extended range as a result of the higher power configuration.

In the Audio Bidirectional Example Application, the Wireless Core automatically switches between the two configuration modes based on the payload size requested by the Audio Core. In mode 0, the default connection settings are used, whereas in mode 1, the TX power settings and CCA Try Count are taken from the Wireless Core fallback configuration. See Fallback Mode for more details.

Fallback Trigger

The next fallback mode is triggered when the transmitter detects a rise in either the TX queue load or the CCA retry count. To avoid reacting to short-lived fluctuations, both the TX queue load and the CCA retry count are smoothed using rolling averages.

Under normal conditions, the TX queue load remains at 0 or 1. When it increases to 2 or higher, it indicates that packets are accumulating due to retransmissions caused by a weakening link. The last three sampled TX queue loads are stored in a circular array and averaged. The values are scaled by a factor of 10 to allow the rolling average to represent fractional values, providing finer averaging precision.

For the CCA retry count, a rolling average is also computed over recent samples. A fallback mode is triggered if this average exceeds a configurable threshold for a sustained period, indicating that retransmissions are occurring persistently and the link quality is deteriorating.

Thus, the link quality at the transmitter is determined as follows:

• A rolling average of the last sampled TX queue loads is calculated for every audio packet that is processed.

• A rolling average of the last CCA retry counts is calculated for every audio packet that is processed.

• If either rolling average exceeds its predetermined thresholds, the next fallback mode is triggered.

The TX queue threshold is configured using the consumer_buffer_load_threshold_tenths field. A value of 13 (1.3) works well for unidirectional links where the timeslots are contiguous. In bidirectional links where there is a time gap between transmissions, a value of 23 (2.3) could be used.

The CCA retry count percentage threshold and the continuous duration for which it must be exceeded are configured using the cca_bad_fail_count_threshold_perc and cca_bad_time_sec parameters respectively.

These values can be fine-tuned on a per-application basis to match the desired link reliability and responsiveness or the defaults settings can be used using the sac_fallback_mode_get_defaults function.

Fallback recovery

Recovery to a previous fallback mode is based on two metrics: the receiver’s Link Margin and the transmitter’s CCA retry count. As in the fallback trigger process, both metrics are smoothed using rolling averages to avoid reacting to transient variations.

Link margin values and CCA retry counts are obtained from the Wireless Core using the swc_connection_get_fallback_info() function, which returns the following:

SR1100

typedef struct swc_fallback_info {
    /*! Link margin value. */
    uint8_t link_margin;
    /*! CCA fail count value. */
    uint32_t cca_fail_count;
    /*! Number of times all CCA attempts failed. */
    uint32_t cca_tx_fail_count;
    /*! Total number of tx dropped packets. */
    uint32_t tx_pkt_dropped;
    /*! Total number of CCA events. */
    uint32_t cca_event_count;
} swc_fallback_info_t;

SR1000

typedef struct swc_fallback_info {
    /*! Link margin value. */
    uint8_t link_margin;
    /*! CCA fail count value. */
    uint32_t cca_fail_count;
    /*! Number of times all CCA attempts failed. */
    uint32_t cca_tx_fail_count;
    /*! Total number of tx dropped packets. */
    uint32_t tx_pkt_dropped;
    /*! Total number of CCA events. */
    uint32_t cca_event_count;
} swc_fallback_info_t;

The receiver’s link margin value must be reported to the transmitter either automatically through the auto-reply mechanism or via a dedicated connection. Although stored as a 16-bit variable, it can be sent using a single unsigned byte if saturated at 255. The link margin threshold used to recover to a previous mode is much lower than this maximum.

The averaged link margin must remain above a predefined threshold for a continuous period before it is considered good. The threshold and duration can be adjusted using link_margin_threshold and link_margin_good_time_sec parameters.

Similarly, the averaged CCA retry count must be below a configurable threshold for a continuous period to be considered good. The period can be configured using the cca_good_time_sec parameter. The threshold is a percentage of the maximum number of retries configured using the cca_good_fail_count_threshold_perc parameter.

Recovery to a previous fallback mode occurs only when both criteria, link margin and CCA retry count, have met their respective thresholds for the configured duration, indicating good wireless conditions.

The multi-mode fallback mechanism supports several fallback levels, each with its own trigger and recovery thresholds. As link quality degrades, modes are entered sequentially, and recovery to a previous mode occurs once both link margin and CCA metrics indicate stable and improved conditions.

These values can be fine-tuned on a per-application basis to match the desired link reliability and responsiveness or the defaults settings can be used using the sac_fallback_mode_get_defaults function.

Fast Recovery Mechanism

Fast recovery is a boot-time optimization that allows the fallback state machine to quickly return to a higher performance mode immediately after TX queue buffering completes.

Once buffering finishes and the TX queue is nearly empty, the system enters a short observation phase during which link quality metrics are evaluated using fixed thresholds. Specifically, both the link margin and CCA recovery counters must report a sufficient number of consecutive valid metrics. If these conditions are met, the state machine immediately recovers to the previous mode, bypassing the slower, recovery criteria.

Fast recovery is only enabled right after buffering completion and is automatically disabled once normal operation resumes.

Audio Fallback Processing Stage

The fallback processing stage is required on both the transmitter and the receiver. The transmitter will monitor the link quality and switch between fallback modes as needed. It will then update the audio header to indicate the fallback mode of the packet. The receiver will update its fallback state based on the audio packets’ audio header it receives from the transmitter.

The fallback processing stage should be the first processing stage in both the Transmitter and Receiver audio pipelines to make sure that the fallback state is updated before any other processing stage runs.

Audio Processing Gate Function

Processing stage sac_fallback_gate_is_process_active gate function is used in both the Transmitter and Receiver devices to verify if a process is assigned to the current fallback mode.

Example: A 48 kHz 24 bits application using audio packing to 16 bits and audio ADPCM compression as a fallback mechanisms.

In this example, the application will have three fallback modes:

• 48 kHz 24-bit (mode 0)

• 48 kHz 16-bit (mode 1)

• 48 kHz ADPCM (mode 2)

In the Transmitter, the first processing stage will be the fallback stage, followed by four additional audio processing stages using the sac_fallback_gate_is_process_active gate.

1. Fallback stage: Checks the fallback mode and updates the audio header.

2. Audio Compression Stage: Discards the output in fallback mode 0 or 1 to keep the compressor up to date. Keeping the compression running continuously in the background ensures seamless activation when it is needed.

3. Audio Packing Stage: Performs audio packing from 32-bit aligned audio to 24-bit when fallback mode 0 is active.

4. Audio Packing Stage: Performs audio packing from 32-bit aligned audio to 16-bit when fallback mode 1 is active.

5. Audio Compression Stage: Performs audio compression from 32-bit aligned audio to ADPCM when fallback mode 2 is active.

In the Receiver, the first processing stage will be the fallback stage, followed by three additional audio processing stages using the sac_fallback_gate_is_process_active gate.

1. Fallback stage: Checks the fallback mode from the audio header and updates the module state.

2. Audio :term:`Unpacking` Stage: Performs audio unpacking from 24-bit aligned audio to 32-bit when fallback mode 0 is active.

3. Audio Unpacking Stage: Performs audio unpacking from 16-bit aligned audio to 32-bit when fallback mode 1 is active.

4. Audio Decompression Stage: Performs the decompression from ADPCM audio to 32-bit aligned audio when fallback mode 2 is active.