Zaber Launcher Tutorials
Zaber Motion Library
Sample Projects
Virtual DeviceDropdown icon
About3D Viewer
AccountDropdown icon
Sign InSign Up
Zaber Motion LibraryGetting StartedHow-to Guides
API Reference
root
zaber_motion.ascii
AlertEventAllAxesAxisAxisGroupAxisIdentityAxisSettingsAxisStorageAxisTypeConnectionConversionFactorDeviceDeviceIdentityDeviceIODeviceIOInfoDeviceSettingsDeviceStorageDigitalOutputActionGetAxisSettingGetAxisSettingResultGetSettingGetSettingResultIoPortLabelIoPortTypeLockstepMeasurementSequenceMessageTypeOscilloscopeOscilloscopeCapturePropertiesOscilloscopeDataOscilloscopeDataSourceParamsetInfoPidTuningPvtPvtAxisDefinitionPvtAxisTypePvtBufferPvtCallActionPvtCancelAllOutputsScheduleActionPvtCancelOutputScheduleActionPvtCsvDataPvtIoPvtModePvtPartialCsvDataPvtPartialPointPvtPartialSequenceItemPvtPointPvtSequencePvtSequenceItemPvtSetAllAnalogOutputsActionPvtSetAllDigitalOutputsActionPvtSetAnalogOutputActionPvtSetDigitalOutputActionResponseServoTunerServoTuningParamServoTuningParamsetSetStateAxisResponseSetStateDeviceResponseSettingConstantsSimpleTuningSimpleTuningParamDefinitionStreamStreamAxisDefinitionStreamAxisTypeStreamBufferStreamIoStreamModeStreamsTransportTriggerTriggerActionTriggerConditionTriggerEnabledStateTriggerOperationTriggersTriggerStateUnknownResponseEventWarningFlagsWarnings
zaber_motion.binary
BinarySettingsCommandCodeConnectionDeviceDeviceIdentityDeviceSettingsDeviceTypeErrorCodeMessageReplyCodeReplyOnlyEventUnknownResponseEvent
zaber_motion.exceptions
MotionLibExceptionBinaryCommandFailedExceptionDataCommandFailedExceptionDataCommandTooLongExceptionDataDeviceAddressConflictExceptionDataDeviceDbFailedExceptionDataDeviceDbInnerErrorGCodeExecutionExceptionDataGCodeSyntaxExceptionDataInvalidPacketExceptionDataInvalidPvtPointInvalidResponseExceptionDataMovementFailedExceptionDataMovementInterruptedExceptionDataOperationFailedExceptionDataPvtExecutionExceptionDataPvtMovementFailedExceptionDataPvtMovementInterruptedExceptionDataSetDeviceStateExceptionDataSetPeripheralStateExceptionDataStreamExecutionExceptionDataStreamMovementFailedExceptionDataStreamMovementInterruptedExceptionData
zaber_motion.gcode
AxisDefinitionAxisMappingAxisTransformationDeviceDefinitionOfflineTranslatorTranslateMessageTranslateResultTranslatorTranslatorConfig
zaber_motion.microscopy
AutofocusAutofocusStatusCameraTriggerFilterChangerIlluminatorIlluminatorChannelMicroscopeMicroscopeConfigObjectiveChangerThirdPartyComponentsWdiAutofocusProviderWdiAutofocusProviderStatus
zaber_motion.product
ProcessProcessControllerProcessControllerModeProcessControllerSourceProcessControllerSourceSensor
zaber_motion
AxisAddressChannelAddressCyclicDirectionDeviceDbSourceDeviceDbSourceTypeDeviceDiscoveryResultDevicePortTypeFirmwareVersionLibraryLogOutputModeMeasurementNamedParameterRotationDirectionToolsUnitConversionDescriptorUnitsUnitTable
SupportBinary Protocol (Legacy)
© 2026 Zaber Technologies Inc.

API Reference v9.0.0

PvtSequenceclass

Module: zaber_motion.ascii

A handle for a PVT sequence with this number on the device. PVT sequences provide a way execute or store trajectory consisting of points with defined position, velocity, and time. PVT sequence methods append actions to a queue which executes or stores actions in a first in, first out order.

