You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: support/README.md
+75-41Lines changed: 75 additions & 41 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -3,27 +3,33 @@ ____
3
3
4
4
## *Basics*
5
5
6
-
<details><summary> Will this be able to track my Apple Watch/Smart Watch?</summary>
6
+
<details><summary><b> Will this be able to track my Apple Watch/Smart Watch?</b></summary><p><p>
7
7
8
8
Yes, with a caveat. Many users, including myself, have successfully added Apple Watch Bluetooth addresses to the `known_static_addresses` file. In my personal experience, an Apple Watch works just fine [once it has connected to at least one other Bluetooth device, apart from your iPhone](https://github.com/andrewjfreyer/monitor#my-phone-doesnt-seem-to-automatically-broadcast-an-anonymous-bluetooth-advertisement-what-can-i-do). Other users have reported that the Apple Watch will occasionally not respond to `monitor`. Your mileage using the Apple Watch and/or other low-power connectible Bluetooth devices may vary. I strongly recommend tracking phones.
9
9
10
-
</details><details><summary> What special app do I need on my phone to get this to work?</summary>
10
+
</details>
11
+
12
+
<details><summary><b> What special app do I need on my phone to get this to work?</b></summary><p><p>
11
13
12
14
None, except in rare circumstances. The only requirement is that Bluetooth is left on. Works best with iPhones and Android phones that have peripheral mode enabled.
15
+
</details>
13
16
14
-
</details><details><summary> Does `monitor` reduce battery life for my phone?</summary>
17
+
<details><summary><b> Does `monitor` reduce battery life for my phone?</b></summary><p><p>
15
18
16
19
Not noticeable in my several years of using techniques similar to this.
20
+
</details>
17
21
18
-
</details><details><summary> How can I trigger an arrival scan?</summary>
22
+
<details><summary><b> How can I trigger an arrival scan?</b></summary><p><p>
19
23
20
24
Post a message with blank content to `monitor/scan/arrive`
25
+
</details>
21
26
22
-
</details><details><summary> How can I trigger an depart scan?</summary>
27
+
<details><summary><b> How can I trigger an depart scan?</b></summary><p><p>
23
28
24
29
Post a message with blank content to `monitor/scan/depart`
30
+
</details>
25
31
26
-
</details><details><summary> How can I trigger an arrive/depart scan from an automation in Home Assistant?</summary>
32
+
<details><summary><b> How can I trigger an arrive/depart scan from an automation in Home Assistant?</b></summary><p><p>
27
33
28
34
For an automation or script (or other service trigger), use:
29
35
@@ -38,20 +44,24 @@ For an automation or script (or other service trigger), use:
38
44
data:
39
45
topic: location/scan/depart
40
46
```
47
+
</details>
41
48
42
-
</details><details><summary> How can I add a known device without manually entering an address?</summary>
49
+
<details><summary><b> How can I add a known device without manually entering an address?</b></summary><p><p>
43
50
44
51
Post a message with the mac address separated from an alias (optional) by a space to: `monitor/setup/add known device`
52
+
</details>
45
53
46
-
</details><details><summary> How can I delete a known device without manually editing an address?</summary>
54
+
<details><summary><b> How can I delete a known device without manually editing an address?</b></summary><p><p>
47
55
48
56
Post a message with the mac address to: `monitor/setup/delete known device`
57
+
</details>
49
58
50
-
</details><details><summary> How can I upgrade to the latest version without using ssh?</summary>
59
+
<details><summary><b> How can I upgrade to the latest version without using ssh?</b></summary><p><p>
51
60
52
61
Post a message with blank content to `monitor/scan/update` or `monitor/scan/updatebeta`
62
+
</details>
53
63
54
-
</details><details><summary> How can I restart a `monitor` node?</summary>
64
+
<details><summary><b> How can I restart a `monitor` node?</b></summary><p><p>
Or, post a message with blank content to `monitor/scan/restart`
73
+
</details>
63
74
64
-
</details><details><summary> Why don't I see RSSI for my iPhone/Andriod/whatever phone?</summary>
75
+
<details><summary><b> Why don't I see RSSI for my iPhone/Andriod/whatever phone?</b></summary><p><p>
65
76
66
77
See the RSSI section of this FAQ. You'll have to connect your phone to `monitor` first.
78
+
</details>
67
79
68
-
</details><details><summary> How do I force an RSSI update for a known device, like my phone?</summary>
80
+
<details><summary><b> How do I force an RSSI update for a known device, like my phone?</b></summary><p><p>
69
81
70
82
Post a message with blank content to `monitor/scan/rssi`
71
83
84
+
</details>
85
+
72
86
____
73
87
74
88
## *Wi-Fi Interference & Performance Issues*
75
89
76
-
</details><details><summary> I'm running 5GHz Wi-Fi, I don't use Bluetooth for anything else, and I don't care whether I interfere with my neighbor's devices. Can't I just issue a name scan every few seconds to get faster arrival and depart detection?</summary>
90
+
<details><summary><b> I'm running 5GHz Wi-Fi, I don't use Bluetooth for anything else, and I don't care whether I interfere with my neighbor's devices. Can't I just issue a name scan every few seconds to get faster arrival and depart detection?</b></summary><p><p>
77
91
78
92
Yes, use periodic scanning mode with `-r`.
93
+
</details>
79
94
80
-
</details><details><summary> Can I use other Bluetooth services while `monitor` is running?</summary>
95
+
<details><summary><b> Can I use other Bluetooth services while `monitor` is running?</b></summary><p><p>
81
96
82
97
No. Monitor needs exclusive use of the Bluetooth radio to function properly. This is why it is designed to run on inexpensive hardware like the Raspberry Pi Zero W.
98
+
</details>
83
99
84
-
</details><details><summary> Can `monitor` run on XYZ hardware or in XYZ container?</summary>
100
+
<details><summary><b> Can `monitor` run on XYZ hardware or in XYZ container?</b></summary><p><p>
85
101
86
102
Probably. The script has been designed to minimize dependencies as much as possible. That said, I can't guarantee or provide support to all systems.
103
+
</details>
87
104
88
-
</details><details><summary> Does `monitor` interfere with Wi-Fi, Zigbee, or Zwave?</summary>
105
+
<details><summary><b> Does `monitor` interfere with Wi-Fi, Zigbee, or Zwave?</b></summary><p><p>
89
106
90
107
It can, if it scans too frequently, especially if you're running `monitor` from internal Raspberry Pi radios. Try to use all techniques for reducing `name` scans, including using trigger-only depart mode `-tdr`. When in this mode, `monitor` will never scan when all devices are home. Instead, `monitor` will wait until a `monitor/scan/depart` message is sent. Personally, I use my front door lock as a depart scan trigger.
108
+
</details>
91
109
92
-
</details><details><summary> How can I check if a `monitor` node is up and hasn't shut down for some reason?</summary>
110
+
<details><summary><b> How can I check if a `monitor` node is up and hasn't shut down for some reason?</b></summary><p><p>
93
111
94
112
Post a message to `monitor/scan/echo`, and you'll receive a response at the topic `$mqtt_topicpath/$mqtt_publisher_identity/echo`
113
+
</details>
95
114
96
-
</details><details><summary> I *still* have interference and/or my ssh sessions to the raspberry pi are really slow and laggy. What gives?</summary>
115
+
<details><summary><b> I *still* have interference and/or my ssh sessions to the raspberry pi are really slow and laggy. What gives?</b></summary><p><p>
97
116
98
117
Cheap Wi-Fi chipsets and cheap Bluetooth chipsets can perform poorly together if operated at the same time, especially on Raspberry Pi devices. If you still experience interference in your network, switching to a Wi-Fi dongle can help.
118
+
</details>
99
119
100
-
</details><details><summary> I use a Bluetooth dongle, and `monitor` seems to become non-responsive after a while - what's going on?</summary>
120
+
<details><summary><b> I use a Bluetooth dongle, and `monitor` seems to become non-responsive after a while - what's going on?</b></summary><p><p>
101
121
102
122
Many Bluetooth dongles do not properly filter out duplicate advertisements, so `monitor` gets overwhelmed trying to filter out hundreds of reports, when it expects dozens. I'm working on a solution, but for now the best option is to switch to internal Bluetooth or, alternatively, you can try another Bluetooth dongle.
123
+
</details>
124
+
103
125
___
104
126
105
127
## *Monitor Logs & Debugging*
106
128
107
-
</details><details><summary> I keep seeing that my Bluetooth hardware is "cycling" in the logs - what does that mean?</summary>
129
+
<details><summary><b> I keep seeing that my Bluetooth hardware is "cycling" in the logs - what does that mean?</b></summary><p><p>
108
130
109
131
If more than one program or executable try to use the Bluetooth hardware at the same time, your Bluetooth hardware will report an error. To correct this error, the hardware needs to be taken offline, then brought back.
132
+
</details>
110
133
111
-
</details><details><summary> I can't do **XYZ**, is `monitor` broken?</summary>
134
+
<details><summary><b> I can't do **XYZ**, is `monitor` broken?</b></summary><p><p>
112
135
113
136
Run via command line and post log output to github. Else, access `journalctl` to show the most recent logs:
114
137
115
138
```bash
116
139
journalctl -u monitor -r
117
140
```
141
+
</details>
118
142
119
-
</details><details><summary> My Android phone doesn't seem to send any anonymous advertisements, no matter what I do. Is there any solution?</summary>
143
+
<details><summary><b> My Android phone doesn't seem to send any anonymous advertisements, no matter what I do. Is there any solution?</b></summary><p><p>
120
144
121
-
Some phones, like the LG ThinQ G7 include an option in settings to enable file sharing via bluetooth. As resported by Home Assistant forum user @jusdwy, access this option via Settings >Connected Devices > File Sharing > File Sharing ON. For other android phones, an app like [Beacon Simulator](https://play.google.com/store/apps/details?</summary>id=net.alea.beaconsimulator&hl=en_US) may be a good option. You may also be able to see more information about Bluetooth on your phone using [nRF Connect](https://play.google.com/store/apps/details?</summary>id=no.nordicsemi.android.mcp&hl=en_US).
145
+
Some phones, like the LG ThinQ G7 include an option in settings to enable file sharing via bluetooth. As resported by Home Assistant forum user @jusdwy, access this option via Settings >Connected Devices > File Sharing > File Sharing ON. For other android phones, an app like [Beacon Simulator](https://play.google.com/store/apps/details?</b></summary><p><p>id=net.alea.beaconsimulator&hl=en_US) may be a good option. You may also be able to see more information about Bluetooth on your phone using [nRF Connect](https://play.google.com/store/apps/details?</b></summary><p><p>id=no.nordicsemi.android.mcp&hl=en_US).
122
146
123
147
Unfortunately, until Android OS includes at least one service that requires bluetooth peripheral mode to be enabled, Android devices will probably not advertise without an application running in the background. In short, as I understand it, Android/Google has been slow to adopt BTLE peripheral mode as an option in addition to the default central mode. [Here is a decently comprehensive list of phones that support peripheral mode](https://altbeacon.github.io/android-beacon-library/beacon-transmitter-devices.html), should an application choose to leverage the appropriate API. It does not appear as though the native OS has an option (outside of the file sharing option mentioned above on LG phones) to enable this mode.
124
148
125
149
Unfortunately, it seems to me that absent an application causing an advertisement to send, Android users will not be able to use monitor in the same way as iOS users or beacon users.
150
+
</details>
126
151
127
-
</details><details><summary> My phone doesn't seem to automatically broadcast an anonymous Bluetooth advertisement ... what can I do?</summary>
152
+
<details><summary><b> My phone doesn't seem to automatically broadcast an anonymous Bluetooth advertisement ... what can I do?</b></summary><p><p>
128
153
129
154
Many phones will only broadcast once they have already connected to *at least one* other Bluetooth device. Connect to a speaker, a car, a headset, or `monitor.sh -c [address]` and try again.
155
+
</details>
130
156
131
-
</details><details><summary> I have connected my phone to Bluetooth devices before but my phone doesn't seem to automatically broadcast an anonymous Bluetooth advertisement ... what can I do?</summary>
132
-
133
-
See above.
134
-
135
-
</details><details><summary> Why does my MQTT broker show connection and disconnection so often?</summary>
157
+
<details><summary><b> Why does my MQTT broker show connection and disconnection so often?</b></summary><p><p>
136
158
137
159
This is normal behavior for `mosquitto_pub` - nothing to worry about.
160
+
</details>
138
161
139
-
</details><details><summary> I updated and `monitor` is no longer working ... what gives?</summary>
162
+
<details><summary><b> I updated and `monitor` is no longer working ... what gives?</b></summary><p><p>
140
163
141
164
Make sure you've updated `mosquitto` to v1.5 or higher. In order to support a wider userbase, backward compatibility for old versions of `mosquitto` was dropped. It is alos strongly recommended that you upgrade to bash 4.4+.
165
+
</details>
142
166
143
-
</details><details><summary> I keep seeing MQTT Broker Offline messages in the `monitor` log. What's going on?</summary>
167
+
<details><summary><b> I keep seeing MQTT Broker Offline messages in the `monitor` log. What's going on?</b></summary><p><p>
144
168
145
169
mosquitto fails to connect to a broker if your password has certain special characters such as: `@`, `:`,`/` - if this is the case, the easiest solution is to create a new user for `monitor` with a different password.
170
+
</details>
146
171
147
-
</details><details><summary> Can I use a certfile for mosquitto instead of my password?</summary>
172
+
<details><summary><b> Can I use a certfile for mosquitto instead of my password?</b></summary><p><p>
148
173
149
174
Yes, specify a path for `mqtt_certificate_path` in mqtt_preferences.
175
+
</details>
150
176
151
177
____
152
178
153
179
## *Filters*
154
180
155
-
</details><details><summary> What filters do you personally use?</summary>
181
+
<details><summary><b> What filters do you personally use?</b></summary><p><p>
</details><details><summary> How do I use this as a device_tracker, in addition to the standard confidence messages?</summary>
200
+
<details><summary><b> How do I use this as a device_tracker, in addition to the standard confidence messages?</b></summary><p><p>
173
201
174
202
Set the option `PREF_DEVICE_TRACKER_REPORT` in your `behavior_preferences` file to true. If it's not there, add a line like this:
175
203
@@ -190,20 +218,22 @@ device_tracker:
190
218
```
191
219
192
220
The standard confidence report will also send.
221
+
</details>
193
222
194
-
</details><details><summary> How do I determine what values to set for filters?</summary>
223
+
<details><summary><b> How do I determine what values to set for filters?</b></summary><p><p>
195
224
196
225
Try using the verbose logging option `-V` to see what `monitor` sees when a new bluetooth device advertisement is seen. Then, power cycle the bluetooth radio on the device you'd like to track - you'll probably see a pattern develop with flags or manufacturers. Use these values to create your arrival filters!
197
226
198
227
Similarly, to set exclude filters, you can observe bluetooth traffic for a period of time to see what devices you simply do not care about seeing.
228
+
</details>
199
229
200
230
____
201
231
202
232
## *Other Questions*
203
233
204
-
</details><details><summary> It's annoying to have to keep track of mac addresses. Can't I just use a nickname for the mac addresses for MQTT topics?</summary>
234
+
<details><summary><b> It's annoying to have to keep track of mac addresses. Can't I just use a nickname for the mac addresses for MQTT topics?</b></summary><p><p>
205
235
206
-
Yes, this is now default behavior. All you have to do is provide a name next to the address in the `known_static_addresses` file. For example, if you have a known device with the mac address of 00:11:22:33:44:55 that you would like to call "Andrew's Phone":
236
+
Yes, this is default behavior. All you have to do is provide a name next to the address in the `known_static_addresses` file. For example, if you have a known device with the mac address of 00:11:22:33:44:55 that you would like to call "Andrew's Phone":
207
237
208
238
```bash
209
239
00:11:22:33:44:55 Andrew's iPhone
@@ -224,12 +254,14 @@ The same is true for beacons in the `known_beacon_addresses` file as well:
224
254
```
225
255
226
256
To disable this feature, set `PREF_ALIAS_MODE=false` in your `behavior_preferences` file.
257
+
</details>
227
258
228
-
</details><details><summary> I don't care about a few devices that are reporting. Can I block them?</summary>
259
+
<details><summary><b> I don't care about a few devices that are reporting. Can I block them?</b></summary><p><p>
229
260
230
261
Yes. Create a file called `address_blacklist` in your configuration directory and add the mac addresses you'd like to block (or uuid-major-minor for iBeacons) one at a time.
262
+
</details>
231
263
232
-
</details><details><summary> I can't use the `device_tracker` platform with the default status strings of `home` and `not_home` with my home automation software. What can I do?</summary>
264
+
<details><summary><b> I can't use the `device_tracker` platform with the default status strings of `home` and `not_home` with my home automation software. What can I do?</b></summary><p><p>
233
265
234
266
Set these options in `behavior_preferences`:
235
267
@@ -263,4 +295,6 @@ Generic:
263
295
PREF_DEVICE_TRACKER_HOME_STRING='home'
264
296
PREF_DEVICE_TRACKER_AWAY_STRING='away'
265
297
PREF_DEVICE_TRACKER_TOPIC_BRANCH='anything you like'
0 commit comments