# API Reference v10.3.1 (Python)

## Connection (class)

Module: zaber_motion.ascii

Class representing access to particular connection (serial port, TCP connection).

The following examples illustrate how you can obtain an instance of this type:

```py
from zaber_motion.ascii import Connection

connection = Connection.open_serial_port("COM3")
```

```py
from zaber_motion.ascii import Connection

connection = Connection.open_tcp("zaber-12345.local")
```

```py
from zaber_motion.ascii import Connection

connection = Connection.open_iot("xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx")
```

```py
from zaber_motion.ascii import Connection

connection = Connection.open_network_share("localhost")
```

```py
from zaber_motion.ascii import Connection
from zaber_motion.ascii import Transport

transport = Transport.open()
connection = Connection.open_custom(transport)
```

Related Guides:

- [Custom transports](https://software.zaber.com/motion-library/docs/guides/advanced/custom_transports.md)
- [Events](https://software.zaber.com/motion-library/docs/guides/library_features/events.md)
- [Sending arbitrary commands](https://software.zaber.com/motion-library/docs/guides/library_features/arbitrary_commands.md)
- [TCP/IP (network) communication](https://software.zaber.com/motion-library/docs/guides/communication/tcp.md)
- [Virtual devices](https://software.zaber.com/motion-library/docs/guides/product_specific/virtual_device.md)

### Constants

#### `DEFAULT_BAUD_RATE`

`Connection.DEFAULT_BAUD_RATE`

Type: `int`

Default baud rate for serial connections.

##### Value

`115200`

#### `NETWORK_SHARE_PORT`

`Connection.NETWORK_SHARE_PORT`

Type: `int`

Local area network share port.

##### Value

`11421`

#### `TCP_PORT_CHAIN`

`Connection.TCP_PORT_CHAIN`

Type: `int`

Commands sent over this port are forwarded to the device chain. The bandwidth may be limited as the commands are forwarded over a serial connection.

##### Value

`55550`

#### `TCP_PORT_DEVICE_ONLY`

`Connection.TCP_PORT_DEVICE_ONLY`

Type: `int`

Commands send over this port are processed only by the device and not forwarded to the rest of the chain. Using this port typically makes the communication faster.

##### Value

`55551`

### Properties

#### `checksum_enabled`

`connection.checksum_enabled`

Type: `bool`

Controls whether outgoing messages contain checksum.

#### `default_request_timeout`

`connection.default_request_timeout`

Type: `int`

The default timeout, in milliseconds, for a device to respond to a request. Setting the timeout to a too low value may cause request timeout exceptions. The initial value is 1000 (one second).

#### `interface_id` (read-only)

`connection.interface_id`

Type: `int`

The interface ID identifies this Connection instance with the underlying library.

#### `is_open` (read-only)

`connection.is_open`

Type: `bool`

Returns whether the connection is open. Does not guarantee that subsequent requests will succeed.

### Events

#### `alert`

`connection.alert`

Event invoked when an alert is received from a device.

##### Emitted Data

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

Alert message received from the device.

#### `disconnected`

`connection.disconnected`

Event invoked when connection is interrupted or closed.

##### Emitted Data

Type: [`MotionLibException`](https://software.zaber.com/motion-library/api/py/exceptions/motionlibexception.md)

Error that caused disconnection.

#### `unknown_response`

`connection.unknown_response`

Event invoked when a response from a device cannot be matched to any known request.

##### Emitted Data

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

Reply that could not be matched to a request.

### Methods

#### `close()` (async available)

`connection.close()`

Close the connection.

#### `detect_devices()` (async available)

`connection.detect_devices(identify_devices = True)`

Attempts to detect any devices present on this connection.

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `identify_devices` | `bool` | Determines whether device identification should be performed as well. |

##### Return Value

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

Array of detected devices.

#### `disable_alerts()` (async available)

`connection.disable_alerts()`

Disables alerts for all devices on the connection. This will change the "comm.alert" setting to 0 on all supported devices.

#### `enable_alerts()` (async available)

`connection.enable_alerts()`

Enables alerts for all devices on the connection. This will change the "comm.alert" setting to 1 on all supported devices.

#### `forget_devices()`

`connection.forget_devices(except_devices = [])`

Forgets all the information associated with devices on the connection. Useful when devices are removed from the chain indefinitely.

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `except_devices` | `List[int]` | Addresses of devices that should not be forgotten. |

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

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

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

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `command` | `str` | Command and its parameters. |
| `device` | `int` | Optional device address to send the command to. |
| `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)

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

Sends a generic ASCII command to this connection and expect multiple responses, either from one device or from many devices. Responses are returned in order of arrival. For more information refer to the [ASCII Protocol Manual](https://www.zaber.com/protocol-manual#topic_commands).

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `command` | `str` | Command and its parameters. |
| `device` | `int` | Optional device address to send the command to. |
| `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)

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

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

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `command` | `str` | Command and its parameters. |
| `device` | `int` | Optional device address to send the command to. Specifying -1 omits the number completely. |
| `axis` | `int` | Optional axis number to send the command to. Specifying -1 omits the number completely. |

#### `get_device()`

`connection.get_device(device_address)`

Gets a Device class instance which allows you to control a particular device on this connection. Devices are numbered from 1.

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `device_address` | `int` | Address of device intended to control. Address is configured for each device. |

##### Return Value

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

Device instance.

#### `home_all()` (async available)

`connection.home_all(wait_until_idle = True)`

Homes all of the devices on this connection.

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `wait_until_idle` | `bool` | Determines whether the function should return immediately or wait until the devices are homed. When false, you must call WaitUntilIdle on each underlying axis afterwards to detect and handle any errors that occur during the movement. |

##### Return Value

Type: `List[int]`

The addresses of the devices that were homed by this command.

(static)

#### `open_custom()` (async available)

`Connection.open_custom(transport)`

Opens a connection using a custom transport.

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `transport` | [`Transport`](https://software.zaber.com/motion-library/api/py/ascii/transport.md) | The custom connection transport. |

##### Return Value

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

An object representing the connection.

(static)

#### `open_iot()` (async available)

`Connection.open_iot(cloud_id, token = "unauthenticated", connection_name = None, realm = None, api = "https://api.zaber.io")`

Opens a secured connection to a cloud connected device chain. Use this method to connect to devices on your account.

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `cloud_id` | `str` | The cloud ID to connect to. |
| `token` | `str` | The token to authenticate with. By default the connection will be unauthenticated. |
| `connection_name` | `Optional[str]` | The ID or name of the connection to open. Can be left empty to default to the only connection present. The ID is the serial port name for serial port connections or hostname:port for TCP connections. The name is the one shown for the connection in Zaber Launcher. |
| `realm` | `Optional[str]` | The realm to connect to. Can be left empty for the default account realm. |
| `api` | `str` | The URL of the API to receive connection info from. |

##### Return Value

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

An object representing the connection.

(static)

#### `open_network_share()` (async available)

`Connection.open_network_share(host_name, port = NETWORK_SHARE_PORT, connection_name = None)`

Opens a connection to Zaber Launcher in your Local Area Network. The connection is not secured.

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `host_name` | `str` | Hostname or IP address. |
| `port` | `int` | Port number. |
| `connection_name` | `Optional[str]` | The ID or name of the connection to open. Can be left empty to default to the only connection present. The ID is the serial port name for serial port connections or hostname:port for TCP connections. The name is the one shown for the connection in Zaber Launcher. |

##### Return Value

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

An object representing the connection.

(static)

#### `open_serial_port()` (async available)

`Connection.open_serial_port(port_name, baud_rate = DEFAULT_BAUD_RATE, direct = False, test_port = False, exclusive = False)`

Opens a serial port, if Zaber Launcher controls the port, the port will be opened through Zaber Launcher. Zaber Launcher allows sharing of the port between multiple applications, If port sharing is not desirable, use the `direct` parameter.

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `port_name` | `str` | Name of the port to open. |
| `baud_rate` | `int` | Optional baud rate (defaults to 115200). |
| `direct` | `bool` | If true will connect to the serial port directly, failing if the connection is already opened by a message router instance. |
| `test_port` | `bool` | Some operating systems may allow opening a serial port that is not writable. Tests if the serial port is writable, and throws an exception if it is not. |
| `exclusive` | `bool` | If true, the port is opened for exclusive use, disconnecting any other application that shares the port through Zaber Launcher. Has no effect on a direct connection, which is always exclusive. |

##### Return Value

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

An object representing the port.

(static)

#### `open_tcp()` (async available)

`Connection.open_tcp(host_name, port = TCP_PORT_CHAIN)`

Opens a TCP connection.

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `host_name` | `str` | Hostname or IP address. |
| `port` | `int` | Optional port number (defaults to 55550). |

##### Return Value

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

An object representing the connection.

#### `renumber_devices()` (async available)

`connection.renumber_devices(first_address = 1)`

Renumbers devices present on this connection. After renumbering, devices need to be identified again.

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `first_address` | `int` | This is the address that the device closest to the computer is given. Remaining devices are numbered consecutively. |

##### Return Value

Type: `int`

Total number of devices that responded to the renumber.

#### `reopen()` (async available)

`connection.reopen()`

Reopens the connection. To continue using events on the connection, you must resubscribe to event observables. Throws an exception if the connection is already open.

#### `stop_all()` (async available)

`connection.stop_all(wait_until_idle = True)`

Stops all of the devices on this connection.

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `wait_until_idle` | `bool` | Determines whether the function should return immediately or wait until the devices are stopped. When false, you must call WaitUntilIdle on each underlying axis afterwards to detect and handle any errors that occur during the movement. |

##### Return Value

Type: `List[int]`

The addresses of the devices that were stopped by this command.

#### `__repr__()`

`connection.__repr__()`

Returns a string that represents the connection.

##### Return Value

Type: `str`

A string that represents the connection.
