Zaber Motion LibraryGetting StartedHow-to GuidesSupportBinary Protocol (Legacy)
API Reference
zaber_motion.ascii
AlertEventAllAxesAxisAxisGroupAxisIdentityAxisSettingsAxisStorageAxisTypeConnectionConversionFactorDeviceDeviceIdentityDeviceIODeviceIOInfoDeviceSettingsDeviceStorageDigitalOutputActionGetAxisSettingGetAxisSettingResultGetAxisSettingTypedResultGetSettingGetSettingResultGetSettingTypedResultIoPortLabelIoPortTypeLockstepMeasurementSequenceMessageTypeOscilloscopeOscilloscopeCapturePropertiesOscilloscopeDataOscilloscopeDataSourceParamsetInfoPidTuningPvtPvtAxisDefinitionPvtAxisTypePvtBufferPvtBufferAxisUnitsPvtCallActionPvtCancelAllOutputsScheduleActionPvtCancelOutputScheduleActionPvtCsvDataPvtIoPvtModePvtPartialCsvDataPvtPartialPointPvtPartialSequenceItemPvtPointPvtSequencePvtSequenceItemPvtSetAllAnalogOutputsActionPvtSetAllDigitalOutputsActionPvtSetAnalogOutputActionPvtSetDigitalOutputActionResponseServoTunerServoTuningParamServoTuningParamsetSetStateAxisResponseSetStateDeviceResponseSettingConstantsSimpleTuningSimpleTuningParamDefinitionStreamStreamAxisDefinitionStreamAxisTypeStreamBufferStreamIoStreamModeStreamsTransportTriggerTriggerActionTriggerConditionTriggerEnabledStateTriggerOperationTriggersTriggerStateTypedSettingUnknownResponseEventWarningFlagsWarnings
zaber_motion.binary
BinarySettingsCommandCodeConnectionDeviceDeviceIdentityDeviceSettingsDeviceTypeErrorCodeMessageReplyCodeReplyOnlyEventUnknownResponseEvent
zaber_motion.exceptions
MotionLibExceptionBinaryCommandFailedExceptionDataCommandFailedExceptionDataCommandTooLongExceptionDataDeviceAddressConflictExceptionDataDeviceDbFailedExceptionDataDeviceDbInnerErrorGCodeExecutionExceptionDataGCodeSyntaxExceptionDataInvalidPacketExceptionDataInvalidPvtPointInvalidResponseExceptionDataMovementFailedExceptionDataMovementInterruptedExceptionDataOperationFailedExceptionDataPvtExecutionExceptionDataPvtMovementFailedExceptionDataPvtMovementInterruptedExceptionDataSetDeviceStateExceptionDataSetPeripheralStateExceptionDataStreamExecutionExceptionDataStreamMovementFailedExceptionDataStreamMovementInterruptedExceptionData
zaber_motion.gcode
AxisDefinitionAxisMappingAxisTransformationDeviceDefinitionOfflineTranslatorTranslateMessageTranslateResultTranslatorTranslatorConfig
zaber_motion.microscopy
AutofocusAutofocusStatusCameraTriggerFilterChangerIlluminatorIlluminatorChannelMicroscopeMicroscopeConfigObjectiveChangerThirdPartyComponentsWdiAutofocusProviderWdiAutofocusProviderStatus
zaber_motion.product
Ge1xGripperGe1xGripperDirectionGe1xGripperErrorGe1xGripperStateProcessProcessControllerProcessControllerModeProcessControllerSourceProcessControllerSourceSensor
zaber_motion
AxisAddressChannelAddressCyclicDirectionDeviceDbSourceDeviceDbSourceTypeDeviceDiscoveryResultDevicePortTypeFirmwareVersionLibraryLogOutputModeMeasurementNamedParameterRotationDirectionToolsUnitConversionDescriptorUnitsUnitTable
© 2026 Zaber Technologies Inc.

API Reference v9.2.0

Connectionclass

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:

Example 1
Example 2
Example 3
Example 4
Example 5
from zaber_motion.ascii import Connection

connection = Connection.open_serial_port('COM3')
from zaber_motion.ascii import Connection

connection = Connection.open_tcp('zaber-12345.local')
from zaber_motion.ascii import Connection

connection = Connection.open_iot('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx')
from zaber_motion.ascii import Connection

connection = Connection.open_network_share('localhost')
from zaber_motion.ascii import Connection
from zaber_motion.ascii import Transport

transport = Transport.open()
connection = Connection.open_custom(transport)
Related Guides:

Index

cConstants
pProperties
eEvents
mMethods

Constants

c

DEFAULT_BAUD_RATE

Connection.DEFAULT_BAUD_RATE
int Default baud rate for serial connections.
Value
115200
c

NETWORK_SHARE_PORT

Connection.NETWORK_SHARE_PORT
int Local area network share port.
Value
11421
c

TCP_PORT_CHAIN

Connection.TCP_PORT_CHAIN
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
c

TCP_PORT_DEVICE_ONLY

