Getting Started

The BrainStem python package allows you to interact with a collection of BrainStem modules from python. The API is similar to both the C++ and Reflex API’s, with a few significant differences. The remainder of this section details the structure and functionality of the python API.

Requirements

The brainstem python package is currently compatible with python 2.7 and python 3.6. When using 2.7 it is recommended that your python version be at least 2.7.9. Windows is currently only supported to MS Windows 7, and only supported for the 32bit version of python.

pip

The brainstem python package is installed via a platform specific wheel. To install these wheels you need a relatively up to date version of pip and setuptools. If you don’t have pip installed you can install it by following the instructions at;

https://pip.pypa.io/en/latest/installing.html

If you do have pip installed it may be helpful to update pip. To do so run the following command from your command line. You may need to have administrator privileges on MacOS and Linux. Instructions for updating pip can be found at;

https://pip.pypa.io/en/latest/installing/#upgrade-pip

libffi

The Brainstem python library relies on libffi, on Mac OS and Windows this is generally available, on linux you may need to install libffi via your distro’s package manager.

Python development headers

Also on linux, you may need to install the development package for python via your distro’s package manager before you can install.

CentOS package manager

On CentOS and yum based distros the following command will install the required packages.

$> sudo yum install libffi-devel python-devel

Installation

Install the python package.

Note:

‘#>’
indicates that the command must be run with admin privileges on MacOS and Linux, either via sudo or su.
#> pip install brainstem-2.3.0-py2-none-any.whl

If you need to uninstall the library, the easiest way to do so is with pip.

$> pip uninstall brainstem

A Tour of the Python Example

To run the example, go to Development/python in the “BrainStem2 Development Kit” package and type:

$> python brainstem_example.py

The example requires that you have a USB BrainStem link module connected to your host computer. If you see the following message, you probably don’t have a module connected:

Creating USB stem and connecting to first module found
Could not find a module.

Once the example starts running, it will connect to the first USBStem it finds connected to your computer and then blink the user LED on the module.

$> python brainstem_example.py
Creating USB stem and connecting to first module found
Connecting to Module with serial number: 0x40F5849A
Flashing the user LED

The following is a brief introduction interacting with the brainstem via the python interactive interpreter. The first step is to import some modules that we’ll need later. There are multiple ways to import the brainstem package. For this example we will use the simplest method.

>>> import brainstem

See the Package Structure <package> section of the python reference for more information about the brainstem package, and the modules it includes.

Next we discover a USBStem module, and connect to it.

>>> spec = brainstem.discover.findFirstModule(brainstem.link.Spec.USB)
>>> print spec
LinkType: USB(serial: 0x40F5849A, module: 0)
>>> stem = brainstem.stem.USBStem()
>>> stem.connect(0x40F5849A)

Information about specific modules can be found in the Modules <Modules> section.

Now that we have created a USBStem, we can turn on the user LED using the system entity:

>>> stem.system.setLED(1)

Finally lets blink the LED in a loop.

>>> from time import sleep
>>> for i in range(0,100):
...     err = stem.system.setLED(i % 2)
...     if err != 0:
...         print "error %d"% err
...         break
...     sleep(0.5)
...
>>>

As you can see the call to setLED returns an error value. In this case that is an error value, that will be 0 on success and some other number if there is an error. The brainstem library generally avoids raising exceptions, and instead passes information via result objects, or result error codes. More information about these errors, and the result object can be found in the Result <result> section of the python reference

Help is available from within the python interpreter, calling help() on a stem or other object will yield context specific documentation.

>>> import brainstem
>>> help(brainstem.stem.USBStem)
Help on class USBStem in module brainstem.stem:

class USBStem(brainstem.module.Module)
|  Concrete Module implementation for 40Pin and MTM USBStem modules
|
|  USBStem modules contain Analogs, Digital IO's, and I2C entities
|  in addition to the system entity.
|
|  Method resolution order:
|      USBStem
...

Enjoy!

The Acroname Team.

Support

If you are having issues, please let us know. We have a mailing list located at: support@acroname.com