242 lines
6.6 KiB
Markdown
Executable File
242 lines
6.6 KiB
Markdown
Executable File
# BrainStem Python Library
|
|
|
|
The BrainStem python package gives access to simple python commands
|
|
to control and interact with a collection of BrainStem devices
|
|
|
|
# Features
|
|
|
|
- Easily interact with BrainStem devices using python
|
|
- Learn more about the capabilities of BrainStem devices in [Acroname's reference documentation](https://acroname.com/reference/)
|
|
|
|
# Download
|
|
|
|
- As of version 2.9.21, the BrainStem Python library is available on [PyPI](https://pypi.org/project/brainstem)
|
|
- It is also available from the BrainStem Development Kit at [Acroname's downloads page](https://acroname.com/software/brainstem-development-kit)
|
|
- Download the operating system specific BrainStem Development Kit
|
|
- Once downloaded and contents extracted, inside the extracted folder, navigate to:
|
|
- `[project_root]/development/python` to find the latest version of the `brainstem-*.whl`
|
|
|
|
# Installation
|
|
|
|
On Windows, to install a new version of BrainStem (or update an existing one), simply execute:
|
|
|
|
```bash
|
|
$> pip install --user brainstem --upgrade
|
|
```
|
|
|
|
Or from wheel file:
|
|
|
|
```bash
|
|
$> pip install --user brainstem-*.whl --upgrade
|
|
```
|
|
|
|
On MacOS and Linux, pip is for the older Python 2 version, pip3 must be executed instead:
|
|
```bash
|
|
$ pip3 install --user brainstem --upgrade
|
|
```
|
|
|
|
Or from wheel file:
|
|
|
|
```bash
|
|
$ pip3 install --user brainstem-*.whl --upgrade
|
|
```
|
|
|
|
To uninstall the library, the easiest way is with pip:
|
|
|
|
Windows:
|
|
|
|
```bash
|
|
$> pip uninstall brainstem
|
|
```
|
|
|
|
MacOS and Linux:
|
|
|
|
```bash
|
|
$> pip3 uninstall brainstem
|
|
```
|
|
|
|
# Troubleshooting
|
|
|
|
- Some additional requirements for installing python wheels in general and the BrainStem wheel specifically may be needed
|
|
- If any errors are encountered installing or running the BrainStem python package, see the `Additional Requirements` section near the bottom of this document
|
|
|
|
# A Tour of the Python Example
|
|
|
|
After navigating to `[project_root]/development/python_examples`, choose the folder that corresponds with the product being used.
|
|
For example, the most common product sold is Acroname's 8-port hub, so the folder needed in this case will be `usbhub3p_example`.
|
|
|
|
To run the example, execute:
|
|
|
|
```bash
|
|
$> python usbhub3p_example.py
|
|
```
|
|
|
|
for your specific BrainStem device.
|
|
|
|
The example requires that a USB BrainStem link module be connected to the host computer.
|
|
If the following message is seen, there is likely no module connected or the incorrect example program was run:
|
|
|
|
```
|
|
'Could not find a module.'
|
|
```
|
|
|
|
Once the example starts running, it will print out some basic information about
|
|
the module and then blink the user LED on the module.
|
|
|
|
# Working with BrainStem from the Interpreter
|
|
|
|
The following is a brief introduction to writing a python program that talks to a connected BrainStem:
|
|
|
|
Start up the python interpreter:
|
|
|
|
```bash
|
|
$> python
|
|
```
|
|
|
|
The first step is to import the BrainStem package:
|
|
|
|
```python
|
|
>>> import brainstem
|
|
```
|
|
|
|
- `stem` and `discover` are the two primary modules
|
|
- `stem` contains classes for each of the distinct module types:
|
|
|
|
* USBStem
|
|
* EtherStem
|
|
* MTMIOSerial
|
|
* MTMPM1
|
|
* MTMEtherStem
|
|
* MTMUSBStem
|
|
* USBHub2x4
|
|
* MTMRelay
|
|
* USBHub3p
|
|
* MTMDAQ1
|
|
* USBCSwitch
|
|
* USBCSwitchPro
|
|
* MTMDAQ2
|
|
* MTMLoad1
|
|
* USBHub3c
|
|
|
|
Next search for all connected modules:
|
|
|
|
```python
|
|
>>> specs = brainstem.discover.findAllModules(brainstem.link.Spec.USB)
|
|
>>> print [str(s) for s in specs]
|
|
```
|
|
|
|
Then search for the first USB module:
|
|
|
|
```python
|
|
>>> spec = brainstem.discover.findFirstModule(brainstem.link.Spec.USB)
|
|
>>> print spec
|
|
```
|
|
|
|
If a USB module is found, create a USBStem object and connect to it using
|
|
the spec object that was returned by discover:
|
|
|
|
```python
|
|
>>> stem = brainstem.stem.USBStem()
|
|
>>> stem.connectFromSpec(spec)
|
|
```
|
|
|
|
Then get some information about the module:
|
|
|
|
```python
|
|
>>> result = stem.system.getModel()
|
|
>>> print brainstem.defs.model_info(result.value)
|
|
```
|
|
|
|
Finally, flash the user LED, on or off every 100ms.
|
|
|
|
```python
|
|
>>> from time import sleep
|
|
>>> for i in range(0,51):
|
|
... err = stem.system.setLED(i % 2)
|
|
... if err != brainstem.result.Result.NO_ERROR:
|
|
... break
|
|
... sleep(0.1)
|
|
...
|
|
>>>
|
|
```
|
|
|
|
That's it! Once this basic example is running, a good place to go is the
|
|
documentation to learn about all the other features available.
|
|
|
|
At the prompt type the following:
|
|
|
|
```python
|
|
>>> help(stem.system)
|
|
# or
|
|
>>> help(brainstem.stem)
|
|
```
|
|
|
|
***
|
|
|
|
# Additional Requirements
|
|
|
|
## python
|
|
|
|
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.
|
|
|
|
MS Windows generally does not include Python, and a suitable Python package will need to be [downloaded and installed](https://www.python.org/downloads/) before proceeding with the following guide.
|
|
The BrainStem wheel is compatible with both 32 and 64bit python packages.
|
|
Python version >= 2.7.9 is recommended.
|
|
|
|
MacOS X and most Linux distributions generally include a Python installation.
|
|
However, the installation may not include pip and setuptools which are required to install the BrainStem Python module.
|
|
|
|
## pip
|
|
|
|
The BrainStem python package is installed via a platform specific wheel.
|
|
To install these wheels, a relatively up to date version of pip and setuptools is needed.
|
|
Pip can be installed by following the instructions at:
|
|
|
|
https://pip.pypa.io/en/latest/installing.html
|
|
|
|
If pip is installed it may still be helpful to update pip.
|
|
Administrator privileges may be required on MacOS and Linux.
|
|
Instructions for updating pip can be found at:
|
|
|
|
https://pip.pypa.io/en/latest/installing.html#upgrade-pip
|
|
|
|
|
|
## libffi
|
|
|
|
The BrainStem python library relies on libffi.
|
|
On MacOS X and Windows, this is generally available.
|
|
Linux users may need to install libffi via the distro's package manager.
|
|
The package is generally named libffi-dev or similar.
|
|
|
|
## Python development headers
|
|
|
|
Linux users may need to install the development package for python
|
|
via the distro's package manager before the brainstem wheel can be installed.
|
|
The package is generally named python-dev or similar.
|
|
|
|
## CentOS package manager
|
|
|
|
On CentOS and yum based distros the following command will install the required packages:
|
|
|
|
```bash
|
|
$> sudo yum install libffi-devel python-devel
|
|
```
|
|
|
|
***
|
|
|
|
# License
|
|
|
|
Licensed under Proprietary License, see full license text here [full license text here](https://acroname.com/software-license).
|
|
|
|
# Support
|
|
|
|
If these troubleshooting steps don't solve the issue, please let us know.
|
|
We have a mailing list located at: support@acroname.com
|
|
and a [support page](https://acroname.com/contact-us) to get in touch with Acroname support staff.
|
|
|
|
Enjoy!
|
|
|
|
The Acroname Team.
|