Update README.md

Author: RicArch97

README.md

@@ -11,7 +11,7 @@ Asynchronous Python library to get data from the cloud, and switch Crownstones.
 
 ## Requirements
 
-* Python 3.7 or higher
+* Python 3.7 (only version that it's tested on currently)
 * Aiohttp 3.6.2
 
 ## Standard installation
@@ -39,33 +39,70 @@ $ python setup.py install
 
 ## Getting started
 
-### Example
+### Examples
+
+#### Async example
 
 ```Python
-from cloudLib.lib.cloud import CrownstoneCloud
+from crownstone_cloud.lib.cloud import CrownstoneCloud
+import asyncio
+
+
+async def main():
+    # init cloud
+    cloud = CrownstoneCloud('email', 'password')
+    await cloud.initialize()
+
+    # get a crownstone by name and switch it on
+    crownstone = cloud.get_crownstone('awesomeCrownstone')
+    await crownstone.turn_on()
 
-cloud = CrownstoneCloud()
+    # switch all crownstones in a sphere to on:
+    sphere = cloud.spheres.find('awesomeSphere')
+    for crownstone in sphere.crownstones:
+        await crownstone.turn_on()
 
+asyncio.run(main())
+```
+
+#### Sync example
+
+```Python
+from crownstone_cloud.lib.cloud import CrownstoneCloud
 
-############# this function will be executed #############
-async def run():
-    # login to the cloud using your account (replace with your own credentials)
-    await cloud.login('email', 'password')
-    # load all the user data from the cloud
-    await cloud.sync()
+# init cloud
+cloud = CrownstoneCloud('email', 'password')
+cloud.initialize_sync()
 
-    # get a crownstone by name
-    lamp = cloud.get_crownstone('Lamp')
-    # turn the crownstone on
-    await lamp.turn_on()
+# get a crownstone and turn it on
+crownstone = cloud.get_crownstone('awesomeCrownstone')
+crownstone.turn_on_sync()
+```
 
-    # close the session
-    await cloud.cleanup()
-##########################################################
+### Initialisation
+Crownstone cloud is initialized with 2 arguments:
+* User email
+* User password
 
-# start executing the function
-cloud.start(run())
+If you do not yet have a Crownstone account, go to (My Crownstone)[my.crownstone.rocks] to set one up.
+The email and password are used to re-login after an access token has expired.
+```Python
+cloud = CrownstoneCloud('email', 'password')
+```
+if already have an access token and you want to skip to first login for speed you can use:
+```Python
+cloud.set_access_token('myAccessToken')
+```
+to initialize all the cloud data into the lib use
+```Python
+await cloud.initialize()
+```
+for async usage, or use
+```Python
+cloud.initialize_sync()
 ```
+for sync usage.<br>
+It is only required to call initialize once at the beginning of the program.
 
 ## Data structure
 
@@ -83,35 +120,29 @@ The cloud can be displayed with the following structure:
 The user is the to whom the data belongs.<br> 
 The user is the one that logs in using email and password.<br>
 By getting a user specific access token after login, the data for that specific user can be requested.
-```python
-await cloud.login('email', 'password')
-```
 
 ### Keys
 
 The keys are user specific.<br> 
 They are required to connect to the crownstone bluetooth mesh.<br>
 The most common used keys are the sphere keys. They are located within each individual sphere.<br>
-Getting the keys is optional and not included in the general sync.<br>
-The keys are returned as a dictionary.
-To get the keys for a sphere:
-```python
-sphere = cloud.spheres.find('MySphere')
-keys = await sphere.get_keys()
-```
 
 ### Spheres
 
-Spheres can be seen as a house, apartement or office. They have rooms (locations), Crownstones and users in them.<br>
-Note that the spheres need to be synced **FIRST** before the other data can be synced.<br>
-To get spheres for the user without any data (only name and id) use:
-```python
-await cloud.spheres.sync()
-```
-To get the spheres and all their data at once use:
-```python
-await cloud.sync()
-```
+Spheres are the main data entry. They have rooms (locations), Crownstones and users in them.<br>
+Example spheres:
+* House
+* Office
+* Apartement
+
+A Sphere has the following fields in the cloud lib:
+* crownstones: Crownstones
+* locations: Locations
+* users: Users
+* keys: Dict (optional, default = None)
+* name: String
+* cloud_id: String
+* unique_id: String
 
 ### Locations
 
@@ -122,48 +153,29 @@ For example for a house:
 * Garage
 * Bathroom
 
-To get the locations for your sphere use:
-```python
-sphere = cloud.spheres.find('MySphere')
-await sphere.locations.sync()
-```
-For the presence tracking, an advanced algorithm detects whenever a user is on a specific location.<br>
-The presence is saved for each location in a list. The list contains names of the people who are present.<br>
-To print the present people list:
-```python
-location = sphere.locations.find('MyLocation')
-print(location.present_people)
-```
+A Location has the following fields in the cloud lib:
+* present_people: List
+* name: String
+* cloud_id: String
+* unique_id: String
 
 ### Crownstones
 
 Crownstones are smart plugs that can make every device that isn't smart, way smarter!<br>
 Crownstones are located within a sphere.<br>
-Example Crownstones:
+Example names of Crownstones:
 * Lamp
 * Charger
 * Television
 
-to get the crownstones for your sphere:
-```python
-sphere = cloud.spheres.find('MySphere')
-await sphere.crownstones.sync()
-```
-Crownstones can also be turned on/off remotely.<br>
-Since this is a command sent to your phone, it is required to have Bluetooth on and to be present in your sphere.<br>
-To switch a crownstone on/off:
-```python
-crownstone = cloud.get_crownstone('MyCrownstone')
-await crownstone.turn_on()
-await crownstone.turn_off()
-```
-It is also possible to set the brightness(dimming) of a crownstone.<br>
-For this to work, you need to enable dimming in your crownstone app for that specific crownstone. Dimming only works with lights and it is **not** recommended to use it for any other device.<br>
-For the brightness use a percentage between 0% and 100%. To set the brightness:
-```python
-crownstone = cloud.get_crownstone('MyCrownstone')
-await crownstone.set_brightness(50)
-```
+A Crownstone has the following fields in the cloud lib:
+* state: Float (0..1)
+* dimming_enabled: Bool (default = False)
+* name: String
+* unique_id: String
+* cloud_id: String
+* type: String
+* sw_version: String
 
 ### Users
 
@@ -173,16 +185,106 @@ A user can have 3 roles:
 * Member
 * Guest
 
-Each role has different privileges.<br>
-Users can have similar names. To view the info of a user's first name in a sphere:
-```python
-sphere = cloud.spheres.find('MySphere')
-users = sphere.users.find_by_first_name('MyUser')
-for username in users:
-    print(user.role)
-    print(user.last_name)
-    print(user.email)
+A User has the following fields in the cloud lib:
+* role: String
+* first_name: String
+* last_name: String
+* email: String
+* cloud_id: String
+* email_verified: Bool
+
+## Function list
+
+### Cloud
+
+#### initialize()
+> Login if no access token available, and sync all data for the user from the cloud.
+
+#### set_access_token(access_token: String)
+> Set an access token to skip the login part, if you already have one
+
+#### get_crownstone(crownstone_name: String) -> Crownstone
+> Get a Crownstone object by name, if it exists.
+
+#### get_crownstone_by_id(crownstone_id: String) -> Crownstone
+> Get a Crownstone object by it's id, it's it exists.
+
+### Spheres
+
+#### update()
+> Async function. Sync the Spheres with the cloud. Doing this will replace all current sphere data with that of the cloud.
+
+#### find(sphere_name: String) -> Sphere
+> Returns a sphere object if one exists by that name.
+
+#### find_by_id(sphere_id: String) -> Sphere
+> Return a sphere object if one exists by that id.
+
+### Sphere
+
+#### 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.
+
+#### find(crownstone_name: String) -> Crownstone
+> Return a Crownstone object if one exists by that name.
+
+#### find_by_id(crownstone_id: String) -> Crownstone
+> Return a Crownstone object if one exists by that id.
+
+### Crownstone
+
+#### 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 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 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.
+
+#### find(location_name: String) -> Location
+> Return a location object if one exists by that name.
+
+#### find_by_id(location_id: String) -> Location
+> Return a location object if one exists by that id.
+
+### 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.
+
+#### find_by_first_name(first_name: String) -> list
+> Returns a list of all users with that first name, as duplicate first names can exist.
+
+#### find_by_last_name(last_name: String) -> list
+> Return a list of all users with that last name, as duplicate last names can exist.
+
+#### find_by_id(user_id: String) -> Location
+> Return a location object if one exists by that id.
+
+## Async vs sync
+The lib can be used synchonously and asynchronously.<br>
+Async functions need to be awaited:
+```Python
+await cloud.spheres.update()
+```
+All the async functions mentioned above can also be used synchronously.<br>
+Simply type the same function name, but with underscore sync at the end. for example:
+```Python
+cloud.initialize_sync()
+cloud.spheres.update_sync()
 ```
+Make sure to see the examples above!
 
 ## Testing
 Tests coming soon!