# API Reference v10.3.1 (Python)

## Stream (class)

Module: zaber_motion.ascii

A handle for a stream with this number on the device. Streams provide a way to execute or store a sequence of actions. Stream 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:

```py
from zaber_motion.ascii import Connection

connection = Connection.open_serial_port("COM3")
device = connection.get_device(1)
streams = device.streams
stream = streams.get_stream(1)
```

Related Guides:

- [Streamed movement](https://software.zaber.com/motion-library/docs/guides/device_features/streams.md)

### Properties

#### `axes` (read-only)

`stream.axes`

Type: [`List[StreamAxisDefinition]`](https://software.zaber.com/motion-library/api/py/ascii/streamaxisdefinition.md)

An array of axes definitions the stream is set up to control.

#### `device` (read-only)

`stream.device`

Type: [`Device`](https://software.zaber.com/motion-library/api/py/ascii/device.md)

Device that controls this stream.

#### `io` (read-only)

`stream.io`

Type: [`StreamIo`](https://software.zaber.com/motion-library/api/py/ascii/streamio.md)

Gets an object that provides access to I/O for this stream.

#### `mode` (read-only)

`stream.mode`

Type: [`StreamMode`](https://software.zaber.com/motion-library/api/py/ascii/streammode.md)

Current mode of the stream.

#### `stream_id` (read-only)

`stream.stream_id`

Type: `int`

The number that identifies the stream on the device.

### Methods

#### `arc_absolute()` (async available)

`stream.arc_absolute(rotation_direction, center_x, center_y, end_x, end_y)`

Queue an absolute arc movement on the first two axes of the stream. Absolute meaning that the home positions of the axes is treated as the origin.

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `rotation_direction` | [`RotationDirection`](https://software.zaber.com/motion-library/api/py/root/rotationdirection.md) | The direction of the rotation. |
| `center_x` | [`Measurement`](https://software.zaber.com/motion-library/api/py/root/measurement.md) | The first dimension of the position of the center of the circle on which the arc exists. |
| `center_y` | [`Measurement`](https://software.zaber.com/motion-library/api/py/root/measurement.md) | The second dimension of the position of the center of the circle on which the arc exists. |
| `end_x` | [`Measurement`](https://software.zaber.com/motion-library/api/py/root/measurement.md) | The first dimension of the end position of the arc. |
| `end_y` | [`Measurement`](https://software.zaber.com/motion-library/api/py/root/measurement.md) | The second dimension of the end position of the arc. |

#### `arc_absolute_on()` (async available)

`stream.arc_absolute_on(target_axes_indices, rotation_direction, center_x, center_y, end_x, end_y)`

Queue an absolute arc movement in the stream. The movement will only target the specified subset of axes in the stream.

Requires at least Firmware 7.11.

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `target_axes_indices` | `List[int]` | Indices of the axes in the stream the movement targets. Refers to the axes provided during the stream setup or further execution. Indices are zero-based. |
| `rotation_direction` | [`RotationDirection`](https://software.zaber.com/motion-library/api/py/root/rotationdirection.md) | The direction of the rotation. |
| `center_x` | [`Measurement`](https://software.zaber.com/motion-library/api/py/root/measurement.md) | The first dimension of the position of the center of the circle on which the arc exists. |
| `center_y` | [`Measurement`](https://software.zaber.com/motion-library/api/py/root/measurement.md) | The second dimension of the position of the center of the circle on which the arc exists. |
| `end_x` | [`Measurement`](https://software.zaber.com/motion-library/api/py/root/measurement.md) | The first dimension of the end position of the arc. |
| `end_y` | [`Measurement`](https://software.zaber.com/motion-library/api/py/root/measurement.md) | The second dimension of the end position of the arc. |

#### `arc_relative()` (async available)

`stream.arc_relative(rotation_direction, center_x, center_y, end_x, end_y)`

Queue a relative arc movement on the first two axes of the stream. Relative meaning that the current position of the axes is treated as the origin.

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `rotation_direction` | [`RotationDirection`](https://software.zaber.com/motion-library/api/py/root/rotationdirection.md) | The direction of the rotation. |
| `center_x` | [`Measurement`](https://software.zaber.com/motion-library/api/py/root/measurement.md) | The first dimension of the position of the center of the circle on which the arc exists. |
| `center_y` | [`Measurement`](https://software.zaber.com/motion-library/api/py/root/measurement.md) | The second dimension of the position of the center of the circle on which the arc exists. |
| `end_x` | [`Measurement`](https://software.zaber.com/motion-library/api/py/root/measurement.md) | The first dimension of the end position of the arc. |
| `end_y` | [`Measurement`](https://software.zaber.com/motion-library/api/py/root/measurement.md) | The second dimension of the end position of the arc. |

#### `arc_relative_on()` (async available)

`stream.arc_relative_on(target_axes_indices, rotation_direction, center_x, center_y, end_x, end_y)`

Queue a relative arc movement in the stream. The movement will only target the specified subset of axes in the stream.

Requires at least Firmware 7.11.

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `target_axes_indices` | `List[int]` | Indices of the axes in the stream the movement targets. Refers to the axes provided during the stream setup or further execution. Indices are zero-based. |
| `rotation_direction` | [`RotationDirection`](https://software.zaber.com/motion-library/api/py/root/rotationdirection.md) | The direction of the rotation. |
| `center_x` | [`Measurement`](https://software.zaber.com/motion-library/api/py/root/measurement.md) | The first dimension of the position of the center of the circle on which the arc exists. |
| `center_y` | [`Measurement`](https://software.zaber.com/motion-library/api/py/root/measurement.md) | The second dimension of the position of the center of the circle on which the arc exists. |
| `end_x` | [`Measurement`](https://software.zaber.com/motion-library/api/py/root/measurement.md) | The first dimension of the end position of the arc. |
| `end_y` | [`Measurement`](https://software.zaber.com/motion-library/api/py/root/measurement.md) | The second dimension of the end position of the arc. |

#### `call()` (async available)

`stream.call(stream_buffer)`

Append the actions in a stream buffer to the queue.

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `stream_buffer` | [`StreamBuffer`](https://software.zaber.com/motion-library/api/py/ascii/streambuffer.md) | The stream buffer to call. |

#### `check_disabled()` (async available)

`stream.check_disabled()`

Queries the stream status from the device and returns boolean indicating whether the stream is disabled. Useful to determine if streaming was interrupted by other movements.

##### Return Value

Type: `bool`

True if the stream is disabled.

#### `circle_absolute()` (async available)

`stream.circle_absolute(rotation_direction, center_x, center_y)`

Queue an absolute circle movement on the first two axes of the stream. Absolute meaning that the home positions of the axes are treated as the origin.

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `rotation_direction` | [`RotationDirection`](https://software.zaber.com/motion-library/api/py/root/rotationdirection.md) | The direction of the rotation. |
| `center_x` | [`Measurement`](https://software.zaber.com/motion-library/api/py/root/measurement.md) | The first dimension of the position of the center of the circle. |
| `center_y` | [`Measurement`](https://software.zaber.com/motion-library/api/py/root/measurement.md) | The second dimension of the position of the center of the circle. |

#### `circle_absolute_on()` (async available)

`stream.circle_absolute_on(target_axes_indices, rotation_direction, center_x, center_y)`

Queue an absolute circle movement in the stream. The movement will only target the specified subset of axes in the stream.

Requires at least Firmware 7.11.

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `target_axes_indices` | `List[int]` | Indices of the axes in the stream the movement targets. Refers to the axes provided during the stream setup or further execution. Indices are zero-based. |
| `rotation_direction` | [`RotationDirection`](https://software.zaber.com/motion-library/api/py/root/rotationdirection.md) | The direction of the rotation. |
| `center_x` | [`Measurement`](https://software.zaber.com/motion-library/api/py/root/measurement.md) | The first dimension of the position of the center of the circle. |
| `center_y` | [`Measurement`](https://software.zaber.com/motion-library/api/py/root/measurement.md) | The second dimension of the position of the center of the circle. |

#### `circle_relative()` (async available)

`stream.circle_relative(rotation_direction, center_x, center_y)`

Queue a relative circle movement on the first two axes of the stream. Relative meaning that the current position of the axes is treated as the origin.

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `rotation_direction` | [`RotationDirection`](https://software.zaber.com/motion-library/api/py/root/rotationdirection.md) | The direction of the rotation. |
| `center_x` | [`Measurement`](https://software.zaber.com/motion-library/api/py/root/measurement.md) | The first dimension of the position of the center of the circle. |
| `center_y` | [`Measurement`](https://software.zaber.com/motion-library/api/py/root/measurement.md) | The second dimension of the position of the center of the circle. |

#### `circle_relative_on()` (async available)

`stream.circle_relative_on(target_axes_indices, rotation_direction, center_x, center_y)`

Queue a relative circle movement in the stream. The movement will only target the specified subset of axes in the stream.

Requires at least Firmware 7.11.

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `target_axes_indices` | `List[int]` | Indices of the axes in the stream the movement targets. Refers to the axes provided during the stream setup or further execution. Indices are zero-based. |
| `rotation_direction` | [`RotationDirection`](https://software.zaber.com/motion-library/api/py/root/rotationdirection.md) | The direction of the rotation. |
| `center_x` | [`Measurement`](https://software.zaber.com/motion-library/api/py/root/measurement.md) | The first dimension of the position of the center of the circle. |
| `center_y` | [`Measurement`](https://software.zaber.com/motion-library/api/py/root/measurement.md) | The second dimension of the position of the center of the circle. |

#### `cork()` (async available)

`stream.cork()`

Cork the front of the stream'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 stream commands reaching the device late. You can only cork an idle live stream.

#### `disable()` (async available)

`stream.disable()`

Disables the stream. If the stream is not setup, this command does nothing. Once disabled, the stream will no longer accept stream commands. The stream will process the rest of the commands in the queue until it is empty.

#### `generic_command()` (async available)

`stream.generic_command(command)`

Sends a generic ASCII command to the stream. Keeps resending the command while the device rejects with AGAIN reason.

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `command` | `str` | Command and its parameters. |

#### `generic_command_batch()` (async available)

`stream.generic_command_batch(batch)`

Sends a batch of generic ASCII commands to the stream. Keeps resending command while the device rejects with AGAIN reason. The batch is atomic in terms of thread safety.

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `batch` | `List[str]` | Array of commands. |

#### `get_max_centripetal_acceleration()` (async available)

`stream.get_max_centripetal_acceleration(unit = Units.NATIVE)`

Gets the maximum centripetal acceleration of the live stream. Converts the units using the first axis of the stream.

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `unit` | [`AccelerationUnits`](https://software.zaber.com/motion-library/api/py/root/units.md) | Units of acceleration. |

##### Return Value

Type: `float`

The maximum centripetal acceleration of the live stream.

#### `get_max_speed()` (async available)

`stream.get_max_speed(unit = Units.NATIVE)`

Gets the maximum speed of the live stream. Converts the units using the first axis of the stream.

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `unit` | [`VelocityUnits`](https://software.zaber.com/motion-library/api/py/root/units.md) | Units of velocity. |

##### Return Value

Type: `float`

The maximum speed of the stream.

#### `get_max_tangential_acceleration()` (async available)

`stream.get_max_tangential_acceleration(unit = Units.NATIVE)`

Gets the maximum tangential acceleration of the live stream. Converts the units using the first axis of the stream.

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `unit` | [`AccelerationUnits`](https://software.zaber.com/motion-library/api/py/root/units.md) | Units of acceleration. |

##### Return Value

Type: `float`

The maximum tangential acceleration of the live stream.

#### `helix_absolute_on()` (async available)

`stream.helix_absolute_on(target_axes_indices, rotation_direction, center_x, center_y, end_x, end_y, *endpoint)`

Queue an absolute helix movement in the stream.

Requires at least Firmware 7.28.

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `target_axes_indices` | `List[int]` | Indices of the axes in the stream the movement targets. Refers to the axes provided during the stream setup or further execution. Indices are zero-based. The first two axes refer to the helix's arc component, while the rest refers to the helix's line component. |
| `rotation_direction` | [`RotationDirection`](https://software.zaber.com/motion-library/api/py/root/rotationdirection.md) | The direction of the rotation. |
| `center_x` | [`Measurement`](https://software.zaber.com/motion-library/api/py/root/measurement.md) | The first dimension of the position of the center of the circle on which the helix projects. |
| `center_y` | [`Measurement`](https://software.zaber.com/motion-library/api/py/root/measurement.md) | The second dimension of the position of the center of the circle on which the helix projects. |
| `end_x` | [`Measurement`](https://software.zaber.com/motion-library/api/py/root/measurement.md) | The first dimension of the end position of the helix's arc component. |
| `end_y` | [`Measurement`](https://software.zaber.com/motion-library/api/py/root/measurement.md) | The second dimension of the end position of the helix's arc component. |
| `*endpoint` | [`Measurement`](https://software.zaber.com/motion-library/api/py/root/measurement.md) | Positions for the helix's line component axes, relative to their home positions. |

#### `helix_relative_on()` (async available)

`stream.helix_relative_on(target_axes_indices, rotation_direction, center_x, center_y, end_x, end_y, *endpoint)`

Queue a relative helix movement in the stream.

Requires at least Firmware 7.28.

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `target_axes_indices` | `List[int]` | Indices of the axes in the stream the movement targets. Refers to the axes provided during the stream setup or further execution. Indices are zero-based. The first two axes refer to the helix's arc component, while the rest refers to the helix's line component. |
| `rotation_direction` | [`RotationDirection`](https://software.zaber.com/motion-library/api/py/root/rotationdirection.md) | The direction of the rotation. |
| `center_x` | [`Measurement`](https://software.zaber.com/motion-library/api/py/root/measurement.md) | The first dimension of the position of the center of the circle on which the helix projects. |
| `center_y` | [`Measurement`](https://software.zaber.com/motion-library/api/py/root/measurement.md) | The second dimension of the position of the center of the circle on which the helix projects. |
| `end_x` | [`Measurement`](https://software.zaber.com/motion-library/api/py/root/measurement.md) | The first dimension of the end position of the helix's arc component. |
| `end_y` | [`Measurement`](https://software.zaber.com/motion-library/api/py/root/measurement.md) | The second dimension of the end position of the helix's arc component. |
| `*endpoint` | [`Measurement`](https://software.zaber.com/motion-library/api/py/root/measurement.md) | Positions for the helix's line component axes, relative to their positions before movement. |

#### `ignore_current_discontinuity()`

`stream.ignore_current_discontinuity()`

Prevents StreamDiscontinuityException as a result of expected discontinuity when resuming streaming.

#### `is_busy()` (async available)

`stream.is_busy()`

Returns a boolean value indicating whether the live stream is executing a queued action.

##### Return Value

Type: `bool`

True if the stream is executing a queued action.

#### `line_absolute()` (async available)

`stream.line_absolute(*endpoint)`

Queue an absolute line movement in the stream.

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `*endpoint` | [`Measurement`](https://software.zaber.com/motion-library/api/py/root/measurement.md) | Positions for the axes to move to, relative to their home positions. |

#### `line_absolute_on()` (async available)

`stream.line_absolute_on(target_axes_indices, endpoint)`

Queue an absolute line movement in the stream, targeting a subset of the stream axes.

Requires at least Firmware 7.11.

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `target_axes_indices` | `List[int]` | Indices of the axes in the stream the movement targets. Refers to the axes provided during the stream setup or further execution. Indices are zero-based. |
| `endpoint` | [`List[Measurement]`](https://software.zaber.com/motion-library/api/py/root/measurement.md) | Positions for the axes to move to, relative to their home positions. |

#### `line_relative()` (async available)

`stream.line_relative(*endpoint)`

Queue a relative line movement in the stream.

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `*endpoint` | [`Measurement`](https://software.zaber.com/motion-library/api/py/root/measurement.md) | Positions for the axes to move to, relative to their positions before movement. |

#### `line_relative_on()` (async available)

`stream.line_relative_on(target_axes_indices, endpoint)`

Queue a relative line movement in the stream, targeting a subset of the stream axes.

Requires at least Firmware 7.11.

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `target_axes_indices` | `List[int]` | Indices of the axes in the stream the movement targets. Refers to the axes provided during the stream setup or further execution. Indices are zero-based. |
| `endpoint` | [`List[Measurement]`](https://software.zaber.com/motion-library/api/py/root/measurement.md) | Positions for the axes to move to, relative to their positions before movement. |

#### `set_hold()` (async available)

`stream.set_hold(hold)`

Pauses or resumes execution of the stream in live mode. The hold only takes effect during execution of motion segments.

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `hold` | `bool` | True to pause execution, false to resume. |

#### `set_max_centripetal_acceleration()` (async available)

`stream.set_max_centripetal_acceleration(max_centripetal_acceleration, unit = Units.NATIVE)`

Sets the maximum centripetal acceleration of the live stream. Converts the units using the first axis of the stream.

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `max_centripetal_acceleration` | `float` | Maximum centripetal acceleration at which any stream action is executed. |
| `unit` | [`AccelerationUnits`](https://software.zaber.com/motion-library/api/py/root/units.md) | Units of acceleration. |

#### `set_max_speed()` (async available)

`stream.set_max_speed(max_speed, unit = Units.NATIVE)`

Sets the maximum speed of the live stream. Converts the units using the first axis of the stream.

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `max_speed` | `float` | Maximum speed at which any stream action is executed. |
| `unit` | [`VelocityUnits`](https://software.zaber.com/motion-library/api/py/root/units.md) | Units of velocity. |

#### `set_max_tangential_acceleration()` (async available)

`stream.set_max_tangential_acceleration(max_tangential_acceleration, unit = Units.NATIVE)`

Sets the maximum tangential acceleration of the live stream. Converts the units using the first axis of the stream.

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `max_tangential_acceleration` | `float` | Maximum tangential acceleration at which any stream action is executed. |
| `unit` | [`AccelerationUnits`](https://software.zaber.com/motion-library/api/py/root/units.md) | Units of acceleration. |

#### `setup_live()` (async available)

`stream.setup_live(*axes)`

Setup the stream to control the specified axes and to queue actions on the device.

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `*axes` | `int` | Numbers of physical axes to setup the stream on. |

#### `setup_live_composite()` (async available)

`stream.setup_live_composite(*axes)`

Setup the stream to control the specified axes and to queue actions on the device. Allows use of lockstep axes in a stream.

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `*axes` | [`StreamAxisDefinition`](https://software.zaber.com/motion-library/api/py/ascii/streamaxisdefinition.md) | Definition of the stream axes. |

#### `setup_store()` (async available)

`stream.setup_store(stream_buffer, *axes)`

Setup the stream to control the specified axes and queue actions into a stream buffer.

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `stream_buffer` | [`StreamBuffer`](https://software.zaber.com/motion-library/api/py/ascii/streambuffer.md) | The stream buffer to queue actions in. |
| `*axes` | `int` | The axis numbers of the physical axes to setup the stream on. |

#### `setup_store_arbitrary_axes()` (async available)

`stream.setup_store_arbitrary_axes(stream_buffer, axes_count)`

Setup the stream to use a specified number of axes, and to queue actions in a stream buffer. Afterwards, you may call the resulting stream buffer on arbitrary axes. This mode does not allow for unit conversions.

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `stream_buffer` | [`StreamBuffer`](https://software.zaber.com/motion-library/api/py/ascii/streambuffer.md) | The stream buffer to queue actions in. |
| `axes_count` | `int` | The number of axes in the stream. |

#### `setup_store_composite()` (async available)

`stream.setup_store_composite(stream_buffer, *axes)`

Setup the stream to control the specified axes and queue actions into a stream buffer. Allows use of lockstep axes in a stream.

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `stream_buffer` | [`StreamBuffer`](https://software.zaber.com/motion-library/api/py/ascii/streambuffer.md) | The stream buffer to queue actions in. |
| `*axes` | [`StreamAxisDefinition`](https://software.zaber.com/motion-library/api/py/ascii/streamaxisdefinition.md) | Definition of the stream axes. |

#### `__repr__()`

`stream.__repr__()`

Returns a string which represents the stream.

##### Return Value

Type: `str`

String which represents the stream.

#### `treat_discontinuities_as_error()`

`stream.treat_discontinuities_as_error()`

Makes the stream throw StreamDiscontinuityException when it encounters discontinuities (ND warning flag).

#### `uncork()` (async available)

`stream.uncork()`

Uncork the front of the queue, unblocking command execution. You can only uncork an idle live stream that is corked.

#### `wait()` (async available)

`stream.wait(time, unit = Units.NATIVE)`

Wait a specified time.

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `time` | `float` | Amount of time to wait. |
| `unit` | [`TimeUnits`](https://software.zaber.com/motion-library/api/py/root/units.md) | Units of time. |

#### `wait_until_idle()` (async available)

`stream.wait_until_idle(throw_error_on_fault = True)`

Waits until the live stream executes all queued actions.

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `throw_error_on_fault` | `bool` | Determines whether to throw error when fault is observed. |
