update docs and examples to use sync with wait_for_result (#624)

docs/_config.yml

@@ -5,9 +5,9 @@ meta:
     title: XKNX - A Python KNX library
     keywords: KNX,KNX/IP,EIB,Home Automation,Home Assistant
     description: >
-            XKNX is a KNX library in Python. Helps you to control KNX devices
-            like Lights, Shutters, Covers,Switches, Outlets, Thermostats
-            via python scripts.
+        XKNX is a KNX library in Python. Helps you to control KNX devices
+        like Lights, Shutters, Covers, Switches, Outlets, Thermostats
+        via python scripts.
     robots: index,follow,noarchive,noodp
     google-site-verification: Z_FsKIe3iX8aXRXZG8NUgqOr3d41c5k9cBGccgKOvwM
 
@@ -27,8 +27,8 @@ logo: "/assets/img/xknx_logo_inverted.png"
 search_enabled: true
 
 aux_links:
-  "XKNX on GitHub":
-    - "//github.com/xknx/xknx"
+    "XKNX on GitHub":
+        - "//github.com/xknx/xknx"
 
 color_scheme: dark
 
@@ -37,4 +37,4 @@ gh_edit_link: true # show or hide edit this page link
 gh_edit_link_text: "Edit this page on GitHub."
 gh_edit_repository: "https://github.com/XKNX/xknx" # the github URL for your repo
 gh_edit_branch: "master" # the branch that your docs is served from
-gh_edit_view_mode: "edit" # "tree" or "edit" if you want the user to jump into the editor immediately
+gh_edit_view_mode: "edit" # "tree" or "edit" if you want the user to jump into the editor immediately

docs/climate.md

@@ -89,7 +89,7 @@ await climate.set_target_temperature(23)
 # Set new setpoint shift value.
 await climate.set_setpoint_shift(1)
 # Reading climate device
-await climate.sync()
+await climate.sync(wait_for_result=True)
 print("Current temperature: ", climate.temperature)
 ```
 

docs/cover.md

@@ -90,7 +90,7 @@ await cover.do('short_up')
 await cover.do('down')
 await cover.do('short_down')
 
-# Requesting state via KNX GROUP WRITE
+# Requesting state via KNX GroupValueRead
 await cover.sync()
 ```
 

docs/devices.md

@@ -8,10 +8,22 @@ has_children: true
 # [](#header-1)Devices
 
 XKNX uses devices to separate different functionality in logical groups like lights, climate et al.
-
 They are also needed in order to provide support for the home assistant plugin.
 
-The following pages will give you an overview over the available devices within XKNX.
+An instantiated device is automatically added to `xknx.devices`.
+
+## [](#header-2)Common public interface for all Device classes
+
+* `xknx` is the XKNX object.
+* `name` is the name of the object.
+* `device_updated_cb` List of awaitable callbacks for each update.
 
+* `has_group_address(group_address)` Test if device has given group address.
+* `sync(wait_for_result)` Read states of device from KNX bus via GroupValueRead requests.
+* `register_device_updated_cb(device_updated_cb)` Register device updated callback.
+* `unregister_device_updated_cb(device_updated_cb)` Unregister device updated callback.
+* `shutdown()` Remove callbacks and device form Devices vector.
 
+## [](#header-2)Device classes
 
+The following pages will give you an overview over the available devices within XKNX.

docs/light.md

@@ -95,6 +95,9 @@ await light.do('brightness:80')
 await light.do('tunable_white:75')
 await light.do('color_temperature:5000')
 
+# Update current state via KNX GroupValueRead
+await light.sync(wait_for_result=True)
+
 # Accessing state
 print(light.state)
 print(light.supports_brightness)
@@ -106,9 +109,6 @@ print(light.supports_tunable_white)
 print(light.current_tunable_white)
 print(light.supports_color_temperature)
 print(light.current_color_temperature)
-
-# Requesting current state via KNX GROUP WRITE
-await light.sync()
 ```
 
 ## [](#header-2)Example: RGBW light with individual group addresses for red, green, blue and white

docs/sensor.md

@@ -33,11 +33,14 @@ sensor = Sensor(
     value_type='temperature'
 )
 
-await sensor.sync() # Syncs the state. Tries to read the corresponding value from the bus.
+# Requesting current state via KNX GroupValueRead from the bus
+await sensor.sync(wait_for_result=True)
 
-sensor.resolve_state() # Returns the value of in a human readable way
+# Returns the value of in a human readable way
+sensor.resolve_state()
 
-sensor.unit_of_measurement() # returns the unit of the value in a human readable way
+# Returns the unit of the value as string
+sensor.unit_of_measurement()
 ```
 
 ## [](#header-2)Configuration via **xknx.yaml**

docs/time.md

@@ -21,7 +21,7 @@ time_device = DateTime(
     localtime=True
 )
 
-# Sending time to knx bus
+# `sync()` doesn't send a GroupValueRead when localtime is True but sends the current time to KNX bus
 await xknx.devices['TimeTest'].sync()
 ```
 

examples/example_daemon.py

@@ -15,9 +15,8 @@ async def main():
     xknx = XKNX(device_updated_cb=device_updated_cb, daemon_mode=True)
     Switch(xknx, name="TestOutlet", group_address="1/1/11")
 
-    # Wait until Ctrl-C was pressed
     await xknx.start()
-
+    # Wait until Ctrl-C was pressed
     await xknx.stop()
 
 

examples/example_light_state.py

@@ -18,8 +18,8 @@ async def main():
     )
     await light.set_brightness(128)
 
-    # Will do a group read of both addresses
-    await light.sync()
+    # Will do a GroupValueRead for both addresses and block until a result is received
+    await light.sync(wait_for_result=True)
 
     print(light)
 

examples/example_sensor.py

@@ -16,7 +16,7 @@ async def main():
         group_address_state="6/0/2",
         device_class="motion",
     )
-    await sensor1.sync()
+    await sensor1.sync(wait_for_result=True)
     print(sensor1)
 
     sensor2 = Sensor(
@@ -26,7 +26,7 @@ async def main():
         value_type="temperature",
     )
 
-    await sensor2.sync()
+    await sensor2.sync(wait_for_result=True)
     print(sensor2)
 
     await xknx.stop()