python-kasa/docs/source/discover.rst
Steven B 3490a1ef84
Add tutorial doctest module and enable top level await (#919)
Add a tutorial module with examples that can be tested with `doctest`.

In order to simplify the examples they can be run with doctest allowing
top level await statements by adding a fixture to patch the builtins
that xdoctest uses to test code.

---------

Co-authored-by: Teemu R. <tpr@iki.fi>
2024-05-16 18:13:44 +02:00

63 lines
2.2 KiB
ReStructuredText

.. py:module:: kasa.discover
Discovering devices
===================
.. contents:: Contents
:local:
Discovery
*********
Discovery works by sending broadcast UDP packets to two known TP-link discovery ports, 9999 and 20002.
Port 9999 is used for legacy devices that do not use strong encryption and 20002 is for newer devices that use different
levels of encryption.
If a device uses port 20002 for discovery you will obtain some basic information from the device via discovery, but you
will need to await :func:`Device.update() <kasa.SmartDevice.update()>` to get full device information.
Credentials will most likely be required for port 20002 devices although if the device has never been connected to the tplink
cloud it may work without credentials.
To query or update the device requires authentication via :class:`Credentials <kasa.Credentials>` and if this is invalid or not provided it
will raise an :class:`AuthenticationException <kasa.AuthenticationException>`.
If discovery encounters an unsupported device when calling via :meth:`Discover.discover_single() <kasa.Discover.discover_single>`
it will raise a :class:`UnsupportedDeviceException <kasa.UnsupportedDeviceException>`.
If discovery encounters a device when calling :meth:`Discover.discover() <kasa.Discover.discover>`,
you can provide a callback to the ``on_unsupported`` parameter
to handle these.
Example:
.. code-block:: python
import asyncio
from kasa import Discover, Credentials
async def main():
device = await Discover.discover_single(
"127.0.0.1",
credentials=Credentials("myusername", "mypassword"),
discovery_timeout=10
)
await device.update() # Request the update
print(device.alias) # Print out the alias
devices = await Discover.discover(
credentials=Credentials("myusername", "mypassword"),
discovery_timeout=10
)
for ip, device in devices.items():
await device.update()
print(device.alias)
if __name__ == "__main__":
asyncio.run(main())
API documentation
*****************
.. autoclass:: kasa.Discover
:members:
:undoc-members: