Skip to content

Commit 85981ee

Browse files
mKeRixmKeRix
committed
feat(bluetooth): add configuration options for noise filter
Should allow users to fine-tune the noise reduction mechanism for their use case. Refs #775
1 parent 6325937 commit 85981ee

9 files changed

+90
-57
lines changed

‎docs/integrations/bluetooth-classic.md

+14-12
Original file line numberDiff line numberDiff line change
@@ -77,18 +77,20 @@ Try to pair your Apple Watch to a Bluetooth device such as headphones/speakers f
7777

7878
## Settings
7979

80-
| Name | Type | Default | Description |
81-
| ------------------ | -------------------------------------------- | ------- | ------------------------------------------------------------ |
82-
| `addresses` | Array | | List of Bluetooth MAC addresses that should be tracked. You can usually find them in the device settings. |
83-
| `minRssi` | Number _or_ [detailed config](#minimum-rssi) | | Limits the RSSI at which a device is still reported if configured. Remember, the RSSI is the inverse of the sensor attribute distance, so for a cutoff at 10 you would configure -10. |
84-
| `rssiFactor` | Number | `1` | Multiplier for the measured RSSI values. Allows you to fine-tune measurements if you use different Bluetooth adapters across your cluster. |
85-
| `hciDeviceId` | Number | `0` | ID of the Bluetooth device to use for the inquiries, e.g. `0` to use `hci0`. |
86-
| `interval` | Number | `10` | The interval at which the Bluetooth devices are queried in seconds. |
87-
| `scanTimeLimit` | Number | `6` | The maximum time allowed for completing a device query in seconds. This should be set lower than the interval. |
88-
| `timeoutCycles` | Number | `2` | The number of completed query cycles after which collected measurements are considered obsolete. The timeout in seconds is calculated as `max(addresses, clusterDevices) * interval * timeoutCycles`. |
89-
| `preserveState` | Boolean | `false` | Whether the last recorded distance should be preserved when the inquiries switch is turned off or not. |
90-
| `inquireFromStart` | Boolean | `true` | Whether the [Inquiries Switch](#inquiries-switch) is turned on when room-assistant is started or not. |
91-
| `entityOverrides` | [Entity Overrides](#entity-overrides) | | Allows you to override some properties of the created entities. |
80+
| Name | Type | Default | Description |
81+
| ------------------------ | -------------------------------------------- | ------- | ------------------------------------------------------------ |
82+
| `addresses` | Array | | List of Bluetooth MAC addresses that should be tracked. You can usually find them in the device settings. |
83+
| `minRssi` | Number _or_ [detailed config](#minimum-rssi) | | Limits the RSSI at which a device is still reported if configured. Remember, the RSSI is the inverse of the sensor attribute distance, so for a cutoff at 10 you would configure -10. |
84+
| `rssiFactor` | Number | `1` | Multiplier for the measured RSSI values. Allows you to fine-tune measurements if you use different Bluetooth adapters across your cluster. |
85+
| `hciDeviceId` | Number | `0` | ID of the Bluetooth device to use for the inquiries, e.g. `0` to use `hci0`. |
86+
| `interval` | Number | `10` | The interval at which the Bluetooth devices are queried in seconds. |
87+
| `scanTimeLimit` | Number | `6` | The maximum time allowed for completing a device query in seconds. This should be set lower than the interval. |
88+
| `timeoutCycles` | Number | `2` | The number of completed query cycles after which collected measurements are considered obsolete. The timeout in seconds is calculated as `max(addresses, clusterDevices) * interval * timeoutCycles`. |
89+
| `preserveState` | Boolean | `false` | Whether the last recorded distance should be preserved when the inquiries switch is turned off or not. |
90+
| `inquireFromStart` | Boolean | `true` | Whether the [Inquiries Switch](#inquiries-switch) is turned on when room-assistant is started or not. |
91+
| `entityOverrides` | [Entity Overrides](#entity-overrides) | | Allows you to override some properties of the created entities. |
92+
| `kalmanProcessNoise` | Number | `1.4` | Covariance of the process noise, used for measurement noise reduction via a [Kalman filter](https://en.wikipedia.org/wiki/Kalman_filter). |
93+
| `kalmanMeasurementNoise` | Number | `1` | Covariance of the measurement noise, used for measurement noise reduction via a [Kalman filter](https://en.wikipedia.org/wiki/Kalman_filter). |
9294

9395
### Minimum RSSI
9496

‎docs/integrations/bluetooth-low-energy.md

+2
Original file line numberDiff line numberDiff line change
@@ -92,6 +92,8 @@ bluetoothLowEnergy:
9292
| `instanceBeaconMajor` | Number | `1` | The major of the advertised iBeacon. |
9393
| `instanceBeaconMinor` | Number | Random | The minor of the advertised iBeacon. |
9494
| `minDiscoveryLogRssi` | Number | -999 | Only log newly discovered beacons if raw RSSI values are greater than this (useful to reduce log spam if on a busy street). |
95+
| `kalmanProcessNoise` | Number | `0.0008` | Covariance of the process noise, used for measurement noise reduction via a [Kalman filter](https://en.wikipedia.org/wiki/Kalman_filter). |
96+
| `kalmanMeasurementNoise` | Number | `4` | Covariance of the measurement noise, used for measurement noise reduction via a [Kalman filter](https://en.wikipedia.org/wiki/Kalman_filter). |
9597

9698
### Tag Overrides
9799

‎src/config/config.service.spec.fail.yml

+4
Original file line numberDiff line numberDiff line change
@@ -107,6 +107,8 @@ bluetoothLowEnergy:
107107
ebef1234567890-55555-444:
108108
name: iBeacon 2
109109
timeout: 120 # FORMAT ERROR: Missplaced Property
110+
kalmanProcessNoise: 1.1
111+
kalmanMeasurementNoise: 2.2
110112
bluetoothClassic:
111113
hciDeviceId: 1
112114
interval: 20
@@ -128,6 +130,8 @@ bluetoothClassic:
128130
entityOverrides:
129131
ebef1234567890-55555-333:
130132
id: 333 # TYPE ERROR: String Required
133+
kalmanProcessNoise: 1
134+
kalmanMeasurementNoise: 2
131135
omronD6t:
132136
busNumber: 3
133137
address: 0x1d

‎src/config/config.service.spec.pass.yml

+4
Original file line numberDiff line numberDiff line change
@@ -101,6 +101,8 @@ bluetoothLowEnergy:
101101
batteryMask: 0xFFFFFFFF
102102
ebef1234567890-55555-444:
103103
name: iBeacon 2
104+
kalmanProcessNoise: 1.1
105+
kalmanMeasurementNoise: 2.2
104106
bluetoothClassic:
105107
hciDeviceId: 1
106108
interval: 20
@@ -119,6 +121,8 @@ bluetoothClassic:
119121
entityOverrides:
120122
ebef1234567890-55555-333:
121123
id: "My Id"
124+
kalmanProcessNoise: 1
125+
kalmanMeasurementNoise: 2
122126
omronD6t:
123127
busNumber: 3
124128
address: 0x1d

‎src/integrations/bluetooth-classic/bluetooth-classic.config.ts

+16-12
Original file line numberDiff line numberDiff line change
@@ -7,33 +7,37 @@ const MAC_DEFAULT_REGEXP = new RegExp(MAC_REXEP_STRING + '|default');
77
const MAC_ERROR = '{#label} does not match the required MAC address format';
88

99
class BluetoothClassicEntityOverride {
10-
@(jf.string().optional())
10+
@jf.string().optional()
1111
id?: string;
12-
@(jf.string().optional())
12+
@jf.string().optional()
1313
name?: string;
1414
}
1515

1616
export class BluetoothClassicConfig {
17-
@(jf.array({ elementClass: String }).custom(validateMACAddress).required())
17+
@jf.array({ elementClass: String }).custom(validateMACAddress).required()
1818
addresses: string[] = [];
19-
@(jf.any().custom(validateMinRSSI).optional())
19+
@jf.any().custom(validateMinRSSI).optional()
2020
minRssi?: number | { [macAddress: string]: number };
21-
@(jf.number().required())
21+
@jf.number().required()
2222
rssiFactor = 1;
23-
@(jf.number().integer().min(0).required())
23+
@jf.number().integer().min(0).required()
2424
hciDeviceId = 0;
25-
@(jf.number().min(1).required())
25+
@jf.number().min(1).required()
2626
interval = 10;
27-
@(jf.number().min(1).required())
27+
@jf.number().min(1).required()
2828
scanTimeLimit = 6;
29-
@(jf.number().min(1).required())
29+
@jf.number().min(1).required()
3030
timeoutCycles = 2;
31-
@(jf.boolean().required())
31+
@jf.boolean().required()
3232
preserveState = false;
33-
@(jf.boolean().required())
33+
@jf.boolean().required()
3434
inquireFromStart = true;
35-
@(jf.object().custom(validateEntityOverrides).required())
35+
@jf.object().custom(validateEntityOverrides).required()
3636
entityOverrides: { [entityId: string]: BluetoothClassicEntityOverride } = {};
37+
@jf.number().positive().required()
38+
kalmanProcessNoise = 1.4;
39+
@jf.number().positive().required()
40+
kalmanMeasurementNoise = 1;
3741
}
3842

3943
function validateMACAddress(options: {

‎src/integrations/bluetooth-classic/bluetooth-classic.service.ts

+5-1
Original file line numberDiff line numberDiff line change
@@ -37,7 +37,11 @@ const execPromise = util.promisify(exec);
3737

3838
@Injectable()
3939
export class BluetoothClassicService
40-
extends KalmanFilterable(Object, 1.4, 1)
40+
extends KalmanFilterable(
41+
Object,
42+
'bluetoothClassic.kalmanProcessNoise',
43+
'bluetoothClassic.kalmanMeasurementNoise'
44+
)
4145
implements OnModuleInit, OnApplicationBootstrap
4246
{
4347
private readonly config: BluetoothClassicConfig;

‎src/integrations/bluetooth-low-energy/bluetooth-low-energy.config.ts

+31-27
Original file line numberDiff line numberDiff line change
@@ -3,63 +3,67 @@ import * as Joi from 'joi';
33
import * as jf from 'joiful';
44

55
class TagOverride {
6-
@(jf.string().optional())
6+
@jf.string().optional()
77
id?: string;
8-
@(jf.string().optional())
8+
@jf.string().optional()
99
name?: string;
10-
@(jf.number().negative().optional())
10+
@jf.number().negative().optional()
1111
measuredPower?: number;
12-
@(jf.number().integer().max(0xffffffff).optional())
12+
@jf.number().integer().max(0xffffffff).optional()
1313
batteryMask?: number;
1414
}
1515

1616
export class BluetoothLowEnergyConfig {
17-
@(jf.number().integer().min(0).required())
17+
@jf.number().integer().min(0).required()
1818
hciDeviceId = 0;
19-
@(jf.array({ elementClass: String }).required())
19+
@jf.array({ elementClass: String }).required()
2020
whitelist: string[] = [];
21-
@(jf.boolean().required())
21+
@jf.boolean().required()
2222
whitelistRegex = false;
23-
@(jf.array({ elementClass: String }).required())
23+
@jf.array({ elementClass: String }).required()
2424
allowlist: string[] = [];
25-
@(jf.boolean().required())
25+
@jf.boolean().required()
2626
allowlistRegex = false;
27-
@(jf.array({ elementClass: String }).required())
27+
@jf.array({ elementClass: String }).required()
2828
blacklist: string[] = [];
29-
@(jf.boolean().required())
29+
@jf.boolean().required()
3030
blacklistRegex = false;
31-
@(jf.array({ elementClass: String }).required())
31+
@jf.array({ elementClass: String }).required()
3232
denylist: string[] = [];
33-
@(jf.boolean().required())
33+
@jf.boolean().required()
3434
denylistRegex = false;
35-
@(jf.boolean().required())
35+
@jf.boolean().required()
3636
processIBeacon = true;
37-
@(jf.boolean().required())
37+
@jf.boolean().required()
3838
onlyIBeacon = false;
39-
@(jf.number().integer().min(0).max(0xffff).required())
39+
@jf.number().integer().min(0).max(0xffff).required()
4040
majorMask = 0xffff;
41-
@(jf.number().integer().min(0).max(0xffff).required())
41+
@jf.number().integer().min(0).max(0xffff).required()
4242
minorMask = 0xffff;
43-
@(jf.number().integer().max(0xffffffff).required())
43+
@jf.number().integer().max(0xffffffff).required()
4444
batteryMask = 0x00000000;
45-
@(jf.boolean().required())
45+
@jf.boolean().required()
4646
instanceBeaconEnabled = true;
47-
@(jf.number().integer().min(0).max(65535).required())
47+
@jf.number().integer().min(0).max(65535).required()
4848
instanceBeaconMajor = 1;
49-
@(jf.number().integer().min(0).max(65535).required())
49+
@jf.number().integer().min(0).max(65535).required()
5050
instanceBeaconMinor = randomInt(0, 65535);
51-
@(jf.object().custom(validateTagOverrides).required())
51+
@jf.object().custom(validateTagOverrides).required()
5252
tagOverrides: { [entityId: string]: TagOverride } = {};
53-
@(jf.number().min(0).required())
53+
@jf.number().min(0).required()
5454
timeout = 60;
55-
@(jf.number().min(0).required())
55+
@jf.number().min(0).required()
5656
updateFrequency = 0;
57-
@(jf.number().required())
57+
@jf.number().required()
5858
rssiFactor = 1;
59-
@(jf.number().positive().optional())
59+
@jf.number().positive().optional()
6060
maxDistance?: number;
61-
@(jf.number().max(0).required())
61+
@jf.number().max(0).required()
6262
minDiscoveryLogRssi = -999;
63+
@jf.number().positive().required()
64+
kalmanProcessNoise = 0.008;
65+
@jf.number().positive().required()
66+
kalmanMeasurementNoise = 4;
6367
}
6468

6569
function validateTagOverrides(options: {

‎src/integrations/bluetooth-low-energy/bluetooth-low-energy.service.ts

+8-2
Original file line numberDiff line numberDiff line change
@@ -36,7 +36,11 @@ const COMPANION_APP_CHARACTERISTIC_UUID = '21c46f33e813440786012ad281030052';
3636

3737
@Injectable()
3838
export class BluetoothLowEnergyService
39-
extends KalmanFilterable(Object, 0.008, 4)
39+
extends KalmanFilterable(
40+
Object,
41+
'bluetoothLowEnergy.kalmanProcessNoise',
42+
'bluetoothLowEnergy.kalmanMeasurementNoise'
43+
)
4044
implements OnModuleInit, OnApplicationBootstrap
4145
{
4246
private readonly config: BluetoothLowEnergyConfig;
@@ -487,7 +491,9 @@ export class BluetoothLowEnergyService
487491
let appId: string;
488492

489493
if (!this.bluetoothService.acquireQueryMutex()) {
490-
this.logger.debug(`Canceled discovery for tag ${tag.id} as BLE adapter is already in use`);
494+
this.logger.debug(
495+
`Canceled discovery for tag ${tag.id} as BLE adapter is already in use`
496+
);
491497
return tag;
492498
}
493499

‎src/util/filters.ts

+6-3
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,14 @@
11
import KalmanFilter from 'kalmanjs';
2+
import c from 'config';
23

34
// eslint-disable-next-line @typescript-eslint/ban-types
45
type Constructable = new (...args: any[]) => object;
56

67
// eslint-disable-next-line @typescript-eslint/explicit-function-return-type,@typescript-eslint/explicit-module-boundary-types
78
export function KalmanFilterable<BC extends Constructable>(
89
Base: BC,
9-
R = 1,
10-
Q = 1
10+
ProcessNoiseProperty: string,
11+
MeasurementNoiseProperty: string
1112
) {
1213
return class extends Base {
1314
kalmanFilterMap: Map<string, KalmanFilter> = new Map<
@@ -27,7 +28,9 @@ export function KalmanFilterable<BC extends Constructable>(
2728
if (this.kalmanFilterMap.has(id)) {
2829
return this.kalmanFilterMap.get(id).filter(value);
2930
} else {
30-
const kalman = new KalmanFilter({ R, Q });
31+
const r = c.get<number>(ProcessNoiseProperty);
32+
const q = c.get<number>(MeasurementNoiseProperty);
33+
const kalman = new KalmanFilter({ R: r, Q: q });
3134
this.kalmanFilterMap.set(id, kalman);
3235
return kalman.filter(value);
3336
}

0 commit comments

Comments
 (0)