Adapt API for Python async environment

README.md

@@ -1,147 +1,87 @@
 
-# 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...)
-
- Dependencies Installation
-------------
-The GoDice Python API is dependent on the [Bleak](https://github.com/hbldh/bleak) library for Bluetooth (BLE) communication with the dice.
-
-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))
-
-Usage
-=====
-**See Main.py for more examples of usage**
+## Installation
 
-Discovering and connecting
-----
-To discover dice using GoDice library:
-```python
-from godice import *
+- once deployed to PyPI
 
-# 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])
+pip install godice
 ```
 
-Once you have the GoDice instance ready (e.g. myDie from the example above) you can call the following class functions:
-
-Messages
------------
-Activating LEDs:
-
-```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
-
-set_led(led1: list, led2: list)
+- meanwhile, to install a local copy
+1. Clone the repo
+2. cd into the root dir
+3. Install a local copy
 ```
-
-```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)
+pip install .
 ```
 
-Requests
------------
-(Instanced methods of GoDice object)
-```python
-# Sends request for color of die
-send_color_request()
-```
-
-
-```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)
+## Demo
 
-set_die_type(new_die_type)  
+Package includes a demo script showing up API features. Command to run it:
 ```
-
-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
-	.
-	.
-	.
+python -m godice.demo
 ```
 
-**Possible 'Results In Queue' (tuples)**
-
-("R" - On roll start, No value)
-
-("S" - Stable event, Value of die)
+It will discover GoDice devices nearby and connect to a closest one.
+Then it setups a dice color and starts listening to dice position changes, outputting a new number each time a dice is flipped.
 
-("TS" - Tilt stable event, Value of die)
+## Usage
 
-("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
+One can import and use the API from any custom Python script like below
+```
+import asyncio
+import bleak
+import godice
+
+
+async def main():
+    mac = "00:00:00:00:00:00"
+    client = bleak.BleakClient(mac, timeout=15)
+
+    # Python context manager (async with) is used for convenient connection handling
+    # Device stays connected during `async with` block execution and auto-disconnected on block finish
+    # Otherwise, dice.connect/dice.disconnect can be used instead 
+    async with godice.create(client, godice.Shell.D6) as dice:
+		print("Connected")
+        blue_rgb = (0, 0, 255)
+        yellow_rgb = (255, 255, 0)
+        off_rgb = (0, 0, 0)
+        await dice.set_led(blue_rgb, yellow_rgb)
+
+        color = await dice.get_color()
+        battery_lvl = await dice.get_battery_level()
+        print(f"Color: {color}")
+        print(f"Battery: {battery_lvl}")
+
+        print("Listening to position updates. Flip your dice")
+        await dice.subscribe_number_notification(notification_callback)
+        await asyncio.sleep(30)
+        await dice.set_led(off_rgb, off_rgb)
+
+
+async def notification_callback(number, stability_descr):
+    """
+    GoDice number notification callback.
+    Called each time GoDice is flipped, receiving flip event data:
+    :param number: a rolled number
+    :param stability_descr: an additional value clarifying device movement state, ie stable, rolling...
+    """
+    print(f"Number: {number}, stability descriptor: {stability_descr}")
+
+
+asyncio.run(main())
 ```