add a demo script

Author: anton-ptashnik

README.md

@@ -13,37 +13,46 @@ Use the GoDice Python API to integrate GoDice functionality into your own Python
 * Get notifications regarding the die state (Rolling or Stable and get the outcome number)
 * Use and configure different shells (D6, D20, D12 etc.)
 
+## Installation
 
-## Usage
+- once deployed to PyPI
 
 ```
-import asyncio
-import bleak
-import godice
+pip install godice
+```
 
+- meanwhile, to install a local copy
+1. Clone the repo
+2. cd into the root dir
+3. Install a local copy
+```
+pip install .
+```
 
-async def print_upd(stability_descr, number):
-    print(f"Stability descriptor: {stability_descr}, number: {number}")
+## Demo
 
+Package includes a demo script showing up API features. Command to run it:
+```
+python -m godice.demo
+```
 
-def filter_godice_devices(devices):
-    return [
-        dev for dev in devices if dev.name.startswith("GoDice")
-    ]
+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.
+
+## Usage
+
+One can import and use the API from any custom Python script like below
+```
+import asyncio
+import bleak
+import godice
 
 
 async def main():
-    print("Discovering GoDice devices...")
-    devices = await bleak.BleakScanner.discover(timeout=10)
-    devices = filter_godice_devices(devices)
-
-    print("Connecting to a dice...")
-    dev = devices[0]
-    client = bleak.BleakClient(dev, timeout=15)
-    
+    mac = "00:00:00:00:00:00"
+    client = bleak.BleakClient(mac, timeout=15)
     async with godice.create(client, godice.DiceType.D6) as dice:
-        print("Connected")
-
+		print("Connected")
         blue_rgb = (0, 0, 255)
         yellow_rgb = (255, 255, 0)
         off_rgb = (0, 0, 0)
@@ -54,27 +63,15 @@ async def main():
         print(f"Color: {color}")
         print(f"Battery: {battery_lvl}")
         
-        print("Listening to dice position updates. Flip your dice")
+        print("Listening to position updates. Flip your dice")
         await dice.subscribe_number_notification(print_upd)
         await asyncio.sleep(30)
         await dice.set_led(off_rgb, off_rgb)
 
 
-asyncio.run(main())
-```
-
-## Installation
-
-- once deployed to PyPI
+async def print_upd(stability_descr, number):
+    print(f"Stability descriptor: {stability_descr}, number: {number}")
 
-```
-pip install godice
-```
 
-- meanwhile, to install a local copy
-1. Clone the repo
-2. cd into the root dir
-3. Install a local copy
-```
-pip install .
+asyncio.run(main())
 ```

godice/__init__.py

@@ -1,3 +1,8 @@
+"""
+GoDice Python API
+"""
+__version__ = "0.0.1"
+
 from .factory import (
     create,
     DiceType

godice/demo.py

@@ -0,0 +1,64 @@
+import asyncio
+import bleak
+import godice
+
+
+async def main():
+    print("Discovering GoDice devices...")
+    discovery_res = await bleak.BleakScanner.discover(timeout=10, return_adv=True)
+    dev_advdata_tuples = discovery_res.values()
+    dev_advdata_tuples = filter_godice_devices(dev_advdata_tuples)
+
+    print("Discovered devices...")
+    print_device_info(dev_advdata_tuples)
+
+    print("Connecting to a closest device...")
+    dev, _adv_data = select_closest_device(dev_advdata_tuples)
+    client = bleak.BleakClient(dev, timeout=15)
+
+    async with godice.create(client, godice.DiceType.D6) as dice:
+        print(f"Connected to {dev.name}")
+
+        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(print_notification)
+        await asyncio.sleep(30)
+        await dice.set_led(off_rgb, off_rgb)
+
+
+async def print_notification(stability_descr, number):
+    print(f"Stability descriptor: {stability_descr}, number: {number}")
+
+
+def filter_godice_devices(dev_advdata_tuples):
+    return [
+        (dev, adv_data)
+        for dev, adv_data in dev_advdata_tuples
+        if dev.name.startswith("GoDice")
+    ]
+
+
+def select_closest_device(dev_advdata_tuples):
+    def _rssi_as_key(dev_advdata):
+        _, adv_data = dev_advdata
+        return adv_data.rssi
+
+    return max(dev_advdata_tuples, key=_rssi_as_key)
+
+
+def print_device_info(devices):
+    for dev, adv_data in devices:
+        print(f"Name: {dev.name}, address: {dev.address}, rssi: {adv_data.rssi}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())