Zaber Motion LibraryGetting StartedHow-to GuidesSupportBinary Protocol (Legacy)
API Reference
ZaberMotionAscii
AlertEventAllAxesAxisAxisGroupAxisIdentityAxisSettingsAxisStorageAxisTypeConnectionConversionFactorDeviceDeviceIdentityDeviceIODeviceIOInfoDeviceSettingsDeviceStorageDigitalOutputActionGetAxisSettingGetAxisSettingResultGetAxisSettingTypedResultGetSettingGetSettingResultGetSettingTypedResultIoPortLabelIoPortTypeLockstepMeasurementSequenceMessageTypeOscilloscopeOscilloscopeCapturePropertiesOscilloscopeDataOscilloscopeDataSourceParamsetInfoPidTuningPvtPvtAxisDefinitionPvtAxisTypePvtBufferPvtBufferAxisUnitsPvtCallActionPvtCancelAllOutputsScheduleActionPvtCancelOutputScheduleActionPvtCsvDataPvtIoPvtModePvtPartialCsvDataPvtPartialPointPvtPartialSequenceItemPvtPointPvtSequencePvtSequenceItemPvtSetAllAnalogOutputsActionPvtSetAllDigitalOutputsActionPvtSetAnalogOutputActionPvtSetDigitalOutputActionResponseServoTunerServoTuningParamServoTuningParamsetSetStateAxisResponseSetStateDeviceResponseSettingConstantsSimpleTuningSimpleTuningParamDefinitionStreamStreamAxisDefinitionStreamAxisTypeStreamBufferStreamIoStreamModeStreamsTransportTriggerTriggerActionTriggerConditionTriggerEnabledStateTriggerOperationTriggersTriggerStateTypedSettingUnknownResponseEventWarningFlagsWarnings
ZaberMotionBinary
BinarySettingsCommandCodeConnectionDeviceDeviceIdentityDeviceSettingsDeviceTypeErrorCodeMessageReplyCodeReplyOnlyEventUnknownResponseEvent
ZaberMotionExceptions
MotionLibExceptionBinaryCommandFailedExceptionDataCommandFailedExceptionDataCommandTooLongExceptionDataDeviceAddressConflictExceptionDataDeviceDbFailedExceptionDataDeviceDbInnerErrorGCodeExecutionExceptionDataGCodeSyntaxExceptionDataInvalidPacketExceptionDataInvalidPvtPointInvalidResponseExceptionDataMovementFailedExceptionDataMovementInterruptedExceptionDataOperationFailedExceptionDataPvtExecutionExceptionDataPvtMovementFailedExceptionDataPvtMovementInterruptedExceptionDataSetDeviceStateExceptionDataSetPeripheralStateExceptionDataStreamExecutionExceptionDataStreamMovementFailedExceptionDataStreamMovementInterruptedExceptionData
ZaberMotionGcode
AxisDefinitionAxisMappingAxisTransformationDeviceDefinitionOfflineTranslatorTranslateMessageTranslateResultTranslatorTranslatorConfig
ZaberMotionMicroscopy
AutofocusAutofocusStatusCameraTriggerFilterChangerIlluminatorIlluminatorChannelMicroscopeMicroscopeConfigObjectiveChangerThirdPartyComponentsWdiAutofocusProviderWdiAutofocusProviderStatus
ZaberMotionProduct
Ge1xGripperGe1xGripperDirectionGe1xGripperErrorGe1xGripperStateProcessProcessControllerProcessControllerModeProcessControllerSourceProcessControllerSourceSensor
ZaberMotion
AxisAddressChannelAddressCyclicDirectionDeviceDbSourceDeviceDbSourceTypeDeviceDiscoveryResultDevicePortTypeFirmwareVersionLibraryLogOutputModeMeasurementNamedParameterRotationDirectionToolsUnitConversionDescriptorUnitsUnitTable
© 2026 Zaber Technologies Inc.

API Reference v9.2.0

Connectionclass

Module: ZaberMotionAscii

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
import ZaberMotionAscii

let connection = try await Connection.openSerialPort(portName: "COM3")
import ZaberMotionAscii

let connection = try await Connection.openTcp(hostName: "zaber-12345.local")
import ZaberMotionAscii