The following example illustrates how you can obtain an instance of this type:

from zaber_motion.ascii import Connection

connection = Connection.open_serial_port('COM3')
device = connection.get_device(1)
pvt = device.pvt
pvt_sequence = pvt.get_sequence(1)
Related Guides:
  • Position Velocity Time (PVT)
  • PVT Sequence Generation

Index

pProperties
axes
device
io
mode
pvt_id
mMethods
call()
check_disabled()
convert_time_absolute_to_relative()
convert_time_absolute_to_relative_partial()
convert_time_relative_to_absolute()
convert_time_relative_to_absolute_partial()
cork()
disable()
generate_positions()
generate_velocities()
generate_velocities_and_times()
generic_command()
generic_command_batch()
ignore_current_discontinuity()
is_busy()
load_partial_sequence_data()
load_sequence_data()
point()
point_relative()
points()
points_relative()
save_sequence_data()
setup_live()
setup_live_composite()
setup_store()
setup_store_composite()
submit_sequence_data()
__repr__()
treat_discontinuities_as_error()
uncork()
wait_until_idle()

Properties

p

axes

readonly
pvt_sequence.axes
List[PvtAxisDefinition] An array of axes definitions the PVT sequence is set up to control.
p

device

readonly
pvt_sequence.device
Device Device that controls this PVT sequence.
p

io

readonly
pvt_sequence.io
PvtIo Gets an object that provides access to I/O for this sequence.
p

mode

readonly
pvt_sequence.mode
PvtMode Current mode of the PVT sequence.
p

pvt_id

readonly
pvt_sequence.pvt_id
int The number that identifies the PVT sequence on the device.

Methods

m

call()

async available
pvt_sequence.call(pvt_buffer)
Append the actions in a PVT buffer to the sequence's queue.
Arguments
NameTypeDescription
pvt_bufferPvtBufferThe PVT buffer to call.
m

check_disabled()

async available
pvt_sequence.check_disabled()
Queries the PVT sequence status from the device and returns boolean indicating whether the PVT sequence is disabled. Useful to determine if execution was interrupted by other movements.
Return Value
bool True if the PVT sequence is disabled.
s

convert_time_absolute_to_relative()

async available
PvtSequence.convert_time_absolute_to_relative(sequence_data)
Converts the time values in a PvtSequenceItem array from absolute to relative. Points passed to the Generate functions or sent to devices must have relative time values.
Arguments
NameTypeDescription
sequence_dataList[PvtSequenceItem]The sequence data for which to convert times from absolute to relative. Point times must all be in the same units.
Return Value
List[PvtSequenceItem] The sequence data with times converted from absolute to relative.
s

convert_time_absolute_to_relative_partial()

async available
PvtSequence.convert_time_absolute_to_relative_partial(sequence_data)
Converts the time values in a PvtPartialSequenceItem array from absolute to relative. Points passed to the Generate functions or sent to devices must have relative time values.
Arguments
NameTypeDescription
sequence_dataList[PvtPartialSequenceItem]The sequence data for which to convert times from absolute to relative. Point times must all be in the same units.
Return Value
List[PvtPartialSequenceItem] The sequence data with times converted from absolute to relative.
s

convert_time_relative_to_absolute()

async available
PvtSequence.convert_time_relative_to_absolute(sequence_data)
Converts the time values in a PvtSequenceItem array from relative to absolute.
Arguments
NameTypeDescription
sequence_dataList[PvtSequenceItem]The sequence data for which to convert times from relative to absolute. Point times must all be in the same units.
Return Value
List[PvtSequenceItem] The sequence data with times converted from relative to absolute.
s

convert_time_relative_to_absolute_partial()

async available
PvtSequence.convert_time_relative_to_absolute_partial(sequence_data)
Converts the time values in a PvtPartialSequenceItem array from relative to absolute.
Arguments
NameTypeDescription
sequence_dataList[PvtPartialSequenceItem]The sequence data for which to convert times from relative to absolute. Point times must all be in the same units.
Return Value
List[PvtPartialSequenceItem] The sequence data with times converted from relative to absolute.
m

