larsrollik / pypulsepal

Python API to interact with PulsePal

PyPulsePal

Python API for the PulsePal open-source pulse train generator

Version: "0.0.2.dev0"

This package provides an API to the PulsePal hardware. This API is a re-implementation of the original PulsePal Python 3 API that draws from the pybpod-api communication protoool.

Example usage

script/function

import time
from pypulsepal import PulsePal

serial_port = "/dev/ttyACM0"  # for unix or "COM"-style port names for Windows

# Create PulsePal object
pp = PulsePal(serial_port=serial_port)

# Set parameters

## Manually
pp.program_one_param(channel=2, param_name="phase1Duration", param_value=.002)

## Via convencience functions
pp.set_resting_voltage(channel=2, voltage=4.2)

# Upload parameters
pp.upload_all()

# Trigger selected channels
pp.trigger_selected_channels(channel_2=True, channel_4=True)

time.sleep(1)

# Stop outputs
pp.stop_all_outputs()

time.sleep(1)

# Save settings (also done automatically on disconnect)
pp.save_settings()

Channels can also be triggered all at once

import time
from pypulsepal import PulsePal

serial_port = "/dev/ttyACM0"  # for unix or "COM"-style port names for Windows

# Create PulsePal object
pp = PulsePal(serial_port=serial_port)

# Trigger all channels
pp.trigger_all_channels()

time.sleep(1)

# Stop outputs
pp.stop_all_outputs()

as context manager

import time
from pypulsepal import PulsePal

with PulsePal(serial_port="/dev/ttyACM0") as pp:
    # set params
    pp.upload_all()

    # do something
    time.sleep(2)

Write default params to all channels

from pypulsepal.write_tests import write_default_settings

write_default_settings(serial_port="/dev/ttyACM0")

Write (funky) test params to all channels

from pypulsepal.write_tests import write_test_settings_for_manual_check

write_test_settings_for_manual_check(serial_port="/dev/ttyACM0")

Installation

pip

pip install pypulsepal

git

git clone https://github.com/larsrollik/pypulsepal.git
cd pypulsepal/
pip install -e .

pip + git

pip install git+https://github.com/larsrollik/pypulsepal.git

Problems & issues

Please open issues or pull-requests in this repository.

Citation

Please cite the original PulsePal and PyBpod code and publications that this package is based on.

To cite PyPulsePal with a reference to the current version (as publicly documented on Zenodo), please use:

Rollik, Lars B. (2021). PyPulsePal: Python API for the PulsePal open-source pulse train generator. doi: 10.5281/zenodo.6379627.

BibTeX

@misc{rollik2022pypulsepal,
    author       = {Lars B. Rollik},
    title        = {{PyPulsePal: Python API for the PulsePal open-source pulse train generator}},
    year         = {2022},
    month        = mar,
    publisher    = {Zenodo},
    url          = {https://doi.org/10.5281/zenodo.6379627},
    doi          = {10.5281/zenodo.6379627},
  }

License & sources

This software is released under the GNU GPL v3.0.

This work is derived from the Sanworks PulsePal Python API (commit: 5bb189f).

The architecture of the API is imported and inspired by the pybpodapi.com.arcom module from the pybpod-api.

For changes from the original implementation, see the git history since commit 972bc1e.

Useful code references

• PyBpod com ArCOM
• PyBpod com protocol
• PyBpod message headers
• PulsePal Python 3 API
• PulsePal .ino file
• PulsePal param definitions

TODO

• Simplify parameter dicts in definitions: into nested dict with first level for name, then standard sub-dict (default value, dtype, dtype legacy(model 1), scaling, )
• Complete API functions with all PulsePal opcodes, e.g. for Arduino logic levels (see PulsePal USB v2 opcode list)
• Move PulsePal hardware settings to init and remove defaults for easier upgrade in future
• API function to accept list of dicts (from json settings file)
  • to make overwrites on channels to get from value-based logic to channel parameter sets
  • add write function to save all settings to json for documentation

pypulsepal's Issues

Move param structure to flattened and explicit properties

example code does not work

the provided example code doesn't run on my system:

# Create PulsePal object
pp = PulsePal(serial_port=serial_port)

# Set parameters

## Manually
pp.program_one_param(channel=2, param_name="phase1Duration", param_value=.002)

## Via convencience functions
pp.set_resting_voltage(channel=2, voltage=4.2)

# Upload parameters
pp.upload_all()

# Trigger channels
pp.trigger_selected_channels(channel_2=True, channel_4=True)
pp.trigger_all_channels()

# Stop outputs
pp.stop_all_outputs()

# Save settings (also done automatically on disconnect)
pp.save_settings()

trigger_all_channels() calls self.trigger_channels() of the PulsePal object, which isn't implemented. Guessing by its call signature that it should be self.trigger_selected_channels() still makes it crash further down the road, briefly looking at it seems like _read_confirmation() never returns True.

Windows 10, PulsePal 2.0

Update build system to toml/cfg standard

Add offline mode for testing/debugging

• accept all args, but do not really upload -> might require to move .write serial comms functions into central location to block interaction to avoid serial exceptions
• also requires to not auto-connect

Add a json/yaml config loader to specify port, channels and params