Install & Compatibility
Where this runs
tested against v2.12.4 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.000s · 92.9MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 2.5s · import 0.155s · 93MB
91MB installed
● package 91MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
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.
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.")
Debug
Known issues
gotchaThe `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.fixEnsure your Python environment is within the supported range. Consider using a virtual environment.
affects: All versions
breakingOn 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.fixInstall the necessary development packages for libffi and Python using your distribution's package manager before attempting `pip install brainstem`.
affects: All versions on Linux
gotchaMany 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.fixEnsure a compatible BrainStem module is physically connected and powered on before running code that attempts device interaction.
affects: All versions
gotchaOn 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.fixAlways use `pip3 install brainstem` for Python 3 environments on macOS and Linux.
affects: All versions on macOS/Linux
Errors
Common errors & fixes
Could not find a module.
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.
fixVerify 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'
The `brainstem` package is not installed in the active Python environment, or its installation failed due to missing dependencies.
fixInstall 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'
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.
fixImport the specific submodules required, for example, `import brainstem.stem` and `import brainstem.discover`.
Upgrade
Version history
2.12.4latest on PyPI · released May 26, 2026
Audit
Dependencies
libffirequiredRequired for the underlying C library interface. On Linux, `libffi-dev` or similar package might need manual installation.
setuptoolsrequiredA relatively up-to-date version is needed for installing platform-specific wheels.
python-devoptionalOn Linux, development headers (e.g., `python-dev` or `python3-dev`) may be required by the distro's package manager for successful installation.