cork()

async available
pvt_sequence.cork()
Cork the front of the PVT sequences's action queue, blocking execution. Execution resumes upon uncorking the queue, or when the number of queued actions reaches its limit. Corking eliminates discontinuities in motion due to subsequent PVT commands reaching the device late. You can only cork an idle live PVT sequence.
m

disable()

async available
pvt_sequence.disable()
Disables the PVT sequence. If the PVT sequence is not setup, this command does nothing. Once disabled, the PVT sequence will no longer accept PVT commands. The PVT sequence will process the rest of the commands in the queue until it is empty.
s

generate_positions()

async available
PvtSequence.generate_positions(sequence_items)
Generates positions for a sequence of velocities and times. This function calculates positions by enforcing that acceleration be continuous at each segment transition. This function does not modify the input velocities or times, and outputs absolute positions. If your initial point has a time of zero, it will be considered a starting position when submitted to the device, and you must already have moved the device to that position. Additionally, all times must be relative to the previous point. Please see the ConvertTimeAbsoluteToRelativePartial function for conversions. Does not support native units.
Arguments
NameTypeDescription
sequence_itemsList[PvtPartialSequenceItem]Partial PVT points defining the velocities and times for the sequence. Each point should have velocities defined for each axis. Times must be defined for each point.
Return Value
List[PvtSequenceItem] Array of points and actions containing the generated PVT sequence. Note returned times are always relative.
s

generate_velocities()

async available
PvtSequence.generate_velocities(sequence_items)
Generates velocities for a sequence of positions and times, and (optionally) a partially defined sequence of velocities. Note that if some velocities are defined, the solver will NOT modify them in any way. If all velocities are defined, the solver will simply return the same velocities. This function calculates velocities by enforcing that acceleration be continuous at each segment transition. The function does not modify the input positions or times. Also note that if the first position is relative, all following points must be relative. If the start position is absolute, then the sequence can include a mix of relative and absolute positions. Additionally, all times must be relative to the previous point. Please see the ConvertTimeAbsoluteToRelativePartial function for conversions. Does not support native units.
Arguments
NameTypeDescription
sequence_itemsList[PvtPartialSequenceItem]Partial PVT points defining the positions, optional velocities, and times for the sequence. Each point should have positions defined for each axis. Velocities are optional. Times must be defined for each point.
Return Value
List[PvtSequenceItem] Array of points and actions containing the generated PVT sequence. Note returned times are always relative.
s

generate_velocities_and_times()

async available
PvtSequence.generate_velocities_and_times(sequence_items, target_speed, target_acceleration, resample_number = None)
Generates sequences of velocities and times for a sequence of positions. This function fits a geometric spline (not-a-knot cubic for sequences of >3 points, natural cubic for 3, and a straight line for 2) over the position sequence and then calculates the velocity and time information by traversing it using a trapezoidal motion profile. This generation scheme attempts to keep speed and acceleration less than the specified target values, but does not guarantee it. Generally speaking, a higher resample number will bring the generated trajectory closer to respecting these limits. Note that consecutive duplicate points will be automatically removed as they have no geometric significance without additional time information. Also note that for multi-dimensional paths this function expects axes to be linear and orthogonal, however for paths of a single dimension rotary units are accepted. Additionally, if the first positions of the input sequence is relative, all following positions must also be relative. If the first position is absolute, the sequence may contain a mix of relative and absolute positions. Resampling a sequence which contains relative positions is not allowed. This function outputs points with absolute positions and relative times, with the first time equal to zero, meaning it will be treated as a start position when executing on a device. You must move the device to that position before submitting the sequence, or change the first point's time to a value greater than zero. Does not support native units.
Arguments
NameTypeDescription
sequence_itemsList[PvtPartialSequenceItem]Partial PVT points defining the positions for the sequence. Each point should have positions defined for each axis.
target_speedMeasurementThe target speed used to generate positions and times.
target_accelerationMeasurementThe target acceleration used to generate positions and times.
resample_numberOptional[int]The number of points to resample the sequence by. Leave undefined to use the specified points.
Return Value
List[PvtSequenceItem] Array of points and actions containing the generated PVT sequence. Note returned times are always relative.
m

