# API Reference v10.3.1 (Python)

## Connection (class)

Module: zaber_motion.binary

Class representing access to particular connection (serial port, TCP connection) using the legacy Binary protocol.

To use this type, add `from zaber_motion.binary import Connection` to the top of your source code.

### Constants

#### `DEFAULT_BAUD_RATE`

`Connection.DEFAULT_BAUD_RATE`

Type: `int`

Default baud rate for serial connections.

##### Value

`9600`

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

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

`connection.interface_id`

Type: `int`

The interface ID identifies thisConnection instance with the underlying library.

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

`connection.is_open`

Type: `bool`

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

### Events

#### `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.

#### `reply_only`

`connection.reply_only`

Event invoked when a reply-only command such as a move tracking message is received from a device.

##### Emitted Data

Type: [`ReplyOnlyEvent`](https://software.zaber.com/motion-library/api/py/binary/replyonlyevent.md)

Reply-only message received from the device.

#### `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/binary/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/binary/device.md)

Array of detected devices.

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

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

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

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `device` | `int` | Device address to send the command to. Use zero for broadcast. |
| `command` | [`CommandCode`](https://software.zaber.com/motion-library/api/py/binary/commandcode.md) | Command to send. |
| `data` | `int` | Optional data argument to the command. Defaults to zero. |
| `timeout` | `float` | Number of seconds to wait for a response from the device. 0 or negative defaults to 0.5s. |
| `check_errors` | `bool` | Controls whether to throw an exception when the device rejects the command. |

##### Return Value

Type: [`Message`](https://software.zaber.com/motion-library/api/py/binary/message.md)

A response to the command.

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

`connection.generic_command_multi_response(command, data = 0, timeout = 0.0, check_errors = True)`

Sends a generic Binary command to this connection and expects responses from one or more devices. Responses are returned in order of arrival. For more information please refer to the [Binary Protocol Manual](https://www.zaber.com/protocol-manual?protocol=Binary#topic_quick_command_reference).

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `command` | [`CommandCode`](https://software.zaber.com/motion-library/api/py/binary/commandcode.md) | Command to send. |
| `data` | `int` | Optional data argument to the command. Defaults to zero. |
| `timeout` | `float` | Number of seconds to wait for all responses from the device chain. 0 or negative defaults to 0.5s. |
| `check_errors` | `bool` | Controls whether to throw an exception when any device rejects the command. |

##### Return Value

Type: [`List[Message]`](https://software.zaber.com/motion-library/api/py/binary/message.md)

All responses to the command.

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

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

Sends a generic Binary command to this connection without expecting a response. For more information please refer to the [Binary Protocol Manual](https://www.zaber.com/protocol-manual?protocol=Binary#topic_quick_command_reference).

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `device` | `int` | Device address to send the command to. Use zero for broadcast. |
| `command` | [`CommandCode`](https://software.zaber.com/motion-library/api/py/binary/commandcode.md) | Command to send. |
| `data` | `int` | Optional data argument to the command. Defaults to zero. |

#### `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/binary/device.md)

Device instance.

(static)

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

`Connection.open_serial_port(port_name, baud_rate = DEFAULT_BAUD_RATE, use_message_ids = False)`

Opens a serial port.

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `port_name` | `str` | Name of the port to open. |
| `baud_rate` | `int` | Optional baud rate (defaults to 9600). |
| `use_message_ids` | `bool` | Enable use of message IDs (defaults to disabled). All your devices must be pre-configured to match. |

##### Return Value

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

An object representing the port.

(static)

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

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

Opens a TCP connection.

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `host_name` | `str` | Hostname or IP address. |
| `port` | `int` | Optional port number (defaults to 55550). |
| `use_message_ids` | `bool` | Enable use of message IDs (defaults to disabled). All your devices must be pre-configured to match. |

##### Return Value

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

An object representing the connection.

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

`connection.renumber_devices()`

Renumbers devices present on this connection. After renumbering, you must identify devices again.

##### Return Value

Type: `int`

Total number of devices that responded to the renumber.

#### `__repr__()`

`connection.__repr__()`

Returns a string that represents the connection.

##### Return Value

Type: `str`

A string that represents the connection.
