Acroname BrainStem Software Control Package

2.12.2 · active · verified Thu Apr 16

The `brainstem` Python package provides a robust interface for controlling and interacting with Acroname BrainStem hardware devices, such as programmable USB hubs and switches. Currently at version 2.12.2, the library enables Python applications to discover, connect to, and manage BrainStem modules. It is actively maintained with updates typically released alongside new BrainStem Development Kits, ensuring compatibility with various operating systems and Python versions.

Common errors

```
Could not find a module.
```
cause The BrainStem library's discovery methods failed to locate any connected BrainStem devices, or the specified transport type (e.g., USB, TCP/IP) was incorrect.

fix Verify that your BrainStem module is properly connected and powered on. Ensure you are calling the correct discovery function (e.g., `brainstem.discover.findAllModules(brainstem.link.Spec.USB)`) for your device's connection type.
```
ModuleNotFoundError: No module named 'brainstem'
```
cause The `brainstem` package is not installed in the active Python environment, or its installation failed due to missing dependencies.

fix Install the package using `pip install brainstem` (or `pip3 install brainstem` on macOS/Linux). On Linux, ensure `libffi-dev` and `python-dev` (or `python3-dev`) are installed system-wide.
```
AttributeError: module 'brainstem' has no attribute 'stem'
```
cause The `stem` (or `discover`, `link`, etc.) functionality is contained within submodules of `brainstem`, not directly exposed at the top level of the `brainstem` package without explicit import.

fix Import the specific submodules required, for example, `import brainstem.stem` and `import brainstem.discover`.

Warnings

gotcha The `brainstem` library is compatible with Python 2.7.9+ and Python 3.6 through 3.10. Using unsupported Python versions may lead to installation failures or runtime errors.
Fix: Ensure your Python environment is within the supported range. Consider using a virtual environment.
breaking On Linux, installation often requires `libffi-dev` and `python-dev` (or `python3-dev`) to be installed via the system's package manager (e.g., `sudo apt-get install libffi-dev python3-dev` on Debian/Ubuntu, `sudo yum install libffi-devel python-devel` on CentOS/RHEL). Failure to install these system dependencies will result in `pip` installation errors.
Fix: Install the necessary development packages for libffi and Python using your distribution's package manager before attempting `pip install brainstem`.
gotcha Many core functionalities and quickstart examples require a physical Acroname BrainStem module to be connected to the host computer (via USB or Ethernet). Without a connected device, module discovery and connection attempts will fail.
Fix: Ensure a compatible BrainStem module is physically connected and powered on before running code that attempts device interaction.
gotcha On macOS and Linux, `pip` typically refers to the Python 2 package installer, while `pip3` is used for Python 3. Incorrectly using `pip` instead of `pip3` can lead to the library being installed in the wrong Python environment or failing to install altogether.
Fix: Always use `pip3 install brainstem` for Python 3 environments on macOS and Linux.

Install

pip install brainstem Windows
pip3 install brainstem macOS / Linux

Imports

brainstem.discover
```
import brainstem.discover
```
Used for finding connected BrainStem modules.
brainstem.stem
```
import brainstem.stem
```
Contains classes for specific BrainStem module types (e.g., USBStem, EtherStem).
brainstem.link
```
import brainstem.link
```
Provides the `Spec` class for defining connection parameters to a module.
brainstem.defs
```
import brainstem.defs
```
Provides definitions and constants, such as module model information.

Quickstart

This quickstart code demonstrates how to discover an Acroname BrainStem USB module, connect to it, and then blink its user-programmable LED. This example requires a physical BrainStem USB module to be connected to your computer for successful execution. The code handles discovery, connection, a simple LED toggle loop, and proper disconnection.

import brainstem
import time

try:
    # Discover the first USB BrainStem module
    print("Discovering modules...")
    specs = brainstem.discover.findAllModules(brainstem.link.Spec.USB)
    if not specs:
        print("No BrainStem modules found. Please connect a device.")
        exit()
    
    # Connect to the first discovered USB module
    spec = specs[0]
    print(f"Found module: {str(spec)}")
    stem = brainstem.stem.USBStem()
    error = stem.connectFromSpec(spec)

    if error == brainstem.result.Result.NO_ERROR:
        print(f"Connected to {brainstem.defs.model_info(stem.system.getModel().value)}")
        print("Blinking user LED for 5 seconds...")
        for i in range(10):
            stem.system.setLED(i % 2) # Toggle LED (0 for off, 1 for on)
            time.sleep(0.5)
        stem.system.setLED(0) # Ensure LED is off at the end
        print("LED blinking complete.")
    else:
        print(f"Failed to connect to module: {error}")

except Exception as e:
    print(f"An error occurred: {e}")
finally:
    if 'stem' in locals() and stem.isConnected():
        stem.disconnect()
        print("Disconnected from BrainStem module.")

view raw JSON →