WonderPy is a Python package providing an interface to the WonderWorkshop robots Dash, Dot, and Cue. It has fine-grained realtime access to all the robot's commands and sensors. There is a companion repository with tutorials and examples.
To get the most out of WonderPy, you should already have a beginner-level comfort with python and the command-line.
WonderPy is current at an "Alpha" release. It's ready to be tried out by folks who are willing to live with a few more rough-edges than one would want, and ideally who can provide constructive criticism.
Please see the "Issues" in github for an up-to-date list of known bugs and to-do items.
- Command Categories:
- eyering
- head
- media
- monoLED
- body
- RGB
- accessory
- Sensor Categories:
- accelerometer / gyroscope
- beacon
- buttons
- distance
- head angles
- pose
- speaker
- wheels
- MacOS
- Python 2.7
- Familiarity with python and the command-line
All of these are required.
-
pip
pipis the standard package manager for python. It's used to install packages such as WonderPy and AdaFruit BLE, below.
It can be tempting to skip installing this, but unfortunately it is required.
Installing pip tends to vary significantly from system to system, so we can't provide specific instructions it. The best we can do is refer you to google to find the best match for your situation. Here's Google on the topic. -
VirtualEnv
VirtualEnv is a system which enables you to be sure which version of Python you're running for WonderPy, and which packages are present.
pip install virtualenv
Depending on how you installed pip, you may need to
sudo pip install virtualenv
- XCode Command Line Tools
xcode-select --install
You may need to install XCode, visit the Apple Developer site and search for "Command Line Tools". Then download and install the appropriate file based on your version of macOS and XCode.
Some users may need to uninstall/reinstall Python 2.x afterwards, depending on their setup. (Since there are many ways python is installed, we don't provide instructions for that here)
- AdaFruit Python BTLE Package
The AdaFruit BTLE package is not hosted on PyPi, which makes it difficult to automatically install when this package is installed via pip. Additionally, this project requires a fork of that project by WonderWorkshop, which as of this writing has not been merged back into the main project.
pip install git+git://github.com/playi/Adafruit_Python_BluefruitLE@928669a#egg=Adafruit_BluefruitLE
virtualenv --python=/usr/bin/python2.7 --no-site-packages venvsource venv/bin/activate
pip install WonderPy
Documentation is still also in Alpha stage.
The steps above install the core library.
There are many examples of using it separately in the github repository playi/WonderPyExamples.
It is highly recommended to look at those examples.
To test basic functionality, run these at the command-line, inside your fresh virtualenv:
download the "01_hello_world.py" tutorial example:
curl -o 01_hello_world.py https://raw.githubusercontent.com/playi/WonderPyExamples/master/tutorial/01_hello_world.py
run it:
python 01_hello_world.py
It should connect to any nearby robot and say hello !
Upon launching any of the examples, the app will scan for robots for at least 5 and at most 20 seconds. After scanning, whichever robot had the highest signal strength (RSSI) will be connected to. This is a reasonable approximation of connecting to the closest robot.
[--connect-type cue | dot | dash]
filter for robots of the specified type/s
[--connect-name MY_ROBOT | MY_OTHER_ROBOT | ...]
filter for robots with the specified name/s
[--connect-eager]
connect as soon as a qualified robot is discovered.
do not wait the full scanning period.
if there are more than one robot with matching criteria,
the one with the best signal is still selected
[--connect-ask]
show a list of available robots, and interactively ask for input.
indicates which has the highest signal strength.
-
Spend 5 seconds looking for all Cue and Dash robots which are named either "sammy" or "sally", and connect to the one with the best signal strength:
python demos/roboFun.py --connect-type cue dash --connect-name sammy blippy sally -
Connect ASAP to any robot named 'orions robot', no matter what type of robot it is.
python demos/roboFun.py --connect-eager --connect-name "orions robot"
Please see the "Issues" in github for an up-to-date list of known bugs and to-do items.
As of this writing, the open issues are:
- Only works with a single robot.
- Only works with Python2.7.
The limiting factor here is getting the AdaFruit BTLE package to run under Python3. There's evidence this is possible. - Once under Python3, update the concurrency model.
- Flesh-out inline documentation.
- Make the pip installation more standard. Currently this requires a manual install of a github-based fork of the AdaFruit package.
- Port to Windows, Linux
How is WonderPy working for you ? We're eager to hear.
Please take time to fill out a survey!
Pull requests are welcome!
Please check the list of issues and todo's at the WonderPy repository on github.
Additional examples in the WonderPyExamples repository would also be great:
- Integrations with other cool packages
- IoT integrations
- Demos with the Sketch Kit accessory
Feature requests for the API should be sent as new Issues in github.
If there's a specific bug or problem with the API, please check the outstanding issues in github and if it's not already covered, create a new one.
If you have a more general question such as "how would I approach doing .." or you have a tip you'd like to share, please visit stackoverflow and be sure to tag your post with wonderworkshop.
Feature requests for the API should be sent as new Issues in github.
Made something cool ? We'd love to see it !
Send your photos, videos, and links to [email protected] .
( Note, we can't promise a reply to all emails )