Getting (Quickly) 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.
Most modern operating systems come with all the tools needed to immediately install the BrainStem python libraries and create python based applications. As such, simply download the latest development package, and then use pip to install the library.
#> cd <path to extracted download>/development/python
#> pip install brainstem-*.whl
If you see errors from these commands, check the requirements and details below.
Requirements¶
The brainstem python package is currently compatible with python 2.7 and python 3.6 through 3.10. When using 2.7 it is recommended that your python version be at least 2.7.9.
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;
libffi¶
The Brainstem python library relies on libffi, on macOS and Windows this is generally available via pip. 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-*.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