Skip to content

Commit 48b1a33

Browse files
oskaptoskapt
authored
add troubleshooting steps to docs
I spent a day wondering why `ubus` wouldn't report changes to the device list in the ARP table before digging into the packets and discovering that it only looks at `hostapd.*`. Since I don't use the AP on my router, this won't work for me. I would have been thrilled to know in advance that it doesn't apply to my use case. I've added a line at the top that clarifies what it looks for, and I've added a block of troubleshooting steps because they were fresh in my mind and might help others in the future. I see a lot of posts in the forums about, "what the heck is <insert component> doing?" Knowing how to look at packets with tcpdump and wireshark is a useful skill.
1 parent d8bc095 commit 48b1a33

File tree

1 file changed

+99
-1
lines changed

1 file changed

+99
-1
lines changed

‎source/_components/device_tracker.ubus.markdown

Lines changed: 99 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ ha_release: 0.7.6
1414

1515
_This is one of the two ways we support OpenWRT. If you encounter problems, try [luci](/components/device_tracker.luci/)._
1616

17-
This is a presence detection scanner for [OpenWRT](https://openwrt.org/) using [ubus](http://wiki.openwrt.org/doc/techref/ubus).
17+
This is a presence detection scanner for [OpenWRT](https://openwrt.org/) using [ubus](http://wiki.openwrt.org/doc/techref/ubus). It scans for changes in `hostapd.*`, which will detect and report changes in devices connected to the access point on the router.
1818

1919
Before this scanner can be used you have to install the ubus RPC package on OpenWRT:
2020

@@ -70,3 +70,101 @@ Configuration variables:
7070
- **password** (*Required*): The password for your given account.
7171
7272
See the [device tracker component page](/components/device_tracker/) for instructions how to configure the people to be tracked.
73+
74+
## Troubleshooting
75+
76+
If you find that this never creates `known_devices.yaml`, or if you need more information on the communication chain between Home Assistant and OpenWRT, follow these steps to grab the packet stream and gain insight into what's happening.
77+
78+
### Increase Log Level
79+
80+
1. On your Home Assistant device, stop Home Assistant
81+
2. Adjust `configuration.yaml` to log more detail for the `device_tracker` component
82+
```yaml
83+
logger:
84+
default: warn
85+
logs:
86+
homeassistant.components.device_tracker: debug
87+
```
88+
3. In another window, tail the logfile in the configuration directory:
89+
```
90+
$ tail -f home-assistant.log | grep device_tracker
91+
```
92+
4. If you see a python stack trace like the following, check your configuration for correct username/password.
93+
```
94+
17-04-28 10:43:30 INFO (MainThread) [homeassistant.loader] Loaded device_tracker from homeassistant.components.device_tracker
95+
17-04-28 10:43:30 INFO (MainThread) [homeassistant.loader] Loaded device_tracker.ubus from homeassistant.components.device_tracker.ubus
96+
17-04-28 10:43:30 INFO (MainThread) [homeassistant.setup] Setting up device_tracker
97+
17-04-28 10:43:31 INFO (MainThread) [homeassistant.components.device_tracker] Setting up device_tracker.ubus
98+
17-04-28 10:43:31 ERROR (MainThread) [homeassistant.components.device_tracker] Error setting up platform ubus
99+
File "/opt/homeassistant/venv/lib/python3.4/site-packages/homeassistant/components/device_tracker/__init__.py", line 152, in async_setup_platform
100+
File "/opt/homeassistant/venv/lib/python3.4/site-packages/homeassistant/components/device_tracker/ubus.py", line 36, in get_scanner
101+
File "/opt/homeassistant/venv/lib/python3.4/site-packages/homeassistant/components/device_tracker/ubus.py", line 58, in __init__
102+
File "/opt/homeassistant/venv/lib/python3.4/site-packages/homeassistant/components/device_tracker/ubus.py", line 156, in _get_session_id
103+
File "/opt/homeassistant/venv/lib/python3.4/site-packages/homeassistant/components/device_tracker/ubus.py", line 147, in _req_json_rpc
104+
17-04-28 10:43:31 INFO (MainThread) [homeassistant.core] Bus:Handling <Event service_registered[L]: domain=device_tracker, service=see>
105+
17-04-28 10:43:31 INFO (MainThread) [homeassistant.core] Bus:Handling <Event component_loaded[L]: component=device_tracker>
106+
```
107+
5. If you see lines like the following repeated at intervals that correspond to the check interval from the config (12 seconds by default), then Home Assistant is correctly polling the router, and you'll need to look at what the router is sending back.
108+
```
109+
17-04-28 10:50:34 INFO (Thread-7) [homeassistant.components.device_tracker.ubus] Checking ARP
110+
```
111+
112+
### Inspect Packets With TCPDump
113+
_These steps require that `tcpdump` is installed on your Home Assistant device, and that you have a utility such as [Wireshark](https://www.wireshark.org) for viewing the packets. It also assumes that Home Assistant is communicating with your router over HTTP and not HTTPS._
114+
115+
1. On your Home Assistant device, stop Home Assistant
116+
2. In another shell on your Home Assistant device, start tcpdump
117+
```bash
118+
$ sudo tcpdump -nnvXSs 0 -w /var/tmp/dt.out 'host <router_ip> and port 80'
119+
```
120+
* In this example we are only looking for traffic to or from port 80, and we are writing the packet stream out to `/var/tmp/dt.out`
121+
3. Start Home Assistant
122+
4. After a few seconds you should see a line like `Got xx` where `xx` is an incrementing number. This indicates that it has captured packets that match our filter. After you see this number increment a few times (>20), you can hit `Ctrl-C` to cancel the capture.
123+
6. Transfer `/var/tmp/dt.out` to the machine where you're running Wireshark and either drag/drop it onto the Wireshark window or use File/Open to open the capture file.
124+
7. In the window that opens, look for the first line that reads `POST /ubus`. Right click on this line, choose Follow and then HTTP Stream to view just the HTTP stream for this connection.
125+
8. The first `POST` will show Home Assistant logging into ubus and receiving a session identifier back. It will look something like this:
126+
```
127+
POST /ubus HTTP/1.1
128+
Host: 10.68.0.1
129+
Accept: */*
130+
User-Agent: python-requests/2.13.0
131+
Connection: keep-alive
132+
Accept-Encoding: gzip, deflate
133+
Content-Length: 161
134+
135+
{"jsonrpc": "2.0", "params": ["00000000000000000000000000000000", "session", "login", {"password": "<password>", "username": "root"}], "method": "call", "id": 1}
136+
137+
HTTP/1.1 200 OK
138+
Date: Fri, 28 Apr 2017 12:04:46 GMT
139+
Content-Type: application/json
140+
Transfer-Encoding: chunked
141+
Connection: keep-alive
142+
143+
{"jsonrpc":"2.0","id":1,"result":[0,{"ubus_rpc_session":"8b4e1632389fcfd09e96a792e01c332c","timeout":300,"expires":300,"acls":{"access-group":{"unauthenticated":["read"],"user":["read"]},"ubus":{"*":["*"],"session":["access","login"]},"uci":{"*":["read"]}},"data":{"username":"root"}}]}
144+
```
145+
9. In the response above, the portion that reads `"result":[0,` indicates that ubus accepted the login without issue. If this is not `0`, search online for what ubus status corresponds to the number you're receiving and address any issues that it brings to light.
146+
10. Otherwise, back in the main Wireshark window click the `x` in the right side of the filter bar where it reads `tcp.stream eq 0`. Scroll down until you find the next `POST /ubus` line and view the HTTP stream again. This request is Home Assistant actually requesting information and will look something like the following:
147+
```
148+
POST /ubus HTTP/1.1
149+
Host: 10.68.0.1
150+
Accept: */*
151+
User-Agent: python-requests/2.13.0
152+
Connection: keep-alive
153+
Accept-Encoding: gzip, deflate
154+
Content-Length: 114
155+
156+
{"jsonrpc": "2.0", "params": ["8b4e1632389fcfd09e96a792e01c332c", "hostapd.*", "", {}], "method": "list", "id": 1}
157+
158+
HTTP/1.1 200 OK
159+
Date: Fri, 28 Apr 2017 12:04:46 GMT
160+
Content-Type: application/json
161+
Transfer-Encoding: chunked
162+
Connection: keep-alive
163+
164+
{"jsonrpc":"2.0","id":1,"result":{}}
165+
```
166+
11. In this case we are actually receiving a valid response with no data. The request says that we are looking for ARP information from `hostapd.*`, which is the access point on the router. In my environment I don't use the AP on the router, and so it was correctly returning no data. Armed with this information, I know that I cannot use this component for device tracking or presence.
167+
168+
### Cleanup
169+
170+
When you're done troubleshooting, remember to reset your logging configuration and delete any capture files that contain sensitive information.

0 commit comments

Comments
 (0)