# API Reference v10.3.1 (Python)

## Axis (class)

Module: zaber_motion.ascii

Represents an axis of motion associated with a device.

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)
axis = device.get_axis(1)
```

Related Guides:

- [Sending arbitrary commands](https://software.zaber.com/motion-library/docs/guides/library_features/arbitrary_commands.md)

### Properties

#### `axis_number` (read-only)

`axis.axis_number`

Type: `int`

The axis number identifies the axis on the device. The first axis has the number one.

#### `axis_type` (read-only)

`axis.axis_type`

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

Determines the type of an axis and units it accepts.

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

`axis.device`

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

Device that controls this axis.

#### `identity` (read-only)

`axis.identity`

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

Identity of the axis.

#### `is_peripheral` (read-only)

`axis.is_peripheral`

Type: `bool`

Indicates whether the axis is a peripheral or part of an integrated device.

#### `label` (read-only)

`axis.label`

Type: `str`

User-assigned label of the peripheral.

#### `peripheral_id` (read-only)

`axis.peripheral_id`

Type: `int`

Unique ID of the peripheral hardware.

#### `peripheral_name` (read-only)

`axis.peripheral_name`

Type: `str`

Name of the peripheral.

#### `peripheral_serial_number` (read-only)

`axis.peripheral_serial_number`

Type: `int`

Serial number of the peripheral, or 0 when not applicable.

#### `resolution` (read-only)

`axis.resolution`

Type: `int`

The number of microsteps per full step for motion axes. Always equal to 0 for non-motion axes.

#### `settings` (read-only)

`axis.settings`

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

Settings and properties of this axis.

#### `storage` (read-only)

`axis.storage`

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

Key-value storage of this axis. Requires at least Firmware 7.30.

#### `warnings` (read-only)

`axis.warnings`

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

Warnings and faults of this axis.

### Methods

#### `activate()` (async available)

`axis.activate()`

Activates a peripheral on this axis. Removes all identity information for the device. Run the identify method on the device after activating to refresh the information.

#### `driver_disable()` (async available)

`axis.driver_disable()`

Disables the driver, which prevents current from being sent to the motor or load. If the driver is already disabled, the driver remains disabled.

#### `driver_enable()` (async available)

`axis.driver_enable(timeout = 10)`

Attempts to enable the driver repeatedly for the specified timeout. If the driver is already enabled, the driver remains enabled.

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `timeout` | `float` | Timeout in seconds. Specify 0 to attempt to enable the driver once. |

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

`axis.generic_command(command, check_errors = True, timeout = 0)`

Sends a generic ASCII command to this axis. For more information refer to: [ASCII Protocol Manual](https://www.zaber.com/protocol-manual#topic_commands).

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `command` | `str` | Command and its parameters. |
| `check_errors` | `bool` | Controls whether to throw an exception when the device rejects the command. |
| `timeout` | `int` | The timeout, in milliseconds, for a device to respond to the command. Overrides the connection default request timeout. |

##### Return Value

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

A response to the command.

#### `generic_command_multi_response()` (async available)

`axis.generic_command_multi_response(command, check_errors = True, timeout = 0)`

Sends a generic ASCII command to this axis and expect multiple responses. Responses are returned in order of arrival. For more information refer to: [ASCII Protocol Manual](https://www.zaber.com/protocol-manual#topic_commands).

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `command` | `str` | Command and its parameters. |
| `check_errors` | `bool` | Controls whether to throw an exception when a device rejects the command. |
| `timeout` | `int` | The timeout, in milliseconds, for a device to respond to the command. Overrides the connection default request timeout. |

##### Return Value

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

All responses to the command.

#### `generic_command_no_response()` (async available)

`axis.generic_command_no_response(command)`

Sends a generic ASCII command to this axis without expecting a response and without adding a message ID For more information refer to: [ASCII Protocol Manual](https://www.zaber.com/protocol-manual#topic_commands).

##### Arguments

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

#### `get_command_unit_conversion_descriptors()`

`axis.get_command_unit_conversion_descriptors(command_template)`

Retrieves unit conversion descriptors for a command, allowing unit conversion without a device. The descriptors can be used with the ConvertTo/FromNativeUnits methods of the UnitTable class. Parameters in the command template are denoted by a question mark. For more information refer to: [ASCII Protocol Manual](https://www.zaber.com/protocol-manual#topic_commands).

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `command_template` | `str` | Template of the command. Parameters are denoted by question marks. |

##### Return Value

Type: [`List[Optional[UnitConversionDescriptor]]`](https://software.zaber.com/motion-library/api/py/root/unitconversiondescriptor.md)

Unit conversion descriptor for each parameter in the command. Nil if a parameter does not have conversion.

#### `get_index_position()` (async available)

`axis.get_index_position()`

Returns current axis index position.

##### Return Value

Type: `int`

Index position starting from 1 or 0 if the position is not an index position.

#### `get_number_of_index_positions()` (async available)

`axis.get_number_of_index_positions()`

Gets number of index positions of the axis.

##### Return Value

Type: `int`

Number of index positions.

#### `get_position()` (async available)

`axis.get_position(unit = Units.NATIVE)`

Returns current axis position.

##### Arguments

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

##### Return Value

Type: `float`

Axis position.

#### `get_state()` (async available)

`axis.get_state()`

Returns a serialization of the current axis state that can be saved and reapplied.

##### Return Value

Type: `str`

A serialization of the current state of the axis.

#### `has_command()`

`axis.has_command(command, allow_partial = False)`

Checks whether the axis supports the given command.

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `command` | `str` | Command to check. Parameters can be denoted by question marks, valid values, or the parameter name. |
| `allow_partial` | `bool` | If true, also matches commands that are a prefix of a supported command. |

##### Return Value

Type: `bool`

True if the command is supported.

#### `home()` (async available)

`axis.home(wait_until_idle = True)`

Homes axis. Axis returns to its homing position.

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `wait_until_idle` | `bool` | Determines whether the function waits for the movement to finish before returning. When false, you must call WaitUntilIdle afterwards to detect and handle any errors that occur during the movement. |

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

`axis.is_busy()`

Returns bool indicating whether the axis is executing a motion command.

##### Return Value

Type: `bool`

True if the axis is currently executing a motion command.

#### `is_homed()` (async available)

`axis.is_homed()`

Returns bool indicating whether the axis has position reference and was homed.

##### Return Value

Type: `bool`

True if the axis has position reference and was homed.

#### `is_parked()` (async available)

`axis.is_parked()`

Returns bool indicating whether the axis is parked or not.

##### Return Value

Type: `bool`

True if the axis is currently parked. False otherwise.

#### `move_absolute()` (async available)

`axis.move_absolute(position, unit = Units.NATIVE, wait_until_idle = True, velocity = 0, velocity_unit = Units.NATIVE, acceleration = 0, acceleration_unit = Units.NATIVE, cyclic_direction = None, extra_cycles = None)`

Move axis to absolute position.

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `position` | `float` | Absolute position. |
| `unit` | [`LengthUnits`](https://software.zaber.com/motion-library/api/py/root/units.md) | Units of position. |
| `wait_until_idle` | `bool` | Determines whether the function waits for the movement to finish before returning. When false, you must call WaitUntilIdle afterwards to detect and handle any errors that occur during the movement. |
| `velocity` | `float` | Movement velocity. Default value of 0 indicates that the maxspeed setting is used instead. |
| `velocity_unit` | [`VelocityUnits`](https://software.zaber.com/motion-library/api/py/root/units.md) | Units of velocity. |
| `acceleration` | `float` | Movement acceleration. Default value of 0 indicates that the accel setting is used instead. |
| `acceleration_unit` | [`AccelerationUnits`](https://software.zaber.com/motion-library/api/py/root/units.md) | Units of acceleration. |
| `cyclic_direction` | [`Optional[CyclicDirection]`](https://software.zaber.com/motion-library/api/py/root/cyclicdirection.md) | Which direction a cyclic device should take to get to the target position. |
| `extra_cycles` | `Optional[int]` | Number of extra cycles to complete before stopping at the target. |

#### `move_index()` (async available)

`axis.move_index(index, wait_until_idle = True, velocity = 0, velocity_unit = Units.NATIVE, acceleration = 0, acceleration_unit = Units.NATIVE)`

Moves the axis to index position.

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `index` | `int` | Index position. Index positions are numbered from 1. |
| `wait_until_idle` | `bool` | Determines whether the function waits for the movement to finish before returning. When false, you must call WaitUntilIdle afterwards to detect and handle any errors that occur during the movement. |
| `velocity` | `float` | Movement velocity. Default value of 0 indicates that the maxspeed setting is used instead. |
| `velocity_unit` | [`VelocityUnits`](https://software.zaber.com/motion-library/api/py/root/units.md) | Units of velocity. |
| `acceleration` | `float` | Movement acceleration. Default value of 0 indicates that the accel setting is used instead. |
| `acceleration_unit` | [`AccelerationUnits`](https://software.zaber.com/motion-library/api/py/root/units.md) | Units of acceleration. |

#### `move_max()` (async available)

`axis.move_max(wait_until_idle = True, velocity = 0, velocity_unit = Units.NATIVE, acceleration = 0, acceleration_unit = Units.NATIVE)`

Moves the axis to the maximum position as specified by limit.max.

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `wait_until_idle` | `bool` | Determines whether the function waits for the movement to finish before returning. When false, you must call WaitUntilIdle afterwards to detect and handle any errors that occur during the movement. |
| `velocity` | `float` | Movement velocity. Default value of 0 indicates that the maxspeed setting is used instead. |
| `velocity_unit` | [`VelocityUnits`](https://software.zaber.com/motion-library/api/py/root/units.md) | Units of velocity. |
| `acceleration` | `float` | Movement acceleration. Default value of 0 indicates that the accel setting is used instead. |
| `acceleration_unit` | [`AccelerationUnits`](https://software.zaber.com/motion-library/api/py/root/units.md) | Units of acceleration. |

#### `move_min()` (async available)

`axis.move_min(wait_until_idle = True, velocity = 0, velocity_unit = Units.NATIVE, acceleration = 0, acceleration_unit = Units.NATIVE)`

Moves the axis to the minimum position as specified by limit.min.

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `wait_until_idle` | `bool` | Determines whether the function waits for the movement to finish before returning. When false, you must call WaitUntilIdle afterwards to detect and handle any errors that occur during the movement. |
| `velocity` | `float` | Movement velocity. Default value of 0 indicates that the maxspeed setting is used instead. |
| `velocity_unit` | [`VelocityUnits`](https://software.zaber.com/motion-library/api/py/root/units.md) | Units of velocity. |
| `acceleration` | `float` | Movement acceleration. Default value of 0 indicates that the accel setting is used instead. |
| `acceleration_unit` | [`AccelerationUnits`](https://software.zaber.com/motion-library/api/py/root/units.md) | Units of acceleration. |

#### `move_relative()` (async available)

`axis.move_relative(position, unit = Units.NATIVE, wait_until_idle = True, velocity = 0, velocity_unit = Units.NATIVE, acceleration = 0, acceleration_unit = Units.NATIVE)`

Move axis to position relative to current position.

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `position` | `float` | Relative position. |
| `unit` | [`LengthUnits`](https://software.zaber.com/motion-library/api/py/root/units.md) | Units of position. |
| `wait_until_idle` | `bool` | Determines whether the function waits for the movement to finish before returning. When false, you must call WaitUntilIdle afterwards to detect and handle any errors that occur during the movement. |
| `velocity` | `float` | Movement velocity. Default value of 0 indicates that the maxspeed setting is used instead. |
| `velocity_unit` | [`VelocityUnits`](https://software.zaber.com/motion-library/api/py/root/units.md) | Units of velocity. |
| `acceleration` | `float` | Movement acceleration. Default value of 0 indicates that the accel setting is used instead. |
| `acceleration_unit` | [`AccelerationUnits`](https://software.zaber.com/motion-library/api/py/root/units.md) | Units of acceleration. |

#### `move_sin()` (async available)

`axis.move_sin(amplitude, amplitude_units, period, period_units, count = 0, wait_until_idle = True)`

Moves the axis in a sinusoidal trajectory.

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `amplitude` | `float` | Amplitude of the sinusoidal motion (half of the motion's peak-to-peak range). |
| `amplitude_units` | [`LengthUnits`](https://software.zaber.com/motion-library/api/py/root/units.md) | Units of position. |
| `period` | `float` | Period of the sinusoidal motion. |
| `period_units` | [`TimeUnits`](https://software.zaber.com/motion-library/api/py/root/units.md) | Units of time. |
| `count` | `float` | Number of sinusoidal cycles to complete. Must be a multiple of 0.5 If count is not specified or set to 0, the axis will move indefinitely. |
| `wait_until_idle` | `bool` | Determines whether the function waits for the movement to finish before returning. When false, you must call WaitUntilIdle afterwards to detect and handle any errors that occur during the movement. |

#### `move_sin_stop()` (async available)

`axis.move_sin_stop(wait_until_idle = True)`

Stops the axis at the end of the sinusoidal trajectory. If the sinusoidal motion was started with an integer-plus-half cycle count, the motion ends at the half-way point of the sinusoidal trajectory.

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `wait_until_idle` | `bool` | Determines whether the function waits for the movement to finish before returning. When false, you must call WaitUntilIdle afterwards to detect and handle any errors that occur during the movement. |

#### `move_velocity()` (async available)

`axis.move_velocity(velocity, unit = Units.NATIVE, acceleration = 0, acceleration_unit = Units.NATIVE)`

Begins to move axis at specified speed.

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `velocity` | `float` | Movement velocity. |
| `unit` | [`VelocityUnits`](https://software.zaber.com/motion-library/api/py/root/units.md) | Units of velocity. |
| `acceleration` | `float` | Movement acceleration. Default value of 0 indicates that the accel setting is used instead. |
| `acceleration_unit` | [`AccelerationUnits`](https://software.zaber.com/motion-library/api/py/root/units.md) | Units of acceleration. |

#### `park()` (async available)

`axis.park()`

Parks the axis in anticipation of turning the power off. It can later be powered on, unparked, and moved without first having to home it.

#### `prepare_command()`

`axis.prepare_command(command_template, *parameters)`

Formats parameters into a command and performs unit conversions. Parameters in the command template are denoted by a question mark. Command returned is only valid for this axis and this device. For more information refer to: [ASCII Protocol Manual](https://www.zaber.com/protocol-manual#topic_commands).

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `command_template` | `str` | Template of a command to prepare. Parameters are denoted by question marks. |
| `*parameters` | [`Measurement`](https://software.zaber.com/motion-library/api/py/root/measurement.md) | Variable number of command parameters. |

##### Return Value

Type: `str`

Command with converted parameters.

#### `restore()` (async available)

`axis.restore()`

Restores all axis settings to their default values. Deletes all zaber axis storage keys. Disables lockstep if the axis is part of one. Unparks the axis. Preserves storage. The device needs to be identified again after the restore.

#### `set_label()` (async available)

`axis.set_label(label)`

Sets the user-assigned peripheral label. The label is stored on the controller and recognized by other software.

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `label` | `str` | Label to set. |

#### `set_state()` (async available)

`axis.set_state(state)`

Applies a saved state to this axis.

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `state` | `str` | The state object to apply to this axis. |

##### Return Value

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

Reports of any issues that were handled, but caused the state to not be exactly restored.

#### `stop()` (async available)

`axis.stop(wait_until_idle = True)`

Stops ongoing axis movement. Decelerates until zero speed.

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `wait_until_idle` | `bool` | Determines whether the function waits for the movement to finish before returning. When false, you must call WaitUntilIdle afterwards to detect and handle any errors that occur during the movement. |

#### `__repr__()`

`axis.__repr__()`

Returns a string that represents the axis.

##### Return Value

Type: `str`

A string that represents the axis.

#### `unpark()` (async available)

`axis.unpark()`

Unparks axis. Axis will now be able to move.

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

`axis.wait_until_idle(throw_error_on_fault = True)`

Waits until axis stops moving.

##### Arguments

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