let connection = try await Connection.openIot(cloudId: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx")
import ZaberMotionAscii

let connection = try await Connection.openNetworkShare(hostName: "localhost")
import ZaberMotionAscii

let transport = try Transport.open()
let connection = try await Connection.openCustom(transport: transport)
Related Guides:

Index

cConstants
pProperties
eEvents
mMethods

Constants

c

defaultBaudRate

Connection.defaultBaudRate
Int Default baud rate for serial connections.
Value
115200
c

networkSharePort

Connection.networkSharePort
Int Local area network share port.
Value
11421
c

tcpPortChain

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

tcpPortDeviceOnly

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

checksumEnabled

throws
try connection.getChecksumEnabled()
try connection.setChecksumEnabled(value)
Bool Controls whether outgoing messages contain checksum.
p

defaultRequestTimeout

throws
try connection.getDefaultRequestTimeout()
try connection.setDefaultRequestTimeout(value)
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

interfaceId

readonly
connection.interfaceId
Int The interface ID identifies this Connection instance with the underlying library.
p

isOpen

readonlythrows
try connection.isOpen
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

UnknownResponse

connection.UnknownResponse
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()

asyncthrows
try await connection.close()
Close the connection.
m

detectDevices()

asyncthrows
try await connection.detectDevices(identifyDevices = true)
Attempts to detect any devices present on this connection.
Arguments
NameTypeDescription
identifyDevicesBoolDetermines whether device identification should be performed as well.
Return Value
[Device] Array of detected devices.
m

disableAlerts()

asyncthrows
try await connection.disableAlerts()
Disables alerts for all devices on the connection. This will change the "comm.alert" setting to 0 on all supported devices.
m

enableAlerts()

asyncthrows
try await connection.enableAlerts()
Enables alerts for all devices on the connection. This will change the "comm.alert" setting to 1 on all supported devices.
m

forgetDevices()

throws
try connection.forgetDevices(exceptDevices = [])
Forgets all the information associated with devices on the connection. Useful when devices are removed from the chain indefinitely.
Arguments
NameTypeDescription
exceptDevices[Int]Addresses of devices that should not be forgotten.
m

genericCommand()

asyncthrows
try await connection.genericCommand(command, device = 0, axis = 0, checkErrors = true, timeout = 0)
Sends a generic ASCII command to this connection. For more information refer to the ASCII Protocol Manual.
Arguments
NameTypeDescription
commandStringCommand and its parameters.
deviceIntOptional device address to send the command to.
axisIntOptional axis number to send the command to.
checkErrorsBoolControls 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

genericCommandMultiResponse()

asyncthrows
try await connection.genericCommandMultiResponse(command, device = 0, axis = 0, checkErrors = 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
commandStringCommand and its parameters.
deviceIntOptional device address to send the command to.
axisIntOptional axis number to send the command to.
checkErrorsBoolControls 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
[Response] All responses to the command.
m

genericCommandNoResponse()

asyncthrows
try await connection.genericCommandNoResponse(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
commandStringCommand 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

getDevice()

throws
try connection.getDevice(deviceAddress)
Gets a Device class instance which allows you to control a particular device on this connection. Devices are numbered from 1.
Arguments
NameTypeDescription
deviceAddressIntAddress of device intended to control. Address is configured for each device.
Return Value
Device Device instance.
m

homeAll()

asyncthrows
try await connection.homeAll(waitUntilIdle = true)
Homes all of the devices on this connection.
Arguments
NameTypeDescription
waitUntilIdleBoolDetermines whether the function should return immediately or wait until the devices are homed.
Return Value
[Int] The addresses of the devices that were homed by this command.
s

openCustom()

asyncthrows
try await Connection.openCustom(transport)
Opens a connection using a custom transport.
Arguments
NameTypeDescription
transportTransportThe custom connection transport.
Return Value
Connection An object representing the connection.
s

openIot()

asyncthrows
try await Connection.openIot(cloudId, token = "unauthenticated", connectionName = nil, realm = nil, 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
cloudIdStringThe cloud ID to connect to.
tokenStringThe token to authenticate with. By default the connection will be unauthenticated.
connectionNameString?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.
realmString?The realm to connect to. Can be left empty for the default account realm.
apiStringThe URL of the API to receive connection info from.
Return Value
Connection An object representing the connection.
s

openNetworkShare()

asyncthrows
try await Connection.openNetworkShare(hostName, port = Connection.networkSharePort, connectionName = nil)
Opens a connection to Zaber Launcher in your Local Area Network. The connection is not secured.
Arguments
NameTypeDescription
hostNameStringHostname or IP address.
portIntPort number.
connectionNameString?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

openSerialPort()

asyncthrows
try await Connection.openSerialPort(portName, baudRate = Connection.defaultBaudRate, direct = false, testPort = 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
portNameStringName of the port to open.
baudRateIntOptional 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.
testPortBoolSome 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

openTcp()

asyncthrows
try await Connection.openTcp(hostName, port = Connection.tcpPortChain)
Opens a TCP connection.
Arguments
NameTypeDescription
hostNameStringHostname or IP address.
portIntOptional port number (defaults to 55550).
Return Value
Connection An object representing the connection.
m

renumberDevices()

asyncthrows
try await connection.renumberDevices(firstAddress = 1)
Renumbers devices present on this connection. After renumbering, devices need to be identified again.
Arguments
NameTypeDescription
firstAddressIntThis 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()

asyncthrows
try await 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

stopAll()

asyncthrows
try await connection.stopAll(waitUntilIdle = true)
Stops all of the devices on this connection.
Arguments
NameTypeDescription
waitUntilIdleBoolDetermines whether the function should return immediately or wait until the devices are stopped.
Return Value
[Int] The addresses of the devices that were stopped by this command.
m

toString()

throws
try connection.toString()
Returns a string that represents the connection.
Return Value
String A string that represents the connection.