generic_command()

async available
pvt_sequence.generic_command(command)
Sends a generic ASCII command to the PVT sequence. Keeps resending the command while the device rejects with AGAIN reason.
Arguments
NameTypeDescription
commandstrCommand and its parameters.
m

generic_command_batch()

async available
pvt_sequence.generic_command_batch(batch)
Sends a batch of generic ASCII commands to the PVT sequence. Keeps resending command while the device rejects with AGAIN reason. The batch is atomic in terms of thread safety.
Arguments
NameTypeDescription
batchList[str]Array of commands.
m

ignore_current_discontinuity()

pvt_sequence.ignore_current_discontinuity()
Prevents PvtDiscontinuityException as a result of expected discontinuity when resuming the sequence.
m

is_busy()

async available
pvt_sequence.is_busy()
Returns a boolean value indicating whether the live PVT sequence is executing a queued action.
Return Value
bool True if the PVT sequence is executing a queued action.
s

load_partial_sequence_data()

async available
PvtSequence.load_partial_sequence_data(path)
Load PVT Sequence data from CSV file, allowing for some combinations of incomplete data. Output from this function cannot be enqueued on a device until the missing data has been filled in using the GenerateVelocities, GeneratePositions or GenerateVelocitiesAndTimes functions. The CSV data can include a header (recommended). There are two possible header formats: 1. A time column with named position and velocity columns. For example, "Time (ms),X Position (cm),X Velocity (cm/s),...". In this case, position, velocity and time columns are all optional. Also, order does not matter, but position and velocity names must be consistent. This is our recommended CSV format. 2. A time column with alternating position and velocity columns. For example, "Time (ms),Position (cm),Velocity (cm/s),...". In this case, only the time column is optional and order does matter. Units must be wrapped in parens or square braces: ie. (µm/s), [µm/s]. Additionally, native units are the default if no units are specified. Time values default to milliseconds if no units are provided. If no header is included, then column order is assumed to be "T,P1,V1,P2,V2,...". In this case the number of columns must be odd. Users can add a column named "Relative" with true/false values to indicate whether each point's position is relative or absolute. If this column is not included, all points will be assumed to be absolute. If the first point has time = zero, it is considered the start position and treated specially. It must have an absolute position, and the device must already be idle at that position when the sequence is submitted. The velocity of the start position is ignored, and should normally be zero. Sequences with nonzero time for the first point do not have these constraints. Buffer calls and I/O actions can be added into the CSV file by adding a column titled "Actions", containing the ASCII protocol command(s) shortened by everything up to the PVT stream number, for example "call 2" or "io set do 1 1". If you want to insert multiple actions after a point, put them in the same cell separated by a semicolon. See the ASCII Protocol Manual PVT command reference section for the list of available commands. Unit symbols are not supported; analog output voltages are always in volts and schedule delay times are always in milliseconds. Note that the Relative and Actions columns are not automatically detected, so if you include them you must include a header row. Time values should always be relative when sent to a device or to the various Generate... functions on this class. If you want to store absolute times in a CSV file, you can use the ConvertTimeRelativeToAbsolute function to convert after loading the file.
Arguments
NameTypeDescription
pathstrThe path to the csv file to load.
Return Value
PvtPartialCsvData The PVT csv data loaded from the file.
s

load_sequence_data()

