adapt API for Python async env

Author: anton-ptashnik

README.md

@@ -1,147 +1,80 @@
 
-# GoDice Python API (with demo)
+# GoDice Python API
 
 ## Overview
 
 Use the GoDice Python API to integrate GoDice functionality into your own Python applications
 
-Here are some of the things that you can do with the GoDice Python API:
+**Supported features:**
 
 * Turn ON/OFF GoDice RGB LEDs
-* Ask for the die Color (dots color)
-* Ask for the die battery level
-* Get different notifications regarding the die state (Rolling or Stable and get the outcome number)
+* Read color (dots color)
+* Read battery level
+* Get notifications regarding the die state (Rolling or Stable and get the outcome number)
 * Use and configure different shells (D6, D20, D12 etc.)
 
-To run the demo (that uses the API) make sure you have the Bleak library installed and run main.py as following:
-``` console
-python main.py
-```
 
-Then enter the index of the GoDice you want to connect (or click Enter to connect to all available dice).
-Once connected you will start get notification from the connected dice (Rolling, Stable, etc...)
+## Usage
 
- Dependencies Installation
-------------
-The GoDice Python API is dependent on the [Bleak](https://github.com/hbldh/bleak) library for Bluetooth (BLE) communication with the dice.
+```
+import asyncio
+import bleak
+import godice
 
-You can install bleak by using this command:
 
-    $ pip install bleak
-   or from sources ([Bleak installation docs](https://bleak.readthedocs.io/en/latest/installation.html))
+async def print_upd(stability_descr, number):
+    print(f"Stability descriptor: {stability_descr}, number: {number}")
 
-Usage
-=====
-**See Main.py for more examples of usage**
 
-Discovering and connecting
-----
-To discover dice using GoDice library:
-```python
-from godice import *
+def filter_godice_devices(devices):
+    return [
+        dev for dev in devices if dev.name.startswith("GoDice")
+    ]
 
-# Example how to discover GoDice Bluetooth devices  
-def main():  
-  
-	# Discovering GoDice devices using BLE  
-	dice_devices = discover_dice()
-```
 
-Connecting to a die and creating a die object (use "create_dice" and pass it a die device):
-```python
-myDie = create_dice(dice_devices[0])
-```
+async def main():
+    print("Discovering GoDice devices...")
+    devices = await bleak.BleakScanner.discover(timeout=10)
+    devices = filter_godice_devices(devices)
 
-Once you have the GoDice instance ready (e.g. myDie from the example above) you can call the following class functions:
+    print("Connecting to a dice...")
+    dev = devices[0]
+    client = bleak.BleakClient(dev, timeout=15)
+    
+    async with godice.create(client, godice.DiceType.D6) as dice:
+        print("Connected")
 
-Messages
------------
-Activating LEDs:
+        blue_rgb = (0, 0, 255)
+        yellow_rgb = (255, 255, 0)
+        off_rgb = (0, 0, 0)
+        await dice.set_led(blue_rgb, yellow_rgb)
 
-```python
-# Turn On/Off RGB LEDs, will turn off if led1 and led2 are None
-# led1 - a list to control the 1st LED in the following format '[R, G, B]'
-#        where R, G, and B are numbers in the range of 0-255
-# led2 - same as led1 for the second led
+        color = await dice.get_color()
+        battery_lvl = await dice.get_battery_level()
+        print(f"Color: {color}")
+        print(f"Battery: {battery_lvl}")
+        
+        print("Listening to dice position updates. Flip your dice")
+        await dice.subscribe_number_notification(print_upd)
+        await asyncio.sleep(30)
+        await dice.set_led(off_rgb, off_rgb)
 
-set_led(led1: list, led2: list)
-```
 
-```python
-# Pulses the die's leds for set time
-# pulse_count - How many pulses
-# on_time - How much time to spend on (units of 10 ms)
-# off_time - How much time to spend off (units of 10 ms)
-# rgb - List of RGB values to set die to pulse to
-
-pulse_led(pulse_count, on_time, off_time, rgb)
-```
-
-Requests
------------
-(Instanced methods of GoDice object)
-```python
-# Sends request for color of die
-send_color_request()
+asyncio.run(main())
 ```
 
+## Installation
 
-```python
-# Changes die type (shell)
-# new_die_type - DieType Enum:
-#	D6 = 0 (default)
-#	D20 = 1,
-#	D10 = 2,
-#	D10x = 3,
-#	D4 = 4,
-#	D8 = 5,
-#	D12 = 6
-# For example: set_die_type(DieType.D20)
+- once deployed to PyPI
 
-set_die_type(new_die_type)  
 ```
-
-Reading responses
------------
-Each die object has a "result_queue" attribute.
-Whenever a response/message is sent to the die, it's response code (if it has one) and it's value placed in the result queue as a tuple.
-
-Example for iterating through the queue:
-```python
-while not die_object.result_queue.empty():
-
-	current_result = die_object.result_queue.get()
-	
-	result_code = current_result[0]
-	if result_code == "S":
-		value = current_result[1]
-		# Do something
-	.
-	.
-	.
+pip install godice
 ```
 
-**Possible 'Results In Queue' (tuples)**
-
-("R" - On roll start, No value)
-
-("S" - Stable event, Value of die)
-
-("TS" - Tilt stable event, Value of die)
-
-("MS" - Move stable event, Value of die)
-
-("FS" - Fake stable event, Value of die)
-
-("B" - Battery response, Battery charge percent: 0-100)
-
-("C" - Color response, ID of color of die: 0-5)
-
-```python
-# Black		0
-# Red		1
-# Green		2
-# Blue		3
-# Yellow	4
-# Orange	5
+- meanwhile, to install a local copy
+1. Clone the repo
+2. cd into the root dir
+3. Install a local copy
+```
+pip install .
 ```