Skip to content

Device Database

The Device Database is a comprehensive resource that contains information about Zaber's products, including unit conversion factors, device names, and supported commands and settings. You can use the library without the Device Database, though some features, such as using real-world units (i.e. units other than Native) or using properties related to device identity, will result in an exception.

The library uses the Device Database whenever it needs to identify a device (e.g. when you call the @method DetectDevices method on a @class Connection class instance). By default, the library accesses the Device Database through a web-service.

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

# from zaber_motion import Library, DeviceDbSourceType

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");
// const { Library, DeviceDbSourceType } = require('@zaber/motion');

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

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

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

There are alternatives to accessing the device database which either limit use, or do not use the web service. These are useful in the case of an undesired or impossible internet connection.

Option #1

The easiest option is to use the Device Database's store feature. When you enable this feature, the next time the library needs the database it will contact the web-service and save the obtained data to the file system. When the library requires data later on, it uses the saved files instead of the web-service.

You may enable this feature by placing the following line at the beginning of your program.

# from zaber_motion import Library

Library.enable_device_db_store()
Library.EnableDeviceDbStore();
// const { Library } = require('@zaber/motion');

Library.enableDeviceDbStore();
// import zaber.motion.Library;

Library.enableDeviceDbStore();
% import zaber.motion.Library;

Library.enableDeviceDbStore();
Library::enableDeviceDbStore();

This creates a folder (%LOCALAPPDATA%\Zaber Technologies\Zaber Motion Library on Windows, $XDG_CACHE_HOME/zaber-motion-lib on Linux and ~/Library/Caches/zaber-motion-lib on Mac OS) and stores all the information about the devices into that folder.

Additionally, you can provide a relative or an absolute path as a second argument to specify the location of the storage.

# from zaber_motion import Library

Library.enable_device_db_store("./device-db-store")
Library.EnableDeviceDbStore("./device-db-store");
// const { Library } = require('@zaber/motion');

Library.enableDeviceDbStore('./device-db-store');
// import zaber.motion.Library;

Library.enableDeviceDbStore("./device-db-store");
% import zaber.motion.Library;

Library.enableDeviceDbStore('./device-db-store');
Library::enableDeviceDbStore("./device-db-store");

The library may try to access the web-service again to update the saved files. This happens if the library upgrades, if it detects a new type of device, or if the device's firmware updates.

Option #2

This option allows the library to operate completely offline. It requires you to download the complete Device Database, which contains information about all Zaber devices.

You may download the database from here. When the download is complete, decompress the archive and move the resulting file to your desired folder.

To configure the library to use this file, place the following line at the top of your program (replacing path_to_the_folder with the folder it is in):

# from zaber_motion import Library, DeviceDbSourceType

Library.set_device_db_source(DeviceDbSourceType.FILE, "path_to_the_folder/devices-public.sqlite")
Library.SetDeviceDbSource(DeviceDbSourceType.File, "path_to_the_folder/devices-public.sqlite");
// const { Library, DeviceDbSourceType } = require('@zaber/motion');

Library.setDeviceDbSource(DeviceDbSourceType.FILE, 'path_to_the_folder/devices-public.sqlite');
// import zaber.motion.Library;
// import zaber.motion.DeviceDbSourceType;

Library.setDeviceDbSource(DeviceDbSourceType.FILE, "path_to_the_folder/devices-public.sqlite");
% import zaber.motion.Library;
% import zaber.motion.DeviceDbSourceType;

Library.setDeviceDbSource(DeviceDbSourceType.FILE, 'path_to_the_folder/devices-public.sqlite');
Library::setDeviceDbSource(DeviceDbSourceType::FILE, "path_to_the_folder/devices-public.sqlite");

Please note that if you upgrade the library or device firmware or purchase a new device, you should repeat this process. Do this by downloading the latest Device Database file from the link above, decompressing it, and replacing the old file with the new one.

Option #3

A third option is to use the library without unit conversions or device identification.

To choose this option, pass false for the first argument of the detect devices method. The library will then not attempt to identify devices during the method call.

If you choose this option, you will be unable to use methods which make use of units. This includes unit conversion when using set or get methods, the standalone unit conversion method, and motion methods which do not use native units. If you attempt these the library will raise an exception.

If you need unit conversions, please visit the ASCII Protocol Manual for instructions on how to do the conversions manually.

The following example demonstrates this option:

# Detect without identification
device_list = connection.detect_devices(False)
device = device_list[0]

axis = device.get_axis(1)
# Move by 10000 native units
axis.move_relative(10000)
// Detect without identification
var deviceList = connection.DetectDevices(false);
var device = deviceList[0];

var axis = device.GetAxis(1);
// Move by 10000 native units
axis.MoveRelative(10000);
// Detect without identification
const deviceList = await connection.detectDevices(false);
const device = deviceList[0];

const axis = device.getAxis(1);
// Move by 10000 native units
await axis.moveRelative(10000);
// Detect without identification
Device[] deviceList = connection.detectDevices(false);
Device device = deviceList[0];

Axis axis = device.getAxis(1);
// Move by 10000 native units
axis.moveRelative(10000);
% Detect without identification
deviceList = connection.detectDevices(0);
device = deviceList(1);

axis = device.getAxis(1);
% Move by 10000 native units
axis.moveRelative(10000);
// Detect without identification
std::vector<Device> deviceList = connection.detectDevices(false);
Device device = deviceList[0];

Axis axis = device.getAxis(1);
// Move by 10000 native units
axis.moveRelative(10000);