async available
PvtSequence.load_sequence_data(path)
Load PVT Sequence data from CSV file. This function expects complete data in the CSV files (a time column and both position and velocity columns for each series). If your CSV file has partial data, use LoadPartialSequenceData instead. The CSV data can include a header (recommended). There are two possible header formats: 1. A time column with named position and velocity columns. For example, "Time (ms),X Position (cm),X Velocity (cm/s),...". In this case, position, velocity and time columns are all optional. Also, order does not matter, but position and velocity names must be consistent. This is our recommended CSV format. 2. A time column with alternating position and velocity columns. For example, "Time (ms),Position (cm),Velocity (cm/s),...". In this case, only the time column is optional and order does matter. Units must be wrapped in parens or square braces: ie. (µm/s), [µm/s]. Additionally, native units are the default if no units are specified. Time values default to milliseconds if no units are provided. If no header is included, then column order is assumed to be "T,P1,V1,P2,V2,...". In this case the number of columns must be odd. Users can add a column named "Relative" with true/false values to indicate whether each point's position is relative or absolute. If this column is not included, all points will be assumed to be absolute. If the first point has time = zero, it is considered the start position and treated specially. It must have an absolute position, and the device must already be idle at that position when the sequence is submitted. The velocity of the start position is ignored, and should normally be zero. Sequences with nonzero time for the first point do not have these constraints. Buffer calls and I/O actions can be added into the CSV file by adding a column titled "Actions", containing the ASCII protocol command(s) shortened by everything up to the PVT stream number, for example "call 2" or "io set do 1 1". If you want to insert multiple actions after a point, put them in the same cell separated by a semicolon. See the ASCII Protocol Manual PVT command reference section for the list of available commands. Unit symbols are not supported; analog output voltages are always in volts and schedule delay times are always in milliseconds. Note that the Relative and Actions columns are not automatically detected, so if you include them you must include a header row. Time values should always be relative when sent to a device or to the various Generate... functions on this class. If you want to store absolute times in a CSV file, you can use the ConvertTimeRelativeToAbsolute function to convert after loading the file.
Arguments
NameTypeDescription
pathstrThe path to the csv file to load.
Return Value
PvtCsvData The PVT csv data loaded from the file.
m

point()

async available
pvt_sequence.point(positions, velocities, time)
Queues a point with absolute coordinates in the PVT sequence. If some or all velocities are not provided, the sequence calculates the velocities from surrounding points using finite difference. If time value is zero, the device must already be idle at the specified position and the specified velocity must be zero. The last point of the sequence must have defined velocity (likely zero).
Arguments
NameTypeDescription
positionsList[Measurement]Positions for the axes to move through, relative to their home positions.
velocitiesList[Optional[Measurement]]The axes velocities at the given point. Specify an empty array or null for specific axes to make the sequence calculate the velocity.
timeMeasurementThe duration between the previous point in the sequence and this one.
m

point_relative()

async available
pvt_sequence.point_relative(positions, velocities, time)
Queues a point with coordinates relative to the previous point in the PVT sequence. If some or all velocities are not provided, the sequence calculates the velocities from surrounding points using finite difference. The time value must be greater than zero, and each point must have its time value measured relative to the previous point or unexpected behavior will result. The last point of the sequence must have defined velocity (likely zero).
Arguments
NameTypeDescription
positionsList[Measurement]Positions for the axes to move through, relative to the previous point.
velocitiesList[Optional[Measurement]]The axes velocities at the given point. Specify an empty array or null for specific axes to make the sequence calculate the velocity.
timeMeasurementThe duration between the previous point in the sequence and this one.
m

points()

async available
Obsolete: This method is being replaced by the new SubmitSequenceData method.
pvt_sequence.points(positions, velocities, times)
Queues points with absolute coordinates in the PVT sequence. Each point must have its time value measured relative to the previous point or unexpected behavior will result. Note that if the first time value is zero, the device must already be idle at the position of the first point and the velocity of that point must be zero. All other time values must be greater than zero.
Arguments
NameTypeDescription
positionsList[MeasurementSequence]Per-axis sequences of positions.
velocitiesList[MeasurementSequence]Per-axis sequences of velocities. For velocities [v0, v1, ...] and positions [p0, p1, ...], v1 is the target velocity at point p1.
timesMeasurementSequenceSegment times from one point to another. For times [t0, t1, ...] and positions [p0, p1, ...], t1 is the time it takes to move from p0 to p1.
m

points_relative()

