Open a serial port

If you want to use the library with prototypes (for instance FW 7.99), you need to use the master Device Database. To make library use the master database, please put the following line at the beginning of your program.

Library.set_device_db_source(DeviceDbSourceType.WEB_SERVICE, "https://api.zaber.io/device-db/master")

Library.SetDeviceDbSource(DeviceDbSourceType.WebService, "https://api.zaber.io/device-db/master");

Library.setDeviceDbSource(DeviceDbSourceType.WEB_SERVICE, 'https://api.zaber.io/device-db/master');

Library.setDeviceDbSource(DeviceDbSourceType.WEB_SERVICE, "https://api.zaber.io/device-db/master");

Library.setDeviceDbSource(DeviceDbSourceType.WEB_SERVICE, 'https://api.zaber.io/device-db/master');

WEB_SERVICE_SOURCE = java_get("zaber.motion.DeviceDbSourceType", "WEB_SERVICE");
javaMethod("setDeviceDbSource", "zaber.motion.Library", WEB_SERVICE_SOURCE, "https://api.zaber.io/device-db/master");

Library::setDeviceDbSource(DeviceDbSourceType::WEB_SERVICE, "https://api.zaber.io/device-db/master");

In order to send commands to the device, you first need to open a serial port.

Which port to open depends on the computer, operating system, and how the device is connected.

Operating system: Windows Linux (Ubuntu) Mac OS

In the following examples, replace the placeholder port name, COM3, with name of your connection. If you are uncertain about the name of your connection, see our guide to finding the right port.

In the following examples, replace the placeholder port name, /dev/ttyUSB0, with name of your connection. If you are uncertain about the name of your connection, see our guide to finding the right port.

In the following examples, replace the placeholder port name, /dev/tty.usbserial-A4017DXH, with name of your connection. If you are uncertain about the name of your connection, see our guide to finding the right port.

with Connection.open_serial_port("COM3") as connection:
    device_list = connection.detect_devices()
    print("Found {} devices".format(len(device_list)))

    # The rest of your program goes here (indented)

using (var connection = Connection.OpenSerialPort("COM3")) {
    var deviceList = connection.DetectDevices();
    Console.WriteLine($"Found {deviceList.Length} devices.");

    // The rest of your program goes here
}

const connection = await Connection.openSerialPort('COM3');
try {
    const deviceList = await connection.detectDevices();
    console.log(`Found ${deviceList.length} devices.`);

    // The rest of your program goes here
} finally {
    // Close the port to allow Node.js to exit
    await connection.close();
}

try (Connection connection = Connection.openSerialPort("COM3")) {
    Device[] deviceList = connection.detectDevices();
    System.out.println(String.format("Found %d devices.", deviceList.length));

    // The rest of your program goes here
}

connection = Connection.openSerialPort('COM3');
try
    deviceList = connection.detectDevices();
    fprintf('Found %d devices.\n', deviceList.length);

    % The rest of your program goes here

    connection.close();
catch exception
    connection.close();
    rethrow(exception);
end

connection = javaMethod("openSerialPort", CONNECTION_CLASS, "COM3");
try
    deviceList = connection.detectDevices();
    fprintf("Found %d devices.\n", length(deviceList));

    % The rest of your program goes here

    connection.close();
catch exception
    connection.close();
    rethrow(exception);
end

Connection connection = Connection::openSerialPort("COM3");

std::vector<Device> deviceList = connection.detectDevices();
std::cout << "Found " << deviceList.size() << " devices." << std::endl;

// The rest of your program goes here

with Connection.open_serial_port("/dev/ttyUSB0") as connection:
    device_list = connection.detect_devices()
    print("Found {} devices".format(len(device_list)))

    # The rest of your program goes here (indented)

using (var connection = Connection.OpenSerialPort("/dev/ttyUSB0")) {
    var deviceList = connection.DetectDevices();
    Console.WriteLine($"Found {deviceList.Length} devices.");

    // The rest of your program goes here
}

const connection = await Connection.openSerialPort('/dev/ttyUSB0');
try {
    const deviceList = await connection.detectDevices();
    console.log(`Found ${deviceList.length} devices.`);

    // The rest of your program goes here
} finally {
    // Close the port to allow Node.js to exit
    await connection.close();
}

try (Connection connection = Connection.openSerialPort("/dev/ttyUSB0")) {
    Device[] deviceList = connection.detectDevices();
    System.out.println(String.format("Found %d devices.", deviceList.length));

    // The rest of your program goes here
}

