# API Reference v10.3.1 (Python)

## Device (class)

Module: zaber_motion.ascii

Represents the controller part of one device - may be either a standalone controller or an integrated controller.

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)
```

Related Guides:

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

### Properties

#### `all_axes` (read-only)

`device.all_axes`

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

Virtual axis which allows you to target all axes of this device.

#### `axis_count` (read-only)

`device.axis_count`

Type: `int`

Number of axes this device has.

#### `connection` (read-only)

`device.connection`

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

Connection of this device.

#### `device_address` (read-only)

`device.device_address`

Type: `int`

The device address uniquely identifies the device on the connection. It can be configured or automatically assigned by the renumber command.

#### `device_id` (read-only)

`device.device_id`

Type: `int`

Unique ID of the device hardware.

#### `firmware_version` (read-only)

`device.firmware_version`

Type: [`FirmwareVersion`](https://software.zaber.com/motion-library/api/py/root/firmwareversion.md)

Version of the firmware.

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

`device.identity`

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

Identity of the device.

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

`device.io`

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

I/O channels of this device.

#### `is_identified` (read-only)

`device.is_identified`

Type: `bool`

Indicates whether or not the device has been identified.

#### `is_integrated` (read-only)

`device.is_integrated`

Type: `bool`

The device is an integrated product.

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

`device.label`

Type: `str`

User-assigned label of the device.

#### `name` (read-only)

`device.name`

Type: `str`

Name of the product.

#### `oscilloscope` (read-only)

`device.oscilloscope`

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

Oscilloscope recording helper for this device. Requires at least Firmware 7.00.

#### `pvt` (read-only)

`device.pvt`

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

Gets an object that provides access to PVT functions of this device. Note that as of ZML v5.0.0, this returns a Pvt object and NOT a PvtSequence object. The PvtSequence can now be obtained from the Pvt object. Requires at least Firmware 7.33.

#### `serial_number` (read-only)

`device.serial_number`

Type: `int`

Serial number of the device.

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

`device.settings`

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

Settings and properties of this device.

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

`device.storage`

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

Key-value storage of this device.

#### `streams` (read-only)

`device.streams`

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

Gets an object that provides access to Streams on this device. Requires at least Firmware 7.05.

#### `triggers` (read-only)

`device.triggers`

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

Triggers for this device. Requires at least Firmware 7.06.

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

`device.warnings`

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

Warnings and faults of this device and all its axes.

### Methods

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

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

Sends a generic ASCII command to this device. 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. |
| `axis` | `int` | Optional axis number to send the command to. |
| `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)

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

Sends a generic ASCII command to this device 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. |
| `axis` | `int` | Optional axis number to send the command to. |
| `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)

`device.generic_command_no_response(command, axis = 0)`

Sends a generic ASCII command to this device 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. |
| `axis` | `int` | Optional axis number to send the command to. Specifying -1 omits the number completely. |

#### `get_axis()`

`device.get_axis(axis_number)`

Gets an Axis class instance which allows you to control a particular axis on this device. Axes are numbered from 1.

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `axis_number` | `int` | Number of axis intended to control. |

##### Return Value

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

Axis instance.

#### `get_command_unit_conversion_descriptors()`

`device.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_lockstep()`

`device.get_lockstep(lockstep_group_id)`

Gets a Lockstep class instance which allows you to control a particular lockstep group on the device.

Requires at least Firmware 6.15 or 7.11.

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `lockstep_group_id` | `int` | The ID of the lockstep group to control. Lockstep group IDs start at one. |

##### Return Value

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

Lockstep instance.

#### `get_lockstep_info()` (async available)

`device.get_lockstep_info(unit = Units.NATIVE)`

Gets information about all lockstep groups enabled on the device.

Requires at least Firmware 6.15 or 7.11.

##### Arguments

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

##### Return Value

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

Information about each enabled lockstep group.

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

`device.get_state()`

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

##### Return Value

Type: `str`

A serialization of the current state of the device.

#### `has_command()`

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

Checks whether the device 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.

#### `identify()` (async available)

`device.identify(assume_version = None)`

Queries the device and the database, gathering information about the product. Without this information features such as unit conversions will not work. Usually, called automatically by detect devices method.

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `assume_version` | [`Optional[FirmwareVersion]`](https://software.zaber.com/motion-library/api/py/root/firmwareversion.md) | The identification assumes the specified firmware version instead of the version queried from the device. Providing this argument can lead to unexpected compatibility issues. |

##### Return Value

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

Device identification data.

#### `prepare_command()`

`device.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 device. Unit conversion is not supported for commands where axes can be remapped, such as stream and PVT commands. 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.

#### `renumber()` (async available)

`device.renumber(address)`

Changes the address of this device. After the address is successfully changed, the existing device instance no longer represents the device. Instead, use the new device instance returned by this method. The identity of this device is discarded, and the new device needs to be identified before using it.

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `address` | `int` | The new address to assign to the device. |

##### Return Value

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

New device instance with the new address.

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

`device.restore(hard = False)`

Restores most of the settings to their default values. Deletes all triggers, stream and PVT buffers, servo tunings. Deletes all zaber storage keys. Disables locksteps, unparks axes. Preserves storage, communication settings, peripherals (unless hard is specified). The device needs to be identified again after the restore.

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `hard` | `bool` | If true, completely erases device's memory. The device also resets. |

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

`device.set_label(label)`

Sets the user-assigned device 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)

`device.set_state(state, device_only = False)`

Applies a saved state to this device.

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `state` | `str` | The state object to apply to this device. |
| `device_only` | `bool` | If true, only device scope settings and features will be set. |

##### Return Value

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

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

#### `__repr__()`

`device.__repr__()`

Returns a string that represents the device.

##### Return Value

Type: `str`

A string that represents the device.
