Metadata-Version: 2.1
Name: brainstem
Version: 2.12.2
Summary: Acroname BrainStem Software Control Package
Home-page: http://www.acroname.com
Author: Acroname Inc.
Author-email: support@acroname.com
License: # Brainstem SDK Software Package License Agreement:
        
        PLEASE READ THIS SOFTWARE LICENSE AGREEMENT CAREFULLY BEFORE DOWNLOADING OR USING THE SOFTWARE.
        
        BY USING THE SOFTWARE, OR USING EQUIPMENT THAT CONTAINS THE SOFTWARE, YOU ARE CONSENTING TO BE BOUND
        BY THIS AGREEMENT. IF YOU DO NOT AGREE TO ALL OF THE TERMS OF THIS AGREEMENT, DO NOT USE THE SOFTWARE
        AND DESTROY ALL COPIES IN YOUR POSSESSION.
        
        ## HUBTOOL, STEMTOOL, CONTROLROOM, BRAINSTEM2 LIBRARY SHARED OBJECT, STATIC ARCHIVE, AND LIBRARY HEADERS
        SOFTWARE LICENSE AGREEMENT Copyright (c) 1994-2024 Acroname Inc.
        
        License Grant: Acroname Inc. ("Acroname") and its authorized agents grant to customer ("Customer") a
        revocable, nonexclusive, and nontransferable license to use the BrainStem2 shared object (.dylib,
        .framework, .so, .dll, etc) static archive (.a), and associated library header files ("Software") in
        object code form solely for Customers internal business purposes. Acroname may modify the Software
        for any reason, without notice and without liability to Customer to comply with applicable law or to
        otherwise protect Acroname or its affiliates, business partners, licensors, and/or customers from
        potential legal liability. The Software is licensed to Customer, not sold. Except for the limited
        license granted above, Acroname and its licensors retain all right, title and interest in the Software
        and its documentation, including copyrights, patents, trademarks and trade secret rights. Customer
        agrees that aspects of the Software, including the specific design and structure of individual
        programs, constitute trade secrets and/or copyrighted material of Acroname.
        
        RESTRICTIONS:
        
        CUSTOMER SHALL NOT: MODIFY THE SOFTWARE; REVERSE ENGINEER OR REVERSE COMPILE OR REVERSE ASSEMBLE ALL
        OR ANY PORTION OF THE SOFTWARE, OR OTHERWISE ATTEMPT TO DERIVE THE TRADE SECRETS EMBODIED IN THE
        SOFTWARE.
        Customer agrees that redistributions of this Software must retain the above copyright notice, this
        list of conditions and the following disclaimer.
        Customer may not copy [or distribute] the Software except to the extent that copying is necessary to
        use the Software for purposes set forth herein.
        Customer may not assign, sublicense, rent, timeshare, loan, lease, [or otherwise provide or transfer]
        the Software, or directly or indirectly permit any third party to use or copy the Software without
        written permission from Acroname.
        Limited Warranty; Disclaimer: THE SOFTWARE IS PROVIDED ON AN AS AVAILABLE,AS IS BASIS WITH ALL
        FAULTS, AND WITHOUT WARRANTY OF ANY KIND. EXCEPT AS SPECIFIED IN THIS AGREEMENT, ALL EXPRESS OR
        IMPLIED CONDITIONS, REPRESENTATIONS, AND WARRANTIES INCLUDING, WITHOUT LIMITATION, ANY IMPLIED
        WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NONINFRINGEMENT OR ARISING FROM A
        COURSE OF DEALING, USAGE, OR TRADE PRACTICE, WITH RESPECT TO THE SOFTWARE ARE HEREBY EXCLUDED TO THE
        EXTENT ALLOWED BY APPLICABLE LAW. ACRONAME DOES NOT WARRANT THAT THE SOFTWARE WILL MEET CUSTOMERS
        REQUIREMENTS, OR THAT THE SOFTWARE IS COMPATIBLE WITH ANY PARTICULAR HARDWARE OR SOFTWARE, OR THAT THE
        SOFTWARE WILL CONTAIN ANY PARTICULAR FEATURES OR FUNCTIONALITY, OR THAT THE OPERATION OF THE SOFTWARE
        WILL BE UNINTERRUPTED OR ERROR-FREE, OR THAT DEFECTS IN THE SOFTWARE WILL BE CORRECTED. THIS SOFTWARE
        IS NOT INTENDED FOR USE IN LIFE SUPPORT SYSTEMS. Acroname shall not be liable for failures caused by
        third party components and/or third party hardware that is integrated with the Software (including
        Customers own systems), misuse of the Software, or Customers negligence or willful misconduct. In no
        event shall Acroname's [or its suppliers'] liability to Customer, whether in contract, tort (including
        negligence), or otherwise, exceed the price paid by Customer. Some jurisdictions may not allow
        limitation or exclusion of liability for consequential or incidental damages.
        
        Indemnities: Acroname will indemnify, defend, and hold Customer harmless from any claim, demand,
        action, proceeding, investigation, judgment, loss, damage, fine, liability, cost, or expense,
        including attorneys fees, experts fees, and court costs, arising out of a claim by a third-party
        that Customers use of the Software in conformance with the terms of this Agreement infringes a
        United States patent, copyright, or trade secret of that third party. The foregoing indemnification
        obligation of Acroname is contingent upon Customers promptly notifying Acroname in writing of such
        claim, permitting Acroname sole authority to control the defense or settlement of such claim, and
        providing Acroname reasonable assistance in connection therewith. If a claim of infringement under
        this Section occurs, or if Acroname determines a claim is likely to occur, Acroname will have the
        right, in its sole discretion, to either: (i) procure for Customer the right or license to continue
        to use the Software free of the infringement claim; or (ii) modify the Software to make it
        non-infringing, without loss of material functionality. If either of these remedies is not reasonably
        available to Acroname, Acroname may, in its sole discretion, immediately terminate this Agreement.
        Notwithstanding the foregoing, Acroname shall have no obligation with respect to any claim of
        infringement that is based upon or arises out of: (i) the use or combination of the Software with any
        third party hardware, products, data or other materials, including Customers own systems and data;
        (ii) modification or alteration of the Software by anyone other than Acroname; (iii) Customers use
        of the Software in excess of the rights granted in this Agreement; (iv) any third party components;
        (v) specifications provided by Customer, (vi) a business method or process that is inherent to
        Customers business, or (vii) gross negligence, willful misconduct, or violation of law by Customer
        (collectively, the Excluded Claims). The provisions of this Section state the sole and exclusive
        obligations and liability of Acroname and its Acronames suppliers for any claim of intellectual
        property infringement arising out of or relating to the Software and/or this Agreement and are in
        lieu of any implied warranties of non-infringement, all of which are expressly disclaimed. Customer
        will indemnify, defend, and hold Acroname harmless from any claim, demand, action, proceeding,
        investigation, judgment, loss, damage, fine, liability, cost, or expense, including attorneys fees,
        experts fees, and court costs, from a third-party claim arising out of an Excluded Claim. Customers
        indemnification obligation is contingent upon Acroname promptly notifying Customer in writing of such
        claim, permitting Customer sole authority to control the defense or settlement of such claim, and
        providing Customer reasonable assistance in connection therewith.
        
        Limitation of Liability: TO THE MAXIMUM EXTENT PERMITTED BY LAW, IN NO EVENT SHALL ACRONAME OR ITS
        SUPPLIERS AND VENDORS BE LIABLE TO CUSTOMER OR ANY THIRD PARTY FOR ANY SPECIAL, INCIDENTAL,
        CONSEQUENTIAL, PUNITIVE, EXEMPLARY, SPECIAL, OR INDIRECT DAMAGES, WHICH SHALL INCLUDE, WITHOUT
        LIMITATION, DAMAGES FOR PERSONAL INJURY, LOST PROFITS, LOST DATA AND BUSINESS INTERRUPTION, ARISING
        OUT OF THE USE OR INABILITY TO USE THE SOFTWARE, EVEN IF ACRONAME HAS BEEN ADVISED OF THE POSSIBILITY
        OF SUCH DAMAGES. IN ANY CASE, THE ENTIRE LIABILITY OF ACRONAME AND ITS SUPPLIERS AND VENDORS UNDER
        THIS AGREEMENT FOR ALL DAMAGES, LOSSES, AND CAUSES OF ACTION (WHETHER IN CONTRACT, TORT (INCLUDING
        NEGLIGENCE), OR OTHERWISE) SHALL BE LIMITED TO THE GREATER OF $500.00 AND FEES PAID BY CUSTOMER, IF
        ANY, DURING THE TWELVE MONTHS IMMEDIATELY PRECEDING THE FIRST EVENT GIVING RISE TO LIABILITY.
        
        Term and Termination: This Agreement is effective until terminated. Customer may terminate this
        Agreement at any time by destroying all copies of the Software including any documentation. This
        Agreement will terminate immediately without notice from Acroname if Customer fails to comply with
        any provision of this Agreement. Upon termination, Customer must destroy all copies of the Software
        including any documentation.
        
        Export: This Software, including technical data, is subject to U.S. export control laws, including
        the U.S. Export Administration Act and its associated regulations, and may be subject to export or
        import regulations in other countries. Customer agrees to comply strictly with all such regulations
        and acknowledges that it has the responsibility to obtain licenses to export, re-export, or import
        Software.
        
        Governing Law: This Agreement shall be governed by and construed in accordance with the laws of the
        State of Colorado, United States of America, as if performed wholly within the state and without
        giving effect to the principles of conflict of law.
        
        Assignment: Customer may not novate, assign, or transfer in whole or in part any of its rights or
        obligations under this agreement, whether by operation or law or otherwise, without the prior written
        consent of Acroname. A change in control of Customer constitutes an assignment of this agreement.
        Acroname may at any time, by notice to Customer, novate, assign, or transfer in whole or in part its
        rights and obligations under this agreement to any third party and to the extent necessary, Customer
        hereby consents to such novation, assignment, or transfer.
        
        General: If any portion hereof is found to be void or unenforceable, the remaining provisions of this
        Agreement shall remain in full force and effect. This Agreement constitutes the entire license
        between the parties with respect to the use of the Software.
        
        ## BRAINSTEM2 DIRECT DEPENDENCY LICENSE NOTIFICATION
        
        ### LIB USB
        
        This binary distribution uses libUSB (https://libusb.info). LibUSB is licensed under GNU Lesser
        General Public License (LGPL) v2.1. Acroname will provide, upon request (support@acroname.com),
        object code sufficient to relink the Acroname provided executables and libraries with an updated
        interface-compatible libUSB library.
        
        Full license text is available: https://www.gnu.org/licenses/lgpl-2.1.html
        
        ### QT
        
        This binary distribution uses Qt (https://qt.io). Qt is licensed under GNU Lesser General Public
        License (LGPL) v3.0. Acroname will provide, upon request to support@acroname.com, object code
        sufficient to relink the Acroname provided executables and libraries with an updated interface
        compatible Qt library.
        
        Full license text for Qt is available: https://www.gnu.org/licenses/lgpl-3.0.en.html
        
        ## HUBTOOL ICON CREDITS
        Settings icons created by Tomas Knop - Flaticon
        Expand icons created by Google - Flaticon
        Filter icons created by Kiranshastry - Flaticon
        Funnel icons created by Freepik - Flaticon
        
        ACRONAME EXAMPLES, DOCUMENTATION AND SOURCE CODE DISTRIBUTIONS
        
        Copyright (c) 1994-2024, Acroname Inc. All rights reserved.
        
        Redistribution and use in source and binary forms, with or without modification, are permitted
        provided that the following conditions are met:
        
        Redistributions of source code must retain the above copyright notice, this list of conditions and
        the following disclaimer.
        Redistributions in binary form must reproduce the above copyright notice, this list of conditions and
        the following disclaimer in the documentation and/or other materials provided with the distribution.
        THIS SOFTWARE IS NOT INTENDED FOR USE IN LIFE-SUPPORT SYSTEMS.
        
        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR
        IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
        FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
        CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
        DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
        DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
        CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE
        USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
        
        The views and conclusions contained in the software and documentation are those of the authors and
        should not be interpreted as representing official policies, either expressed or implied, of Acroname
        Inc.
        
        Acroname Inc.
        
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 3
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: OS Independent
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: cffi (<2.0.0,>=1.0.0) ; python_version <= "3.8"
Requires-Dist: pycparser (<3.0.0,>=2.18) ; python_version <= "3.8"
Requires-Dist: cffi (>=1.0.0) ; python_version > "3.8"
Requires-Dist: pycparser (>=2.18) ; python_version > "3.8"

# 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.