async available
Obsolete: This method is being replaced by the new SubmitSequenceData method.
pvt_sequence.points_relative(positions, velocities, times)
Queues points with coordinates relative to the previous point in the PVT sequence. All time values must be greater than zero and each point must have its time value measured relative to the previous point or unexpected behavior will result.
Arguments
NameTypeDescription
positionsList[MeasurementSequence]Per-axis sequences of positions.
velocitiesList[MeasurementSequence]Per-axis sequences of velocities. For velocities [v0, v1, ...] and positions [p0, p1, ...], v1 is the target velocity at point p1.
timesMeasurementSequenceSegment times from one point to another. For times [t0, t1, ...] and positions [p0, p1, ...], t1 is the time it takes to move from p0 to p1.
s

save_sequence_data()

async available
PvtSequence.save_sequence_data(sequence_data, path, dimension_names = None)
Saves PvtSequenceItem array as a csv file. Save format is compatible with Zaber Launcher PVT Editor App. Normally a sequence in memory should have relative time values on the points. If you want to store absolute times instead, you can use the ConvertTimeRelativeToAbsolute function to convert before saving. Throws InvalidArgumentException if fields are undefined or inconsistent. For example, position and velocity arrays must have the same dimensions. Sequence lengths must be consistent for positions, velocities and times.
Arguments
NameTypeDescription
sequence_dataList[PvtSequenceItem]The PVT sequence data to save.
pathstrThe path to save the file to.
dimension_namesOptional[List[str]]Optional csv column names for each series. If not provided, the default names will be used: Series 1, Series 2, etc.. Length of this array must be equal to number of dimensions in sequence data.
m

setup_live()

async available
pvt_sequence.setup_live(*axes)
Setup the PVT sequence to control the specified axes and to queue actions on the device.
Arguments
NameTypeDescription
*axesintNumbers of physical axes to setup the PVT sequence on.
m

setup_live_composite()

async available
pvt_sequence.setup_live_composite(*pvt_axes)
Setup the PVT sequence to control the specified axes and to queue actions on the device. Allows use of lockstep axes in a PVT sequence.
Arguments
NameTypeDescription
*pvt_axesPvtAxisDefinitionDefinition of the PVT sequence axes.
m

setup_store()

async available
pvt_sequence.setup_store(pvt_buffer, *axes)
Setup the PVT sequence to use the specified axes and queue actions into a PVT buffer.
Arguments
NameTypeDescription
pvt_bufferPvtBufferThe PVT buffer to queue actions in.
*axesintThe axis numbers of the physical axes to setup the PVT sequence on.
m

setup_store_composite()

async available
pvt_sequence.setup_store_composite(pvt_buffer, *pvt_axes)
Setup the PVT sequence to use the specified axes and queue actions into a PVT buffer. Allows use of lockstep axes in a PVT sequence.
Arguments
NameTypeDescription
pvt_bufferPvtBufferThe PVT buffer to queue actions in.
*pvt_axesPvtAxisDefinitionDefinition of the PVT sequence axes.
m

submit_sequence_data()

async available
pvt_sequence.submit_sequence_data(sequence_data)
Writes the contents of a PvtSequenceItem array to the sequence. Each point must have its time value measured relative to the previous point or unexpected behavior will result. If your point times are absolute (measured from the start of the sequence), use the ConvertTimeAbsoluteToRelative function to convert them before submitting. If the first point in the sequence has a time value of zero, it is considered the starting position. It must have an absolute position, zero velocity, and the device must already be idle at the specified position.
Arguments
NameTypeDescription
sequence_dataList[PvtSequenceItem]The PVT sequence data to submit.
m

__repr__()

pvt_sequence.__repr__()
Returns a string which represents the PVT sequence.
Return Value
str String which represents the PVT sequence.
m

treat_discontinuities_as_error()

pvt_sequence.treat_discontinuities_as_error()
Makes the PVT sequence throw PvtDiscontinuityException when it encounters discontinuities (ND warning flag).
m

uncork()

async available
pvt_sequence.uncork()
Uncork the front of the queue, unblocking command execution. You can only uncork an idle live PVT sequence that is corked.
m

wait_until_idle()

async available
pvt_sequence.wait_until_idle(throw_error_on_fault = True)
Waits until the live PVT sequence executes all queued actions.
Arguments
NameTypeDescription
throw_error_on_faultboolDetermines whether to throw error when fault is observed.
Top