Start | Migration | Scanning Issues | Troubleshooting | FAQ | Acknowledgements

Table of Contents

Scanning Issues

Scanning for devices relies on the Zeroconf technology stack. Simplified (and technically) it means that zeroconf devices acts as DNS servers and listens to requests on a specific multicast address (also using port 5353 instead of regular 53). When someone wants to find devices supporting a particular service, it sends a DNS request to the multicast address (on port 5353) and await response from other devices. This is an extremely simplified view of what is going on.

There are a number of sources of errors to consider:

The latter two seems to be most common. Lets break them down.

Timing issues

Timing issues can happen because pyatv only scans for a small period of time. By saying “scan”, we actually mean sending out requests and waiting for responses. The wait time should be long enough to receive all responses but short enough to not be annoying to the user. Waiting five minutes for a scan to finish is annoying. By default, pyatv scans for 3 seconds (with atvremote).

Not receiving responses within the time frame obviously is problematic. To make the matter even more complex: pyatv relies upon several services. One for MRP, one for AirPlay and so on. They are requested independently of each other. This means that it is possible to get a response for AirPlay but miss MRP because of timing issues (or other issues as well). You might see this happen sometimes when scanning, that one or more service is missing. This is the reason why that happens.

Response filtering

A behavior that has been observed is that the response is indeed received by the host (as seen with Wireshark), but it is never forwarded to the python process so zeroconf never receives it. Some filtering happens at some point for some reason. It is still unclear if this is a bug in python or not and should be investigated further.

Working around issues

Issues with scanning has always plauged pyatv and it still does. To mitigate the problems, support for “unicast scanning” has been added. It is meant as a compliment to regular scanning, as it cannot replace that.

Unicast scanning (which is an expression used here, it is not a commonly accepted term) works in the same way as regular multicast but the request is sent to specific hosts instead. You basically say: “scan these IP-addresses”. This seems to work more relibly and it also comes with some other advantages:

Support for unicast scanning has been added via the --scan-hosts flag in atvremote.

Troubleshooting further

If pyatv doesn’t find your devices, you can try other Zeroconf tools to see if it is a general issue or not.

For Linux:

$ avahi-browse --all

For macOS:

$ dns-sd -B _appletv-v2._tcp.
$ dns-sd -G -B _touch-able._tcp.
$ dns-sd -G -B _mediaremotetv._tcp.

If you get an error such as “command not found”, you do do not have avahi installed. You will have to consult your distributions support channels (e.g. forum) for help on this.

Here are some other possible sources of problems:

If you continue having problems scanning for devices, consider writing a support issue. Remember to include debug logs (--debug if you are using atvremote).

← Migration | Troubleshooting →