connection = Connection.openSerialPort('/dev/ttyUSB0');
try
    deviceList = connection.detectDevices();
    fprintf('Found %d devices.\n', deviceList.length);

    % The rest of your program goes here

    connection.close();
catch exception
    connection.close();
    rethrow(exception);
end

connection = javaMethod("openSerialPort", CONNECTION_CLASS, "/dev/ttyUSB0");
try
    deviceList = connection.detectDevices();
    fprintf("Found %d devices.\n", length(deviceList));

    % The rest of your program goes here

    connection.close();
catch exception
    connection.close();
    rethrow(exception);
end

Connection connection = Connection::openSerialPort("/dev/ttyUSB0");

std::vector<Device> deviceList = connection.detectDevices();
std::cout << "Found " << deviceList.size() << " devices." << std::endl;

// The rest of your program goes here

with Connection.open_serial_port("/dev/tty.usbserial-A4017DXH") as connection:
    device_list = connection.detect_devices()
    print("Found {} devices".format(len(device_list)))

    # The rest of your program goes here (indented)

using (var connection = Connection.OpenSerialPort("/dev/tty.usbserial-A4017DXH")) {
    var deviceList = connection.DetectDevices();
    Console.WriteLine($"Found {deviceList.Length} devices.");

    // The rest of your program goes here
}

const connection = await Connection.openSerialPort('/dev/tty.usbserial-A4017DXH');
try {
    const deviceList = await connection.detectDevices();
    console.log(`Found ${deviceList.length} devices.`);

    // The rest of your program goes here
} finally {
    // Close the port to allow Node.js to exit
    await connection.close();
}

try (Connection connection = Connection.openSerialPort("/dev/tty.usbserial-A4017DXH")) {
    Device[] deviceList = connection.detectDevices();
    System.out.println(String.format("Found %d devices.", deviceList.length));

    // The rest of your program goes here
}

connection = Connection.openSerialPort('/dev/tty.usbserial-A4017DXH');
try
    deviceList = connection.detectDevices();
    fprintf('Found %d devices.\n', deviceList.length);

    % The rest of your program goes here

    connection.close();
catch exception
    connection.close();
    rethrow(exception);
end

connection = javaMethod("openSerialPort", CONNECTION_CLASS, "/dev/tty.usbserial-A4017DXH");
try
    deviceList = connection.detectDevices();
    fprintf("Found %d devices.\n", length(deviceList));

    % The rest of your program goes here

    connection.close();
catch exception
    connection.close();
    rethrow(exception);
end

Connection connection = Connection::openSerialPort("/dev/tty.usbserial-A4017DXH");

std::vector<Device> deviceList = connection.detectDevices();
std::cout << "Found " << deviceList.size() << " devices." << std::endl;

// The rest of your program goes here

Run the code and you should see the number of detected devices in the output of the application.

If you encounter a problem during this step, check that the device is connected correctly and powered on. Also ensure that other applications, such as Zaber Console, do not have the port open by either selecting Close or exiting the application. If you encounter @class DeviceAddressConflictException, use the Zaber Console application to assign distinct addresses to your devices.

The example code demonstrates use of a with statement to ensure that the serial port closes after the program runs.

The example code demonstrates use of a using statement to ensure that the serial port closes after the program runs.

The example code demonstrates use of a try, finally statement to ensure that the serial port closes after the program runs. Closing the port is crucial because an open port prevents Node.js from exiting.

The example code demonstrates use of a try-with-resources statement to ensure that the serial port closes after the program runs.

The example code demonstrates use of a try-catch statement to ensure that the serial port closes in case of an exception.

The serial port is closed on object deconstruction. No additional try-catch or explicit close() call is needed.

Continue the Getting Started guide by homing your device.

Continue the Getting Started guide by homing your device.

Troubleshooting: Permission denied

In some cases you may encounter:

Cannot open serial port: open /dev/ttyUSB0: permission denied

This problem occurs when the current user is not allowed to use serial ports on the computer. To resolve this issue open a console and enter the following:

sudo adduser $USER dialout

Logout and login again or reboot your computer and you should have access to the serial ports.

Port Locking

To avoid conflict with other software accessing the serial port, the library locks the port using the flock system call. If the lock cannot be acquired without blocking, the @method OpenSerialPort method throws a @class ConnectionFailedException exception. The library also puts the port into exclusive mode using the TIOCEXCL command of the ioctl system call to prevent further attempts to open the port. The lock is released and exclusive mode is disabled when the connection is closed.