From e699f2b03ad2e58f15d025cb87936e7428b5f61d Mon Sep 17 00:00:00 2001 From: Ricardo Steijn <61013287+RicArch97@users.noreply.github.com> Date: Mon, 22 Jun 2020 13:35:12 +0200 Subject: [PATCH 1/2] Update README.md --- README.md | 93 ++++++++++++++++++++++++++++++++----------------------- 1 file changed, 54 insertions(+), 39 deletions(-) diff --git a/README.md b/README.md index dd5d02d..a558f96 100644 --- a/README.md +++ b/README.md @@ -45,26 +45,28 @@ $ python setup.py install ```Python from crownstone_cloud.lib.cloud import CrownstoneCloud +import logging import asyncio +# enable logging +logging.basicConfig(format='%(levelname)s:%(message)s', level=logging.INFO) + async def main(): # init cloud cloud = CrownstoneCloud('email', 'password') - await cloud.initialize() + await cloud.async_initialize() + + # get a crownstone by name that can dim, and put it on 50% brightness + crownstone_lamp = cloud.get_crownstone('Lamp') + await crownstone_lamp.async_set_brightness(0.5) - # get a crownstone by name and switch it on - crownstone = cloud.get_crownstone('awesomeCrownstone') - await crownstone.turn_on() + # get a crownstone by name and turn it on + crownstone_tv = cloud.get_crownstone('TV') + await crownstone_tv.async_turn_on() - # switch all crownstones in a sphere to on: - sphere = cloud.spheres.find('awesomeSphere') - for crownstone in sphere.crownstones: - await crownstone.turn_on() - - # close session - # required when ran as standalone program, optional if ran in integration. - await cloud.close_session() + # close the session after we are done + await cloud.async_close_session() asyncio.run(main()) ``` @@ -73,18 +75,20 @@ asyncio.run(main()) ```Python from crownstone_cloud.lib.cloud import CrownstoneCloud +import logging + +# enable logging +logging.basicConfig(format='%(levelname)s:%(message)s', level=logging.INFO) # init cloud cloud = CrownstoneCloud('email', 'password') -cloud.initialize_sync() +cloud.initialize() -# get a crownstone and turn it on -crownstone = cloud.get_crownstone('awesomeCrownstone') -crownstone.turn_on_sync() +# get a crownstone by name and turn it on +crownstone_coffee_machine = cloud.get_crownstone('Coffee machine') +crownstone_coffee_machine.turn_on() -# close session -# required when ran as standalone program, optional if ran in integration. -cloud.close_session_sync() +cloud.close_session() ``` ### Initialization @@ -103,11 +107,11 @@ cloud.set_access_token('myAccessToken') ``` to initialize all the cloud data into the lib, for async usage use: ```Python -await cloud.initialize() +await cloud.async_initialize() ``` Or for sync usage use: ```Python -cloud.initialize_sync() +cloud.initialize() ``` It is only required to call initialize once at the beginning of the program. @@ -150,6 +154,7 @@ A Sphere has the following fields in the cloud lib: * name: String * cloud_id: String * unique_id: String +* present_people: List ### Locations @@ -176,8 +181,8 @@ Example names of Crownstones: * Television A Crownstone has the following fields in the cloud lib: +* abilities: Dict * state: Float (0..1) -* dimming_enabled: Bool (default = False) * name: String * unique_id: String * cloud_id: String @@ -204,7 +209,7 @@ A User has the following fields in the cloud lib: ### Cloud -#### initialize() +#### async_initialize() > Login if no access token available, and sync all data for the user from the cloud. #### set_access_token(access_token: String) @@ -216,10 +221,16 @@ A User has the following fields in the cloud lib: #### get_crownstone_by_id(crownstone_id: String) -> Crownstone > Get a Crownstone object by it's id, it's it exists. +#### async_close_session() +> Async function. This will close the websession in requestHandler to cleanup nicely after the program has finished. + +#### reset() +> Reset the requestHandler parameters in case the cloud instance was cleaned up and needs to be recreated. + ### Spheres -#### update() -> Async function. Sync the Spheres with the cloud. Doing this will replace all current sphere data with that of the cloud. +#### async_update_sphere_data() +> Async function. Sync the Spheres with the cloud. Calling the function again after init will update the current data. #### find(sphere_name: String) -> Sphere > Returns a sphere object if one exists by that name. @@ -229,13 +240,13 @@ A User has the following fields in the cloud lib: ### Sphere -#### get_keys() -> Dict +#### async_get_keys() -> Dict > Async function. Returns a dict with the keys of this sphere. The keys can be used for BLE connectivity with the Crownstones. ### Crownstones -#### update() -> Async function. Sync the Crownstones with the cloud for a sphere. Doing this will replace all the current crownstone data with that of the cloud. +#### async_update_crownstone_data() +> Async function. Sync the Crownstones with the cloud for a sphere. Calling the function again after init will update the current data. #### find(crownstone_name: String) -> Crownstone > Return a Crownstone object if one exists by that name. @@ -245,19 +256,22 @@ A User has the following fields in the cloud lib: ### Crownstone -#### turn_on() +#### async_turn_on() > Async function. Send a command to turn a Crownstone on. To make this work make sure to be in the selected sphere and have Bluetooth enabled on your phone. -#### turn_off() +#### async_turn_off() > Async function. Send a command to turn a Crownstone off. To make this work make sure to be in the selected sphere and have Bluetooth enabled on your phone. -#### set_brightness(percentage: Int) +#### async_set_brightness(value: Float) > Async function. Send a command to set a Crownstone to a given brightness level. To make this work make sure to be in the selected sphere and have Bluetooth enabled on your phone. ### Locations -#### update() -> Async function. Sync the Locations en present people in that location with the cloud for a sphere. Doing this will replace all the current location data with that of the cloud. +#### async_update_location_data() +> Async function. Sync the Locations with the cloud for a sphere. Calling the function again after init will update the current data. + +#### async_update_location_presence() +> Async function. Sync the presence with the cloud. This will replace the current presence with the new presence. #### find(location_name: String) -> Location > Return a location object if one exists by that name. @@ -267,8 +281,8 @@ A User has the following fields in the cloud lib: ### Users -#### update() -> Async function. Sync the Users with the cloud for a sphere. Doing this will replace all the current user data with that of the cloud. +#### async_update_user_data() +> Async function. Sync the Users with the cloud for a sphere. Calling the function again after init will update the current data. #### find_by_first_name(first_name: String) -> List > Returns a list of all users with that first name, as duplicate first names can exist. @@ -281,15 +295,16 @@ A User has the following fields in the cloud lib: ## Async vs sync The lib can be used synchonously and asynchronously.
+All async functions in the library API functions in this library have the prefix **async_** Async functions need to be awaited: ```Python -await cloud.spheres.update() +await cloud.spheres.async_update_sphere_data() ``` All the async functions mentioned above can also be used synchronously.
-Simply type the same function name, but with underscore sync at the end. for example: +Sync functions don't have the async prefix. for example: ```Python -cloud.initialize_sync() -cloud.spheres.update_sync() +cloud.initialize() +cloud.spheres.update_sphere_data() ``` Make sure to see the examples above! From 9ac44d0e20b72fc6903ca1fd50f4a0f5e4fe4621 Mon Sep 17 00:00:00 2001 From: Ricardo Steijn <61013287+RicArch97@users.noreply.github.com> Date: Mon, 22 Jun 2020 13:35:28 +0200 Subject: [PATCH 2/2] Update README.md --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index a558f96..6619bab 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,7 @@ Asynchronous Python library to get data from the cloud, and switch Crownstones. ## Requirements * Python 3.7 (only version that it's tested on currently) -* Aiohttp 3.6.2 +* Aiohttp 3.6.1 ## Standard installation