From 98b40b5072692805950a3a36d50ca69ac240fc50 Mon Sep 17 00:00:00 2001 From: Teemu R Date: Wed, 9 Dec 2020 10:13:14 +0100 Subject: [PATCH] Improve cli documentation for bulbs and power strips (#123) --- README.md | 1 + docs/source/cli.rst | 19 +++++++----- docs/source/conf.py | 3 ++ docs/source/index.rst | 3 -- docs/source/smartbulb.rst | 53 +++++++++++++++++++++++++++++++++ docs/source/smartdevice.rst | 4 +++ docs/source/smartdimmer.rst | 7 +++++ docs/source/smartlightstrip.rst | 7 +++++ docs/source/smartplug.rst | 8 +++++ docs/source/smartstrip.rst | 31 +++++++++++++++++++ 10 files changed, 126 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index 09329ef1..fcc089ce 100644 --- a/README.md +++ b/README.md @@ -115,6 +115,7 @@ or the `parse_pcap.py` script contained inside the `devtools` directory. * HS300 * KP303 +* KP400 ### Wall switches diff --git a/docs/source/cli.rst b/docs/source/cli.rst index 0d1989db..1e656997 100644 --- a/docs/source/cli.rst +++ b/docs/source/cli.rst @@ -2,18 +2,23 @@ Command-line usage ================== The package is shipped with a console tool named kasa, please refer to ``kasa --help`` for detailed usage. -The device to which the commands are sent is chosen by `KASA_HOST` environment variable or passing ``--host
`` as an option. +The device to which the commands are sent is chosen by ``KASA_HOST`` environment variable or passing ``--host
`` as an option. To see what is being sent to and received from the device, specify option ``--debug``. -To avoid discovering the devices when executing commands its type can be passed by specifying either ``--plug`` or ``--bulb``, -if no type is given its type will be discovered automatically with a small delay. -Some commands (such as reading energy meter values and setting color of bulbs) additional parameters are required, -which you can find by adding ``--help`` after the command, e.g. ``kasa emeter --help`` or ``kasa hsv --help``. +To avoid discovering the devices when executing commands its type can be passed as an option (e.g., ``--plug`` for plugs, ``--bulb`` for bulbs, ..). +If no type is manually given, its type will be discovered automatically which causes a short delay. If no command is given, the ``state`` command will be executed to query the device state. +.. note:: + + Some commands (such as reading energy meter values, changing bulb settings, or accessing individual sockets on smart strips) additional parameters are required, + which you can find by adding ``--help`` after the command, e.g. ``kasa emeter --help`` or ``kasa hsv --help``. + Refer to the device type specific documentation for more details. + + Provisioning -~~~~~~~~~~~~ +************ You can provision your device without any extra apps by using the ``kasa wifi`` command: @@ -23,6 +28,6 @@ You can provision your device without any extra apps by using the ``kasa wifi`` 4. Join/change the network using ``kasa wifi join`` command, see ``--help`` for details. ``kasa --help`` -~~~~~~~~~~~~~~~ +*************** .. program-output:: kasa --help diff --git a/docs/source/conf.py b/docs/source/conf.py index 7e718402..6090e924 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -31,6 +31,7 @@ extensions = [ "sphinx.ext.autodoc", "sphinx.ext.coverage", "sphinx.ext.viewcode", + "sphinx.ext.todo", "sphinxcontrib.programoutput", ] @@ -55,6 +56,8 @@ html_theme = "sphinx_rtd_theme" # so a file named "default.css" will overwrite the builtin "default.css". html_static_path = ["_static"] +todo_include_todos = True + def setup(app): # add copybutton to hide the >>> prompts, see https://github.com/readthedocs/sphinx_rtd_theme/issues/167 diff --git a/docs/source/index.rst b/docs/source/index.rst index 59897b39..2804757e 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -1,6 +1,3 @@ -python-kasa documentation -========================= - .. mdinclude:: ../../README.md .. toctree:: diff --git a/docs/source/smartbulb.rst b/docs/source/smartbulb.rst index 76f66224..bf58ecbf 100644 --- a/docs/source/smartbulb.rst +++ b/docs/source/smartbulb.rst @@ -1,6 +1,59 @@ Bulbs =========== +Supported features +****************** + +* Turning on and off +* Setting brightness, color temperature, and color (in HSV) +* Querying emeter information +* Transitions + +Currently unsupported +********************* + +* Setting the default transitions +* Timers + +.. note:: + + Feel free to open a pull request to add support for more features! + +Transitions +*********** + +All commands changing the bulb state can be accompanied with a transition, e.g., to slowly fade the light off. +The transition time is in milliseconds, 0 means immediate change. +If no transition value is given, the default setting as configured for the bulb will be used. + +.. note:: + + Accepted values are command (and potentially bulb) specific, feel free to improve the documentation on accepted values. + + **Example:** While KL130 allows at least up to 15 second transitions for smooth turning off transitions, turning it on will not be so smooth. + +Command-line usage +****************** + +All command-line commands can be used with transition period for smooth changes. + + +**Example:** Turn the bulb off over a 15 second time period. + +.. code:: + + $ kasa --bulb --host off --transition 15000 + +**Example:** Change the bulb to red with 20% brightness over 15 seconds: + +.. code:: + + $ kasa --bulb --host hsv 0 100 20 --transition 15000 + + +API documentation +***************** + .. autoclass:: kasa.SmartBulb :members: :undoc-members: diff --git a/docs/source/smartdevice.rst b/docs/source/smartdevice.rst index dd08ac91..6b83c1a5 100644 --- a/docs/source/smartdevice.rst +++ b/docs/source/smartdevice.rst @@ -40,6 +40,10 @@ Refer to device type specific classes for more examples: * :class:`SmartDimmer` * :class:`SmartLightStrip` + +API documentation +~~~~~~~~~~~~~~~~~ + .. autoclass:: kasa.SmartDevice :members: :undoc-members: diff --git a/docs/source/smartdimmer.rst b/docs/source/smartdimmer.rst index f55d571c..fa4e1ece 100644 --- a/docs/source/smartdimmer.rst +++ b/docs/source/smartdimmer.rst @@ -1,6 +1,13 @@ Dimmers ======= +.. note:: + + Feel free to open a pull request to improve the documentation! + +API documentation +***************** + .. autoclass:: kasa.SmartDimmer :members: :undoc-members: diff --git a/docs/source/smartlightstrip.rst b/docs/source/smartlightstrip.rst index b02342ed..4d34efbb 100644 --- a/docs/source/smartlightstrip.rst +++ b/docs/source/smartlightstrip.rst @@ -1,6 +1,13 @@ Light strips ============ +.. note:: + + Feel free to open a pull request to improve the documentation! + +API documentation +***************** + .. autoclass:: kasa.SmartLightStrip :members: :undoc-members: diff --git a/docs/source/smartplug.rst b/docs/source/smartplug.rst index 75b342cb..e9b8ccdf 100644 --- a/docs/source/smartplug.rst +++ b/docs/source/smartplug.rst @@ -1,6 +1,14 @@ Plugs ===== +.. note:: + + Feel free to open a pull request to improve the documentation! + + +API documentation +***************** + .. autoclass:: kasa.SmartPlug :members: :undoc-members: diff --git a/docs/source/smartstrip.rst b/docs/source/smartstrip.rst index b6c9ff90..460f211e 100644 --- a/docs/source/smartstrip.rst +++ b/docs/source/smartstrip.rst @@ -1,6 +1,37 @@ Smart strips ============ + +.. note:: + + The emeter feature is currently not implemented for smart strips. See https://github.com/python-kasa/python-kasa/issues/64 for details. + +.. note:: + + Feel free to open a pull request to improve the documentation! + +Command-line usage +****************** + +To command a single socket of a strip, you will need to specify it either by using ``--index`` or by using ``--name``. +If not specified, the commands will act on the parent device: turning the strip off will turn off all sockets. + +**Example:** Turn off the first socket (the indexing starts from zero): + +.. code:: + + $ kasa --strip --host on --index 0 + +**Example:** Turn on the socket by name: + +.. code:: + + $ kasa --strip --host off --name "Maybe Kitchen" + + +API documentation +***************** + .. autoclass:: kasa.SmartStrip :members: :undoc-members: