# API Reference v10.3.1 (Python)

## DeviceSettings (class)

Module: zaber_motion.ascii

Class providing access to various device settings and properties.

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)
device_settings = device.settings
```

Related Guides:

- [Arbitrary unit conversions](https://software.zaber.com/motion-library/docs/guides/library_features/settings_unit_conversion.md)
- [Settings](https://software.zaber.com/motion-library/docs/guides/device_features/settings.md)

### Methods

#### `can_convert_native_units()`

`device_settings.can_convert_native_units(setting)`

Indicates if given setting can be converted from and to native units.

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `setting` | `str` | Name of the setting. |

##### Return Value

Type: `bool`

True if unit conversion can be performed.

#### `convert_from_native_units()`

`device_settings.convert_from_native_units(setting, value, unit)`

Convert arbitrary setting value from Zaber native units.

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `setting` | `str` | Name of the setting. |
| `value` | `float` | Value of the setting in Zaber native units. |
| `unit` | [`UnitsAndLiterals`](https://software.zaber.com/motion-library/api/py/root/units.md) | Units to convert value to. |

##### Return Value

Type: `float`

Setting value.

#### `convert_to_native_units()`

`device_settings.convert_to_native_units(setting, value, unit, round = False)`

Convert arbitrary setting value to Zaber native units.

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `setting` | `str` | Name of the setting. |
| `value` | `float` | Value of the setting in units specified by following argument. |
| `unit` | [`UnitsAndLiterals`](https://software.zaber.com/motion-library/api/py/root/units.md) | Units of the value. |
| `round` | `bool` | If true, round the result to the device's native decimal places. |

##### Return Value

Type: `float`

Setting value.

#### `get()` (async available)

`device_settings.get(setting, unit = Units.NATIVE)`

Returns any device setting or property. For more information refer to the [ASCII Protocol Manual](https://www.zaber.com/protocol-manual#topic_settings).

##### Arguments

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

##### Return Value

Type: `float`

Setting value.

#### `get_bool()` (async available)

`device_settings.get_bool(setting)`

Returns any device setting or property as a boolean. For more information refer to the [ASCII Protocol Manual](https://www.zaber.com/protocol-manual#topic_settings).

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `setting` | `str` | Name of the setting. |

##### Return Value

Type: `bool`

Setting value.

#### `get_default()`

`device_settings.get_default(setting, unit = Units.NATIVE)`

Returns the default value of a setting.

##### Arguments

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

##### Return Value

Type: `float`

Default setting value.

#### `get_default_bool()`

`device_settings.get_default_bool(setting)`

Returns the default value of a setting as a boolean.

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `setting` | `str` | Name of the setting. |

##### Return Value

Type: `bool`

Default setting value.

#### `get_default_int()`

`device_settings.get_default_int(setting)`

Returns the default value of a setting as an integer.

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `setting` | `str` | Name of the setting. |

##### Return Value

Type: `int`

Default setting value.

#### `get_default_string()`

`device_settings.get_default_string(setting)`

Returns the default value of a setting as a string.

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `setting` | `str` | Name of the setting. |

##### Return Value

Type: `str`

Default setting value.

#### `get_from_all_axes()` (async available)

`device_settings.get_from_all_axes(setting)`

Gets the value of an axis scope setting for each axis on the device. Values may be NaN where the setting is not applicable.

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `setting` | `str` | Name of the setting. |

##### Return Value

Type: `List[float]`

The setting values on each axis.

#### `get_int()` (async available)

`device_settings.get_int(setting)`

Returns any device setting or property as an integer. For more information refer to the [ASCII Protocol Manual](https://www.zaber.com/protocol-manual#topic_settings).

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `setting` | `str` | Name of the setting. |

##### Return Value

Type: `int`

Setting value.

#### `get_many()` (async available)

`device_settings.get_many(*settings)`

Gets many setting values in as few device requests as possible. A returned value is NaN when the device responds with NA, indicating the setting is not supported by the device or an axis.

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `*settings` | [`GetSetting`](https://software.zaber.com/motion-library/api/py/ascii/getsetting.md) | The settings to read. |

##### Return Value

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

The setting values read.

#### `get_many_typed()` (async available)

`device_settings.get_many_typed(*settings)`

Returns many device settings or properties in their native types in as few requests as possible. Note that specifying units will always return floating point values, even for settings that are natively integers. For more information refer to the [ASCII Protocol Manual](https://www.zaber.com/protocol-manual#topic_settings).

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `*settings` | [`GetSetting`](https://software.zaber.com/motion-library/api/py/ascii/getsetting.md) | The settings to read. |

##### Return Value

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

The setting values read.

#### `get_string()` (async available)

`device_settings.get_string(setting)`

Returns any device setting or property as a string. For more information refer to the [ASCII Protocol Manual](https://www.zaber.com/protocol-manual#topic_settings).

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `setting` | `str` | Name of the setting. |

##### Return Value

Type: `str`

Setting value.

#### `get_synchronized()` (async available)

`device_settings.get_synchronized(*settings)`

Gets many setting values in the same tick, ensuring their values are synchronized.

Requires at least Firmware 7.35.

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `*settings` | [`GetSetting`](https://software.zaber.com/motion-library/api/py/ascii/getsetting.md) | The settings to read. |

##### Return Value

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

The setting values read.

#### `get_typed()` (async available)

`device_settings.get_typed(setting, unit = Units.NATIVE)`

Returns any device setting or property in its native type. Note that specifying units will cause settings that are otherwise integers to be returned as floats. For more information refer to the [ASCII Protocol Manual](https://www.zaber.com/protocol-manual#topic_settings).

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `setting` | `str` | Name of the setting. |
| `unit` | [`UnitsAndLiterals`](https://software.zaber.com/motion-library/api/py/root/units.md) | Units of setting to convert result to. |

##### Return Value

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

Setting value.

#### `get_unit_conversion_descriptor()`

`device_settings.get_unit_conversion_descriptor(setting)`

Retrieves unit conversion descriptor for a setting, allowing unit conversion without a device. The descriptor can be used with the ConvertTo/FromNativeUnits methods of the UnitTable class.

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `setting` | `str` | Name of the setting. |

##### Return Value

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

The unit conversion descriptor for the setting.

#### `has_setting()`

`device_settings.has_setting(setting)`

Indicates whether the specified setting exists on this device.

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `setting` | `str` | Name of the setting. |

##### Return Value

Type: `bool`

True if the setting exists on this device.

#### `set()` (async available)

`device_settings.set(setting, value, unit = Units.NATIVE)`

Sets any device setting. For more information refer to the [ASCII Protocol Manual](https://www.zaber.com/protocol-manual#topic_settings).

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `setting` | `str` | Name of the setting. |
| `value` | `float` | Value of the setting. |
| `unit` | [`UnitsAndLiterals`](https://software.zaber.com/motion-library/api/py/root/units.md) | Units of setting. |

#### `set_bool()` (async available)

`device_settings.set_bool(setting, value)`

Sets any device setting as a boolean. For more information refer to the [ASCII Protocol Manual](https://www.zaber.com/protocol-manual#topic_settings).

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `setting` | `str` | Name of the setting. |
| `value` | `bool` | Value of the setting. |

#### `set_int()` (async available)

`device_settings.set_int(setting, value)`

Sets any device setting or property as an integer. For more information refer to the [ASCII Protocol Manual](https://www.zaber.com/protocol-manual#topic_settings).

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `setting` | `str` | Name of the setting. |
| `value` | `int` | Value of the setting. |

#### `set_string()` (async available)

`device_settings.set_string(setting, value)`

Sets any device setting as a string. For more information refer to the [ASCII Protocol Manual](https://www.zaber.com/protocol-manual#topic_settings).

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `setting` | `str` | Name of the setting. |
| `value` | `str` | Value of the setting. |
