Control MOSS Double Brain using Python
DISCLAIMER: The author and the repository contents are not associated in any way with Modular Robotics. The code presented here is not based on any official documentation and using it may or may not damage your device. Use it at your own risk.
MOSS is a great robotics kit by Modular Robotics, it features a bluetooth communications module called Double Brain. The module can be controlled using mobile apps, and also by using the Scratch programming language. This repository provides an API in Python for controlling the brain module.
Setting up bluetooth can be tricky, at a minimum, the brain device needs to be paired with a bluetooth enabled computer. The operating system needs to support Python and the Python BlueZ bindings, or the Python LightBlue module (which is available for Mac OS X, where PyBlueZ isn't available).
The code was developed and tested on an Asus 1000he EeePC running Ubuntu 14.04. It was also tested on a Raspberry Pi with a bluetooth dongle running Raspbian.
It is probably best to start by following the information in the links in the Introduction section above and setup the mobile apps and/or the Scratch environment, then connect to the device and communicate with it. Doing so, will help in gaining familiarity with the setup, the device and its capabilities and provide an opportunity to troubleshoot possible issues in a more "friendly" environment.
The musci.py
script contains inline documentation for the API that it
exposes (try running import musci; help(musci)
and also read the code).
The API allows connecting to (and scanning for, if needed) the brain
bluetooth device, and then sending commands to the device to set and get
parameters, such as face input/output state, value and LED color.
The Brain
class is used in a with
statement to instantiate an object.
This will optionally scan for, and connect to the device. This instance
object is then used as a function (callable) to issue commands to the
device, the return value of the function call is that output data from the
command.
import musci
with musci.Brain() as brain:
brain('setLEDState', 255, 0, 0)
r, g, b = brain('getLEDState')
...
For now, only the following commands were tested:
-
getAllFaceStates
:Input: empty
Output: STATE-1, VALUE-1, STATE-2, VALUE-2, ..., STATE-8, VALUE-8
-
setAllFaceStates
:Input: STATE-1, STATE-2, ..., STATE-8
Output: VALUE-1, VALUE-2, ..., VALUE-8
-
setFaceState
:Input: ZERO-BASED-INDEX, STATE
Output: ZERO-BASED-INDEX, VALUE
-
getAllFaceValues
:Input: empty
Output: VALUE-1, VALUE-2, ..., VALUE-8
-
getFaceValue
:Input: ZERO-BASED-INDEX
Output: ZERO-BASED-INDEX, VALUE
-
setManyFaceValues
:Input: INDEX-MASK, FIRST-VALUE, SECOND-VALUE, ..., LAST-VALUE
Output: empty
-
setFaceValue
:Input: ZERO-BASED-INDEX, VALUE
Output: empty
-
getLEDState
:Input: empty
Output: RED-VALUE, GREEN-VALUE, BLUE-VALUE
-
setLEDState
:Input: RED-VALUE, GREEN-VALUE, BLUE-VALUE
Output: empty
Scanning and connecting can take some time (>10 seconds), it can be
shortened if the device address is provided when the Brain
object is
initialized, but it still takes a few seconds to connect.
The API is implemented with synchronous I/O, a command call will block until the result of the command is available. When the bluetooth connection is weak the command call would just appear to be stuck - this can be confusing.
When musci.py
is run as a script it will function as a "server" that
listens for commands on stdin
, runs them on the device and writes the
output to stdout
. This can be used to interface with the device from the
shell. If -d
is used (as in ./musci.py -d
), a lot of debugging messages
will be printed, with (among other things) the address of the device that can
be used to connect more quickly if it is specified with -a ADDRESS
.
There are two example scripts: led.py
and rover.py
. Like musci.py
,
they can be launched with -a ADDRESS
to speed up the connection setup
time, and with -d
to generate (lots of) debug messages. The scripts run
forever and are supposed to be stopped by CTRL-C. The scripts are each
intended to control a specific robot with a bluetooth brain that has
specific faces connected to the proximity sensor and (for rover.py
) the
wheels.
-
led.py
: control a simple distance measuring device made from the battery block, the double brain block, and the proximity sensor (connected to face #7 in the brain block). The script will periodically read the output of the proximity sensor and will set the LED color according to the measured proximity value. -
rover.py
: control an obstacle evading "rover" built with two parallel wheels (connected to faces #1 and #8) and the proximity sensor (connected to face #7). The script will instruct the rover to move the wheels forward for a period of time, then read the proximity sensor value, then if there is an object in front of the proximity sensor, the script will move the wheels backward for a period of time, then turn for a period of time, then try again to move forward.
MOSS is a trademark of Modular Robotics, and Musci is the Latin word for Mosses (the plants).