Skip to content

Commit

Permalink
refactor: rename insensitive list properties
Browse files Browse the repository at this point in the history
For public-facing options the previous namings are still supported, but
deprecated and removed from the docs.

Closes #347
  • Loading branch information
mKeRix committed Dec 6, 2020
1 parent b0b2f7c commit 396289c
Show file tree
Hide file tree
Showing 6 changed files with 177 additions and 127 deletions.
2 changes: 1 addition & 1 deletion docs/integrations/bluetooth-classic.md
Original file line number Diff line number Diff line change
Expand Up @@ -65,7 +65,7 @@ Bluetooth uses the 2.4 GHz band, which may also be used by some of your other Wi

On some Single Board computers, such as the Raspberry Pis with integrated Wifi/BT, Bluetooth and WiFi are on a shared chip and antenna. If Bluetooth communication is happening the chip will temporarily shutdown WiFi packets until it is done, then switch back. Only one protocol is active at the same time, which can lead to request timeouts and delays in packets: if the the device is pinged at the wrong time, it won't accept a connection, and thus will time out. It will also lead to sluggish SSH sessions occasionally.

Why? The command used for polling takes about 5.5s overall, most of which are Bluetooth communication. If all whitelisted devices are away the SBC essentially only has about 1s of the 6s interval available for WiFi communication. If devices are near the effects are much less noticeable, as the polling finishes quickly and unlocks the chip for WiFi communication.
Why? The command used for polling takes about 5.5s overall, most of which are Bluetooth communication. If all allowlisted devices are away the SBC essentially only has about 1s of the 6s interval available for WiFi communication. If devices are near the effects are much less noticeable, as the polling finishes quickly and unlocks the chip for WiFi communication.

If you don't have anything else running on the Pis this shouldn't be much of an issue - room-assistant can handle the harsh network conditions. If you want the Pis to be more responsive and/or run other applications on them, currently there is only one solution that will do the trick: increase the interval. Keep in mind this also slows down the detection a bit.

Expand Down
16 changes: 8 additions & 8 deletions docs/integrations/bluetooth-low-energy.md
Original file line number Diff line number Diff line change
Expand Up @@ -37,9 +37,9 @@ This integration requires you to run room-assistant in the `host` network.

## Determining the IDs

In order to not clutter your home automation software with the many BLE devices broadcasting their status nearby, room-assistant requires you to set up a whitelist or blacklist before it will pass on any information. For regular BLE devices this is the lowercase MAC address without `:`, for example `7750fb4dab70` for a peripheral with the MAC address `77:50:FB:4D:AB:70`. When using iBeacons the ID will be in the format of `uuid-major-minor`, for example `2f234454cf6d4a0fadf2f4911ba9ffa6-1-2`.
In order to not clutter your home automation software with the many BLE devices broadcasting their status nearby, room-assistant requires you to set up a allowlist or denylist before it will pass on any information. For regular BLE devices this is the lowercase MAC address without `:`, for example `7750fb4dab70` for a peripheral with the MAC address `77:50:FB:4D:AB:70`. When using iBeacons the ID will be in the format of `uuid-major-minor`, for example `2f234454cf6d4a0fadf2f4911ba9ffa6-1-2`.

If you are unsure what ID your device has you can start room-assistant with the BLE integration enabled, but no whitelist. Devices that are seen for the first time after starting will be logged with their ID to the console.
If you are unsure what ID your device has you can start room-assistant with the BLE integration enabled, but no allowlist. Devices that are seen for the first time after starting will be logged with their ID to the console.

## Tracking iOS Devices

Expand All @@ -51,10 +51,10 @@ The app is currently in beta, you can join it through TestFlight with this link:

| Name | Type | Default | Description |
| ----------------- | ------------------------------- | -------- | ------------------------------------------------------------ |
| `whitelist` | Array | | A list of [BLE tag IDs](#determining-the-ids) that should be tracked. |
| `whitelistRegex` | Boolean | `false` | Whether the whitelist should be evaluated as a list of [regular expressions](https://en.wikipedia.org/wiki/Regular_expression) or not. |
| `blacklist` | Array | | A list of [BLE tag IDs](#determining-the-ids) that should not be tracked. If an ID matches both whitelist and blacklist it will not be tracked. |
| `blacklistRegex` | Boolean | `false` | Whether the blacklist should be evaluated as a list of [regular expressions](https://en.wikipedia.org/wiki/Regular_expression) or not. |
| `allowlist` | Array | | A list of [BLE tag IDs](#determining-the-ids) that should be tracked. |
| `allowlistRegex` | Boolean | `false` | Whether the allowlist should be evaluated as a list of [regular expressions](https://en.wikipedia.org/wiki/Regular_expression) or not. |
| `denylist` | Array | | A list of [BLE tag IDs](#determining-the-ids) that should not be tracked. If an ID matches both allowlist and denylist it will not be tracked. |
| `denylistRegex` | Boolean | `false` | Whether the denylist should be evaluated as a list of [regular expressions](https://en.wikipedia.org/wiki/Regular_expression) or not. |
| `processIBeacon` | Boolean | `true` | Whether additional data from iBeacon devices should be taken into account or not. Affects tag IDs and distance estimation. |
| `onlyIBeacon` | Boolean | `false` | Whether only iBeacons should be considered when scanning for devices ot not. |
| `timeout` | Number | `5` | The time after which a recorded distance is considered outdated. This value should be higher than the advertisement frequency of your peripheral. |
Expand Down Expand Up @@ -82,7 +82,7 @@ global:
integrations:
- bluetoothLowEnergy
bluetoothLowEnergy:
whitelist:
allowlist:
- 7750fb4dab70
- 2f234454cf6d4a0fadf2f4911ba9ffa6-1-2
maxDistance: 7
Expand Down Expand Up @@ -110,7 +110,7 @@ bluetoothClassic:
- '77:50:fb:4d:ab:70'
bluetoothLowEnergy:
hciDeviceId: 1
whitelist:
allowlist:
- 7750fb4dab70
- 2f234454cf6d4a0fadf2f4911ba9ffa6-1-2
```
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,12 @@ export class BluetoothLowEnergyConfig {
hciDeviceId = 0;
whitelist: string[] = [];
whitelistRegex = false;
allowlist: string[] = [];
allowlistRegex = false;
blacklist: string[] = [];
blacklistRegex = false;
denylist: string[] = [];
denylistRegex = false;
processIBeacon = true;
onlyIBeacon = false;
majorMask = 0xffff;
Expand Down

0 comments on commit 396289c

Please sign in to comment.