See https://github.com/playi/WonderPy/blob/master/README.md for the original documentation.

This is an unofficial port that reverse engineers the JSON to binary protocol.

See: https://www.robopenguins.com/reverse-dash/ for a blog post of my approach

See: ReversingDylib.md for reverse engineering notes.

For the supported commands and sensors, the interface should be exactly the same as with the original library.

I'm only testing on a Dash, so it's likely that some features will not work properly for other bots without some tweaking.

1. Python 3.9+
2. Familiarity with python and the command-line

See the original instructions for setting up a virtual environment if desired.

pip install -r requirements.txt
pip install .

You can use https://docs.astral.sh/uv/ with this library

uv sync

The original implementation ran the BLE handling in an event loop which needed any commands to be sent from separate threads. Since Bleak uses asyncio, I had a few options in how I want to handle scheduling the BLE actions.

Making the whole library async would probably be the most flexible option, but that adds a lot of complexity to the end user.

Instead I've decided to hide the async as an implementation detail. This does mean that blocking calls need to be run from a separate thread instead of being able to use an await. However, the user code can still be written in an async manner by making the sensor callbacks async.

• Sometimes the initial connection after Linux restarts fails. I'm not sure if this is a timeout or what. Retrying succeeds.
• Many of the commands and sensors haven't been implemented. Some of these are due to specific issues, but mostly these are due to a lack of time to reverse engineer them all. See the list below.

Commands

• pose ✅ Mostly working. Didn't implement some logic for resetting global origin. May have some issues with accumulating error around relative angle commands.
• RGB Lights ✅
• Speaker ❔ Same functionality as original library. This does not include uploading custom sounds
• Power ❔ Implemented, but didn't experiment with values
• Head Pan/Tilt ❔ Only implemented position commands
• Eye Ring Lights/Animation 🛑 Didn't attempt, but should be doable
• Launcher 🛑 Didn't attempt, but should be doable
• Low Level Wheel Control 🛑 Didn't attempt, but should be doable
• Robot Animation 🛑 Didn't attempt, but should be doable

Sensors

• Buttons ✅
• Head Pan/Tilt ✅
• Pose ✅ This includes the "watermark" to determine how many movement commands are queued
• Accelerometer ✅
• Gyro ✅
• Distance Sensors ❔ The raw values are captured, but the original library used the dylib to convert the values to distance in cm. Replaced with a very rough double exponential curve fit.
• Wheel Encoders ✅
• Picked Up ✅
• Bump Stall ✅
• Sound Playing ✅
• Animation Playing ✅
• Microphone ❔ I made an attempt at reversing this from the dylib. The amplitude and direction sort of worked, but not the confidence. Also, this value isn't actually surfaced in the API.
• Battery 🛑 Didn't attempt, is complicated by device specific variations
• Beacons 🛑 Didn't attempt, is complicated by device specific variations

The original Python library had many features that were referenced, but not fully implemented. Other features were reference in the dylib, but not the Python code. The remaining functionality could probably be found by spying on the BlueTooth traffic, but I'm not planning to look into that.