BluetoothSignalStrengthFilter
BluetoothSignalStrengthFilter
BluetoothSignalStrengthFilter
BluetoothSignalStrengthFilter
Class
Definition
Groups parameters used to configure received signal strength indicator (RSSI)-based filtering.
public : sealed class BluetoothSignalStrengthFilter : IBluetoothSignalStrengthFilterpublic sealed class BluetoothSignalStrengthFilter : IBluetoothSignalStrengthFilterPublic NotInheritable Class BluetoothSignalStrengthFilter Implements IBluetoothSignalStrengthFilter// You can use this class in JavaScript.
- Attributes
| Device family |
Windows 10 (introduced v10.0.10240.0 - for Xbox, see UWP features that aren't yet supported on Xbox)
|
| API contract |
Windows.Foundation.UniversalApiContract (introduced v1)
|
| Capabilities |
bluetooth
|
Remarks
The BluetoothSignalStrengthFilter class only accepts a limited range for its properties. However, depending on how this class is used by an app, additional restrictions may apply. For example, the valid range for RSSI values differs between Bluetooth LE and Bluetooth BR/EDR devices.
The valid range for these properties are as follows:
- InRangeThresholdInDBm - The minimum threshold for an RSSI event to be considered in range. The valid range is -128 to 127.
- OutOfRangeThresholdInDBm - The minimum threshold for an RSSI event to be considered out of range. The valid range is -128 to 127.
- OutOfRangeTimeout - Timeout for an RSSI event to be considered out of range. The valid range is equal or greater than 1 second.
- SamplingInterval - The interval at which RSSI events are sampled. The valid range is equal or greater than 0. Any sampling interval greater or equal to 25.5 seconds will disable sampling entirely. In that special case, the filtering is trigger-based. There are two possible states for filtering RSSI values for any device:
- In range.
- Out of range. Any RSSI events are propagated if they are considered in range. This includes events with RSSI values lower or equal than OutOfRangeThresholdInDBm as long as OutOfRangeTimeout has not expired.
This class has additional limitations on its properties when used by the BluetoothLEAdvertisementWatcher class. An exception will be thrown when the BluetoothLEAdvertisementWatcher is started with parameters outside of the valid range for BluetoothLEAdvertisementWatcher.
In general, there are three main use cases for this API:
| InRangeThresholdInDBm | OutOfRangeThresholdInDBm | OutOfRangeTimeout | SamplingInterval | Behavior |
|---|---|---|---|---|
| Any | <= InRangeThresholdInDBm | >= 1 | 0 | Will receive all RSSI events as they arrive as long as they are considered "in range". The events are considered "out of range" if OutOfRangeTimeout expires without any events or without any events with RSSI values greater than OutOfRangeThresholdInDBm. No additional events are generated when OutOfRangeTimeout expires. |
| Any | <= InRangeThresholdInDBm | >= 1 | (0, 25.5) | Will receive RSSI events on a regular interval defined by SamplingInterval as long as they are considered “in range”. The RSSI value will be an average of the values of events received within a SamplingInterval. If no events are received within SamplingInterval, no event will be propagated. If OutOfRangeTimeout expires without any events or without any events with RSSI values greater than OutOfRangeThresholdInDBm, the events are considered “out of range” and an event with the last RSSI value received will be generated. If the last RSSI value was above OutOfRangeThresholdInDBm, it is set to -127 dBm. |
| Any | <= InRangeThresholdInDBm | >= 1 | >=25.5 (disabled) | Will receive a RSSI event when the RSSI events are transitioning to "in range" from "out of range". If OutOfRangeTimeout expires without any events or without any events with RSSI values greater than OutOfRangeThresholdInDBm, the events are considered “out of range” and an event with the last RSSI value received will be generated. If the last RSSI value was above OutOfRangeThresholdInDBm, it is set to OutOfRangeThresholdInDBm. |
Constructors
BluetoothSignalStrengthFilter() BluetoothSignalStrengthFilter() BluetoothSignalStrengthFilter() BluetoothSignalStrengthFilter()
Create a new BluetoothSignalStrengthFilter object.
public : BluetoothSignalStrengthFilter()public BluetoothSignalStrengthFilter()Public Sub New()// You can use this method in JavaScript.
| Device family |
Windows 10 (introduced v10.0.10240.0 - for Xbox, see UWP features that aren't yet supported on Xbox)
|
| API contract |
Windows.Foundation.UniversalApiContract (introduced v1)
|
| Capabilities |
bluetooth
|
Properties
InRangeThresholdInDBm InRangeThresholdInDBm InRangeThresholdInDBm InRangeThresholdInDBm
The minimum received signal strength indicator (RSSI) value in dBm on which RSSI events will be propagated or considered in range if the previous events were considered out of range.
public : IReference<short> InRangeThresholdInDBm { get; set; }public Nullable<short> InRangeThresholdInDBm { get; set; }Public ReadWrite Property InRangeThresholdInDBm As Nullable<short>// You can use this property in JavaScript.
- Value
- IReference<short> Nullable<short> Nullable<short> Nullable<short>
The minimum RSSI value in dBm on which RSSI events will be propagated or considered in range.
| Device family |
Windows 10 (introduced v10.0.10240.0 - for Xbox, see UWP features that aren't yet supported on Xbox)
|
| API contract |
Windows.Foundation.UniversalApiContract (introduced v1)
|
| Capabilities |
bluetooth
|
Remarks
The valid range for this property is between -128 and 127.
This condition still applies if no events were received since the beginning of the filtering process. The initial assumption for any device is always out of range. An event is considered in range if its RSSI value is greater than or equal to InRangeThresholdInDBm or if the previous event was considered in range and the OutOfRangeTimeout has not expired.
- See Also
OutOfRangeThresholdInDBm OutOfRangeThresholdInDBm OutOfRangeThresholdInDBm OutOfRangeThresholdInDBm
The minimum received signal strength indicator (RSSI) value in dBm on which RSSI events will be considered out of range.
public : IReference<short> OutOfRangeThresholdInDBm { get; set; }public Nullable<short> OutOfRangeThresholdInDBm { get; set; }Public ReadWrite Property OutOfRangeThresholdInDBm As Nullable<short>// You can use this property in JavaScript.
- Value
- IReference<short> Nullable<short> Nullable<short> Nullable<short>
The minimum RSSI value in dBm on which RSSI events will be considered out of range.
| Device family |
Windows 10 (introduced v10.0.10240.0 - for Xbox, see UWP features that aren't yet supported on Xbox)
|
| API contract |
Windows.Foundation.UniversalApiContract (introduced v1)
|
| Capabilities |
bluetooth
|
Remarks
The valid range for this property is between -128 and 127.
RSSI events are considered out of range after their RSSI values are kept lower than or equal to OutOfRangeThresholdInDBm within OutOfRangeTimeout. RSSI events are also considered out of range if no events are received within OutOfRangeTimeout.
- See Also
OutOfRangeTimeout OutOfRangeTimeout OutOfRangeTimeout OutOfRangeTimeout
The timeout for a received signal strength indicator (RSSI) event to be considered out of range.
public : IReference<TimeSpan> OutOfRangeTimeout { get; set; }public Nullable<TimeSpan> OutOfRangeTimeout { get; set; }Public ReadWrite Property OutOfRangeTimeout As Nullable<TimeSpan>// You can use this property in JavaScript.
- Value
- IReference<TimeSpan> Nullable<TimeSpan> Nullable<TimeSpan> Nullable<TimeSpan>
The timeout for an RSSI event to be considered out of range.
| Device family |
Windows 10 (introduced v10.0.10240.0 - for Xbox, see UWP features that aren't yet supported on Xbox)
|
| API contract |
Windows.Foundation.UniversalApiContract (introduced v1)
|
| Capabilities |
bluetooth
|
Remarks
The valid range for this property is equal or greater than 1 second.
If the RSSI events are currently considered in range, this is the timeout period during which if the received RSSI events have RSSI values less than or equal to OutOfRangeThresholdInDBm or no RSSI events are received, further RSSI events will be considered out of range. This timer is reset if received RSSI values are greater than OutOfRangeThresholdInDBm. If the events are currently out of range, this property has no effect.
When applied to LE advertisements, an advertisement with the minimum RSSI value (-127) will be generated to indicate that the advertisement went out of range.
- See Also
SamplingInterval SamplingInterval SamplingInterval SamplingInterval
The interval at which received signal strength indicator (RSSI) events are sampled.
public : IReference<TimeSpan> SamplingInterval { get; set; }public Nullable<TimeSpan> SamplingInterval { get; set; }Public ReadWrite Property SamplingInterval As Nullable<TimeSpan>// You can use this property in JavaScript.
- Value
- IReference<TimeSpan> Nullable<TimeSpan> Nullable<TimeSpan> Nullable<TimeSpan>
The interval at which RSSI events are sampled.
| Device family |
Windows 10 (introduced v10.0.10240.0 - for Xbox, see UWP features that aren't yet supported on Xbox)
|
| API contract |
Windows.Foundation.UniversalApiContract (introduced v1)
|
| Capabilities |
bluetooth
|
Remarks
The valid range for this property is equal or greater than zero.
If the SamplingInterval is zero, every received RSSI event that satisfies the conditions configured through the other BluetoothSignalStrengthFilter properties will be propagated. If the sampling interval is greater than or equal to a maximum limit value (currently 25.5 seconds), sampling will be disabled and RSSI events will only be propagated on a triggered basis when they transition between in range and out of range. Otherwise, an aggregated RSSI value (average in most cases) of the RSSI events received within SamplingInterval will be propagated. If no RSSI events have been received within SamplingInterval, no RSSI events are propagated.