API Reference¶
PulsePal¶
Constructor¶
| Parameter | Type | Default | Description |
|---|---|---|---|
serial_port |
str | None |
Serial port path (e.g. /dev/ttyACM0, COM3) |
baudrate |
int | 115200 |
Serial baud rate |
cycle_frequency |
int | 20000 |
Hardware cycle frequency in Hz |
nr_output_channels |
int | 4 |
Number of output channels |
nr_trigger_channels |
int | 2 |
Number of trigger channels |
Attributes¶
| Attribute | Type | Description |
|---|---|---|
channel_configs |
list[ChannelConfig] |
Per-channel configuration (0-indexed) |
trigger_configs |
list[TriggerConfig] |
Per-trigger configuration (0-indexed) |
config |
PulsePalConfig |
Snapshot of current in-memory state (property) |
firmware_version |
int | Detected firmware version |
model |
int | Hardware model: 1 or 2 |
Upload methods¶
| Method | Description |
|---|---|
sync_all_params() |
Bulk upload all params in one serial write (preferred) |
upload_all() |
Per-parameter upload with per-write confirmation |
program_one_param(channel, param_name, param_value) |
Update a single parameter on one channel |
program_trigger_channel(trigger_channel, trigger_mode) |
Set trigger mode on a trigger channel |
Voltage and output¶
| Method | Description |
|---|---|
set_resting_voltage(channel, voltage) |
Set restingVoltage on one channel |
set_fixed_voltage(channel, voltage) |
Set immediate DC voltage outside pulse train |
set_continuous(channel, state) |
Start (1) or stop (0) continuous output on a channel |
set_logic(channel, level) |
Set digital logic level: model 2 only |
get_logic(channel) |
Read digital logic level: model 2 only |
Triggering¶
| Method | Description |
|---|---|
trigger_selected_channels(**kwargs) |
Software-trigger specific channels (channel_1=True, …) |
trigger_all_channels() |
Software-trigger all four channels |
stop_all_outputs() |
Abort all running outputs |
Custom trains¶
| Method | Description |
|---|---|
upload_custom_pulse_train(pulse_train_id, pulse_times, pulse_voltages) |
Upload custom timing+voltage sequence to slot 0 or 1 |
upload_custom_waveform(pulse_train_id, pulse_width, pulse_voltages) |
Upload evenly-spaced waveform to slot 0 or 1 |
Config persistence¶
| Method | Description |
|---|---|
save_config(path) |
Save in-memory config to JSON or YAML |
load_config(path) |
Load config from JSON or YAML and apply in memory |
from_config(config, serial_port) |
Class method: connect and apply a PulsePalConfig |
save_settings() |
Send disconnect opcode to persist params on device |
save_to_sd(filename) |
Save RAM params to SD card: model 2 only |
read_sd_params() |
Read SD card params as dict: model 2 only |
reset_to_defaults() |
Reset all configs to defaults and sync to device |
Models¶
PulsePalConfig uses 1-indexed integer keys for channels and triggers: channels[1] through channels[4], triggers[1] through triggers[2]. String keys from JSON ("1", "2", …) are coerced to integers automatically.
See Concepts for field-level documentation.
config_io¶
| Function | Description |
|---|---|
load_config(path) |
Load PulsePalConfig from a JSON or YAML file |
save_config(config, path) |
Save PulsePalConfig to a JSON or YAML file |
Auto-generated reference¶
pypulsepal.PulsePal
¶
Python interface for the PulsePal open-source pulse train generator.
Connects to PulsePal hardware over serial and provides methods for configuring output channels, uploading pulse trains, and triggering outputs.
Example
pp = PulsePal("/dev/ttyACM0") pp.channel_configs[0].phase1_duration = 0.001 pp.sync_all_params() pp.trigger_all_channels() pp.save_settings()
config
property
¶
Current channel and trigger configs as a PulsePalConfig snapshot.
encoded_opcode
property
writable
¶
The handshake opcode byte encoded for serial transmission.
__enter__()
¶
Return self to support use as a context manager.
__exit__(exc_type, exc_val, exc_tb)
¶
Save settings and close the serial connection on context exit.
__init__(serial_port=None, baudrate=115200, cycle_frequency=PULSEPAL_CYCLE_FREQUENCY, nr_output_channels=4, nr_trigger_channels=2, opcode=213, **kwargs)
¶
Connect to PulsePal hardware over serial.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
serial_port
|
str | None
|
Serial port path (e.g. |
None
|
baudrate
|
int
|
Serial baud rate. |
115200
|
cycle_frequency
|
int
|
Hardware cycle frequency in Hz. |
PULSEPAL_CYCLE_FREQUENCY
|
nr_output_channels
|
int
|
Number of output channels. |
4
|
nr_trigger_channels
|
int
|
Number of trigger channels. |
2
|
**kwargs
|
Any
|
Additional keyword arguments (ignored). |
{}
|
close()
¶
Save settings to device and close the serial connection.
connect(serial_port, baudrate=115200, timeout=1)
¶
Connect to hardware and perform handshake.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
serial_port
|
str
|
Serial port path (e.g. |
required |
baudrate
|
int
|
Serial baud rate. |
115200
|
timeout
|
float
|
Serial read timeout in seconds. |
1
|
Returns:
| Type | Description |
|---|---|
PulsePal
|
Self, for method chaining. |
from_config(config, serial_port, **kwargs)
classmethod
¶
Construct a connected PulsePal with the given config pre-loaded and synced.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
config
|
PulsePalConfig
|
Device configuration to apply immediately after connecting. |
required |
serial_port
|
str
|
Serial port path (e.g. |
required |
**kwargs
|
Forwarded to the constructor. |
{}
|
Returns:
| Type | Description |
|---|---|
PulsePal
|
Connected PulsePal instance with all parameters synced to hardware. |
get_logic(channel)
¶
Read current Arduino digital logic level on an output channel (opcode 87).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
channel
|
int
|
0-indexed output channel. |
required |
Returns:
| Type | Description |
|---|---|
int
|
Logic level: 0 or 1. |
load_config(path)
¶
Load channel/trigger configs from a JSON or YAML file and apply in memory.
program_one_param(channel=None, param_name=None, param_value=None)
¶
Send a single parameter update to hardware and mirror it in the in-memory config.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
channel
|
0-indexed channel number. |
None
|
|
param_name
|
Parameter name string (e.g. |
None
|
|
param_value
|
Value in natural units (volts or seconds); scaling to wire format is applied internally. |
None
|
Returns:
| Type | Description |
|---|---|
|
True if hardware acknowledged the write. |
program_trigger_channel(trigger_channel=None, trigger_mode=None)
¶
Set the trigger mode for one trigger input channel.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
trigger_channel
|
0-indexed trigger channel number. |
None
|
|
trigger_mode
|
Mode as an integer (0 normal, 1 toggle, 2 gated) or the
equivalent string ( |
None
|
Returns:
| Type | Description |
|---|---|
|
True if hardware acknowledged the write. |
read_sd_params()
¶
Read 178-byte SD parameter file via opcode 85 and parse to a dict.
Returns None if the firmware returns an unexpected byte count. Keys match ChannelConfig field names; 'triggerAddress' is firmware-only (4-element list of output channel link flags per trigger channel).
per output channel ×4 (42 bytes each):
8× uint32 phase1Duration, interPhaseInterval, phase2Duration, interPulseInterval, burstDuration, interBurstInterval, pulseTrainDuration, pulseTrainDelay (firmware cycles ÷ 20000 = s) 1× uint8 isBiphasic 3× uint16 phase1Voltage, phase2Voltage, restingVoltage (0-65535 → ±10V) 3× uint8 customTrainID, customTrainTarget, customTrainLoop
Per trigger channel ×2 (5 bytes each): 1× uint8 triggerMode 4× uint8 triggerAddress[0..3] Total: 4×42 + 2×5 = 178 bytes
reset_to_defaults()
¶
Reset all channel and trigger configs to factory defaults and sync to hardware.
save_config(path)
¶
Save current channel/trigger configs to a JSON or YAML file.
save_settings()
¶
Send disconnect opcode (81) to save current params on device.
Firmware sends no ack byte for this opcode: confirmed on model 2 fw21. Returns False if not connected or port is closed.
save_to_sd(filename='default.pps')
¶
Save current RAM params to SD card (opcode 90, op 1).
Firmware sends no ack byte: do not read confirmation. A 100ms sleep is inserted to allow SD write to complete.
set_continuous(channel, state)
¶
Enable or disable continuous output mode on one channel.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
channel
|
int
|
0-indexed output channel. |
required |
state
|
int
|
1 to enable continuous output, 0 to disable. |
required |
Returns:
| Type | Description |
|---|---|
bool
|
True if hardware acknowledged the write. |
set_fixed_voltage(channel, voltage)
¶
Set a channel to a fixed DC voltage immediately, outside of any pulse train.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
channel
|
int
|
0-indexed output channel. |
required |
voltage
|
float
|
Target voltage in volts (range: -10 to +10 V). |
required |
Returns:
| Type | Description |
|---|---|
bool
|
True if hardware acknowledged the write. |
set_logic(channel, level)
¶
Set Arduino digital logic level on an output channel (model 2, opcode 86).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
channel
|
int
|
0-indexed output channel. |
required |
level
|
int
|
Logic level: 0 or 1. |
required |
set_resting_voltage(channel, voltage)
¶
Set the resting (idle) voltage on one output channel.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
channel
|
int
|
0-indexed output channel. |
required |
voltage
|
float
|
Resting voltage in volts. |
required |
Returns:
| Type | Description |
|---|---|
bool
|
True if hardware acknowledged the write. |
stop_all_outputs()
¶
Abort all currently running pulse train outputs.
sync_all_params()
¶
Upload all parameters in a single bulk serial write (opcode 73).
Faster than upload_all() which does one serial round trip per parameter. Byte layout differs between model 1 and model 2.
trigger_all_channels()
¶
Software-trigger all four output channels simultaneously.
trigger_selected_channels(channel_1=False, channel_2=False, channel_3=False, channel_4=False)
¶
Software-trigger specific output channels.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
channel_1
|
bool
|
Trigger channel 1. |
False
|
channel_2
|
bool
|
Trigger channel 2. |
False
|
channel_3
|
bool
|
Trigger channel 3. |
False
|
channel_4
|
bool
|
Trigger channel 4. |
False
|
upload_all()
¶
Program all channel and trigger parameters via individual serial writes.
Prefer sync_all_params() for faster bulk upload.
upload_custom_pulse_train(pulse_train_id, pulse_times, pulse_voltages)
¶
Upload a custom pulse train to hardware slot 0 or 1.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
pulse_train_id
|
int
|
Slot index, 0 or 1. |
required |
pulse_times
|
list[float]
|
Pulse onset times in seconds. |
required |
pulse_voltages
|
list[float]
|
Output voltages in volts for each pulse. |
required |
Returns:
| Type | Description |
|---|---|
bool
|
True if hardware acknowledged the upload. |
upload_custom_waveform(pulse_train_id, pulse_width, pulse_voltages)
¶
Upload an evenly-spaced waveform to hardware slot 0 or 1.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
pulse_train_id
|
int
|
Slot index, 0 or 1. |
required |
pulse_width
|
float
|
Inter-sample interval in seconds. |
required |
pulse_voltages
|
list[float]
|
Output voltages in volts for each sample. |
required |
Returns:
| Type | Description |
|---|---|
bool
|
True if hardware acknowledged the upload. |
pypulsepal.pulsepal.PulsePalError
¶
Bases: Exception
Convenience error object for PulsePal