Connection.TCP_PORT_DEVICE_ONLY
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

p

checksum_enabled

connection.checksum_enabled
bool Controls whether outgoing messages contain checksum.
p

default_request_timeout

connection.default_request_timeout
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).
p

interface_id

readonly
connection.interface_id
int The interface ID identifies this Connection instance with the underlying library.
p

is_open

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

Events

e

alert

connection.alert
Event invoked when an alert is received from a device.
Emitted Data
AlertEvent Alert message received from the device.
e

disconnected

connection.disconnected
Event invoked when connection is interrupted or closed.
Emitted Data
MotionLibException Error that caused disconnection.
e

unknown_response

connection.unknown_response
Event invoked when a response from a device cannot be matched to any known request.
Emitted Data
UnknownResponseEvent Reply that could not be matched to a request.

Methods

m

close()

async available
connection.close()
Close the connection.
m

detect_devices()

async available
connection.detect_devices(identify_devices = True)
Attempts to detect any devices present on this connection.
Arguments
NameTypeDescription
identify_devicesboolDetermines whether device identification should be performed as well.
Return Value
List[Device] Array of detected devices.
m

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.
m

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.
m

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
NameTypeDescription
except_devicesList[int]Addresses of devices that should not be forgotten.
m

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.
Arguments
NameTypeDescription
commandstrCommand and its parameters.
deviceintOptional device address to send the command to.
axisintOptional axis number to send the command to.
check_errorsboolControls whether to throw an exception when the device rejects the command.
timeoutintThe timeout, in milliseconds, for a device to respond to the command. Overrides the connection default request timeout.
Return Value
Response A response to the command.
m

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.
Arguments
NameTypeDescription
commandstrCommand and its parameters.
deviceintOptional device address to send the command to.
axisintOptional axis number to send the command to.
check_errorsboolControls whether to throw an exception when a device rejects the command.
timeoutintThe timeout, in milliseconds, for a device to respond to the command. Overrides the connection default request timeout.
Return Value
List[Response] All responses to the command.
m

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.
Arguments
NameTypeDescription
commandstrCommand and its parameters.
deviceintOptional device address to send the command to. Specifying -1 omits the number completely.
axisintOptional axis number to send the command to. Specifying -1 omits the number completely.
m

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
NameTypeDescription
device_addressintAddress of device intended to control. Address is configured for each device.
Return Value
Device Device instance.
m

home_all()

async available
connection.home_all(wait_until_idle = True)
Homes all of the devices on this connection.
Arguments
NameTypeDescription
wait_until_idleboolDetermines whether the function should return immediately or wait until the devices are homed.
Return Value
List[int] The addresses of the devices that were homed by this command.
s

open_custom()

async available
Connection.open_custom(transport)
Opens a connection using a custom transport.
Arguments
NameTypeDescription
transportTransportThe custom connection transport.
Return Value
Connection An object representing the connection.
s

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
NameTypeDescription
cloud_idstrThe cloud ID to connect to.
tokenstrThe token to authenticate with. By default the connection will be unauthenticated.
connection_nameOptional[str]The name of the connection to open. Can be left empty to default to the only connection present. Otherwise, use serial port name for serial port connection or hostname:port for TCP connection.
realmOptional[str]The realm to connect to. Can be left empty for the default account realm.
apistrThe URL of the API to receive connection info from.
Return Value
Connection An object representing the connection.
s

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
NameTypeDescription
host_namestrHostname or IP address.
portintPort number.
connection_nameOptional[str]The name of the connection to open. Can be left empty to default to the only connection present. Otherwise, use serial port name for serial port connection or hostname:port for TCP connection.
Return Value
Connection An object representing the connection.
s

open_serial_port()

async available
Connection.open_serial_port(port_name, baud_rate = DEFAULT_BAUD_RATE, direct = False, test_port = 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
NameTypeDescription
port_namestrName of the port to open.
baud_rateintOptional baud rate (defaults to 115200).
directboolIf true will connect to the serial port directly, failing if the connection is already opened by a message router instance.
test_portboolSome 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.
Return Value
Connection An object representing the port.
s

open_tcp()

async available
Connection.open_tcp(host_name, port = TCP_PORT_CHAIN)
Opens a TCP connection.
Arguments
NameTypeDescription
host_namestrHostname or IP address.
portintOptional port number (defaults to 55550).
Return Value
Connection An object representing the connection.
m

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
NameTypeDescription
first_addressintThis is the address that the device closest to the computer is given. Remaining devices are numbered consecutively.
Return Value
int Total number of devices that responded to the renumber.
m

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.
m

stop_all()

async available
connection.stop_all(wait_until_idle = True)
Stops all of the devices on this connection.
Arguments
NameTypeDescription
wait_until_idleboolDetermines whether the function should return immediately or wait until the devices are stopped.
Return Value
List[int] The addresses of the devices that were stopped by this command.
m

__repr__()

connection.__repr__()
Returns a string that represents the connection.
Return Value
str A string that represents the connection.