GeezerVison

The World Wide Web, restored to 800 pixels of glory.

GeezerVison is showing github.com — Add protocol and transport documentation by sdb9696 · Pull Request #663 · python-kasa/python-kasa

Add protocol and transport documentation #663

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged

rytilahti merged 2 commits into python-kasa:master from sdb9696:update_doc_protocols

Jan 22, 2024

Uh oh!

There was an error while loading. Please reload this page.

Merged

Add protocol and transport documentation #663

Show file tree

Hide file tree

Changes from all commits

Commits

Show all changes

2 commits

Select commit Hold shift + click to select a range

f1d86c6

Add protocol and transport documentation

File filter

Filter by extension .py (1) .rst (1) All 2 file types selected

Viewed files

Clear filters

Conversations

Failed to load comments.

Uh oh!

There was an error while loading. Please reload this page.

Jump to

Jump to file

Failed to load files.

Uh oh!

There was an error while loading. Please reload this page.

Diff view

Unified

Split

Hide whitespace

Diff view

Unified

Split

Hide whitespace

There are no files selected for viewing

83 changes: 83 additions & 0 deletions 83 docs/source/design.rst

Show comments

View file

Open in desktop

Original file line number	Diff line number	Diff line change
		@@ -1,5 +1,6 @@
		.. py:module:: kasa.modules


		.. _library_design:

		Library Design & Modules
Expand Down Expand Up		@@ -46,6 +47,7 @@ While the properties are designed to provide a nice API to use for common use ca
		you may sometimes want to access the raw, cached data as returned by the device.
		This can be done using the :attr:`~kasa.SmartDevice.internal_state` property.


		.. _modules:

		Modules
Expand All		@@ -61,6 +63,42 @@ You can get the list of supported modules for a given device instance using :att
		If you only need some module-specific information,
		you can call the wanted method on the module to avoid using :meth:`~kasa.SmartDevice.update`.

		Protocols and Transports
		************************

		The library supports two different TP-Link protocols, ``IOT`` and ``SMART``.
		``IOT`` is the original Kasa protocol and ``SMART`` is the newer protocol supported by TAPO devices and newer KASA devices.
Comment thread sdb9696 marked this conversation as resolved. Resolved Uh oh! There was an error while loading. Please reload this page.
		The original protocol has a ``target``, ``command``, ``args`` interface whereas the new protocol uses a different set of
		commands and has a ``method``, ``parameters`` interface.
		Confusingly TP-Link originally called the Kasa line "Kasa Smart" and hence this library used "Smart" in a lot of the
		module and class names but actually they were built to work with the ``IOT`` protocol.

		In 2021 TP-Link started updating the underlying communication transport used by Kasa devices to make them more secure.
		It switched from a TCP connection with static XOR type of encryption to a transport called ``KLAP`` which communicates
		over http and uses handshakes to negotiate a dynamic encryption cipher.
		This automatic update was put on hold and only seemed to affect UK HS100 models.

		In 2023 TP-Link started updating the underlying communication transport used by Tapo devices to make them more secure.
		It switched from AES encryption via public key exchange to use ``KLAP`` encryption and negotiation due to concerns
		around impersonation with AES.
		The encryption cipher is the same as for Kasa KLAP but the handshake seeds are slightly different.
		Also in 2023 TP-Link started releasing newer Kasa branded devices using the ``SMART`` protocol.
		This appears to be driven by hardware version rather than firmware.


		In order to support these different configurations the library migrated from a single :class:`TPLinkSmartHomeProtocol <kasa.protocol.TPLinkSmartHomeProtocol>`
		to support pluggable transports and protocols.
		The classes providing this functionality are:

		- :class:`BaseProtocol <kasa.protocol.BaseProtocol>`
		- :class:`IotProtocol <kasa.iotprotocol.IotProtocol>`
		- :class:`SmartProtocol <kasa.smartprotocol.SmartProtocol>`

		- :class:`BaseTransport <kasa.protocol.BaseTransport>`
		- :class:`AesTransport <kasa.aestransport.AesTransport>`
		- :class:`KlapTransport <kasa.klaptransport.KlapTransport>`
		- :class:`KlapTransportV2 <kasa.klaptransport.KlapTransportV2>`


		API documentation for modules
		*****************************
Expand All		@@ -70,3 +108,48 @@ API documentation for modules
		:members:
		:inherited-members:
		:undoc-members:



		API documentation for protocols and transports
		**********************************************

		.. autoclass:: kasa.protocol.BaseProtocol
		:members:
		:inherited-members:
		:undoc-members:

		.. autoclass:: kasa.iotprotocol.IotProtocol
		:members:
		:inherited-members:
		:undoc-members:

		.. autoclass:: kasa.smartprotocol.SmartProtocol
		:members:
		:inherited-members:
		:undoc-members:

		.. autoclass:: kasa.protocol.BaseTransport
		:members:
		:inherited-members:
		:undoc-members:

		.. autoclass:: kasa.klaptransport.KlapTransport
		:members:
		:inherited-members:
		:undoc-members:

		.. autoclass:: kasa.klaptransport.KlapTransportV2
		:members:
		:inherited-members:
		:undoc-members:

		.. autoclass:: kasa.aestransport.AesTransport
		:members:
		:inherited-members:
		:undoc-members:

		.. autoclass:: kasa.protocol.TPLinkSmartHomeProtocol
		:members:
		:inherited-members:
		:undoc-members:

2 changes: 1 addition & 1 deletion 2 kasa/protocol.py

Show comments

View file

Open in desktop

Original file line number	Diff line number	Diff line change
Expand Up		@@ -168,7 +168,7 @@ async def query(self, request: Union[str, Dict], retry_count: int = 3) -> Dict:

		:param str host: host name or ip address of the device
		:param request: command to send to the device (can be either dict or
		json string)
		json string)
		:param retry_count: how many retries to do in case of failure
		:return: response dict
		"""
Expand Down

Add this suggestion to a batch that can be applied as a single commit. This suggestion is invalid because no changes were made to the code. Suggestions cannot be applied while the pull request is closed. Suggestions cannot be applied while viewing a subset of changes. Only one suggestion per line can be applied in a batch. Add this suggestion to a batch that can be applied as a single commit. Applying suggestions on deleted lines is not supported. You must change the existing code in this line in order to create a valid suggestion. Outdated suggestions cannot be applied. This suggestion has been applied or marked resolved. Suggestions cannot be applied from pending reviews. Suggestions cannot be applied on multi-line comments. Suggestions cannot be applied while the pull request is queued to merge. Suggestion cannot be applied right now. Please check back later.

You are visitor 01402520 — GeezerVison does not store the pages you look up.
Best viewed with Netscape Navigator 4.7 or Internet Explorer 6 at 800×600. No cookies required.