Use the GoDice Python API to integrate GoDice functionality into your own Python applications
Supported features:
- Turn ON/OFF GoDice RGB LEDs
- 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.)
pip install godice
Package includes a demo script showing up API features. Command to run it:
python -m godice.demo
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.
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"
# 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(mac, godice.Shell.D6, timeout=30) 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())
