Published on February 15, 2018

Manual Control Using a Joystick

  Download PDF version (892 KB)


  1. Introduction
  2. Zaber X-JOY3 Features
    1. Joystick Knob
    2. Keys
    3. Alerts
  3. Set-Up and Configuration
    1. Daisy-chaining
    2. Configuring Behaviour
    3. Using Zaber Console's Joystick Tab
    4. Using a Script to Configure in Zaber Console
  4. Use Cases and Examples
    1. Enclosed Environments (Vacuum or Pressure Chambers)
    2. Multi-axis Control and Toggling (3+ devices)
    3. Virtual Axis Control for Micromanipulators
    4. Raster Scan with a Stream Buffer
    5. Trigger A Script Using Alerts
  5. Discussion/Conclusion


A joystick can be a useful complement to many motion control applications. Joysticks, in this context, typically allow for graduated velocity and position control and commonly have buttons that can be mapped to commands, offering the freedom to operate your devices without a computer connection. In this article, we will look at the features of Zaber's X-JOY3 joystick and the steps to set it up. We will also explore some applications that benefit from implementing a joystick control, and look at the different capabilities you can use for your next system.

Zaber X-JOY3 Features

The X-JOY3 is Zaber's 3-axis joystick. It is compatible with all of Zaber's devices and can be daisy-chained with them to share power and data, keeping cabling simple and minimal. Later, we'll go through how to configure the joystick, but first let's look at an overview of the X-JOY3 features.

Figure 1: X-JOY3 in a daisy-chain.

Back to Top

Joystick Knob

The joystick knob offers manual control of three axes, shown in Figure 2: Axis 1 [Left|Right], Axis 2 [Up|Down], and Axis 3 [Counterclockwise|Clockwise]. For each knob axis, you can specify the following:

  • Target Device/Axis: The address of the motor that you want the knob axis to control, including the device number, and, if the device controls more than one motor, the axis number.
  • Axis Direction: Coordinates the direction of movement of a device and the knob that controls it.
  • Maximum Speed: The speed at which the motor will move when the knob is moved to the maximum in an axis
  • Resolution: The number of speed increments in an axis to reach the maximum speed.
  • Speed Profile: The way the speed changes over the travel as you move the knob through increments. The options are linear, squared, or cubed. The linear profile means each increment increases speed by the same amount. Squared and cubed profiles allow finer speed control at low speeds.
Top-down view of the X-JOY3

Figure 2: Top-down view of the X-JOY3 anatomy.

Back to Top


Each of the X-JOY3's 8 keys, shown in Figure 2, can be programmed to send commands to any device connected downstream in the daisy-chain. The commands can be set to target a specific device or axis in the chain or all the devices.

Each button has four available key events to which commands can be mapped. As shown in Figure 3, event 1 occurs as soon as the key is pushed; event 2 occurs if the button is released shortly after pressed; event 3 occurs if the button is held; and event 4 occurs when the button is released after being held. You can map commands to one or more of these events, and you can map multiple commands to a single event.

X-JOY3 key events

Figure 3: X-JOY3 key events.

Back to Top


As shown in Table 1, the joystick can be set to send alerts. Alerts are responses sent upstream from the joystick, which are intended to convey information to a computer if one is connected. If the setting 'comm.alert' is set to 1 on the joystick, then any key event can be set to send an alert response. In cases where you have more complex actions that can't be easily mapped to a button, you can write a computer program that watches for these responses in order to do these functions.

Key Short Press Long Press
1 Stop all axes Home all axes
2 Send alerts* 1, 2 Send alerts* 1, 3, 4
3 Move to saved position Save current position
4 Move to saved position Save current position
5 Move to saved position Save current position
6 Axis 1 low speed Axis 1 high speed
7 Axis 2 low speed Axis 2 high speed
8 Axis 3 low speed Axis 3 high speed

* When comm.alert is set to 1

Table 1: Preprogammed functions.

Each of these can be moved, changed, or removed. We will explain how in a later section.

Back to Top

Set-Up and Configuration

Once you have a joystick and devices, you're ready to setup and configure the system. To get started with your X-JOY3, we recommend using Zaber Console for the initial setup. Zaber Console is our free, open-source, and easy-to-use software, which you can download from here:


Once Zaber Console is installed, all it takes to get started are three steps:

Joystick cable set-up

1. Connect the Joystick to the computer as the first device in the daisy-chain, and connect the devices you would like to control after it.

Zaber console COM port

2. Open Zaber Console; open the COM port; and send a renumber command to All Devices. This will set the Joystick as device 1, and the next devices as 2, 3, and 4. The joystick knob axes control these device numbers by default.

Zaber console Joystick tab

3. Select the X-JOY3 from the device list, and click on the Joystick tab.

For more information on connecting devices, see the Daisy-chaining Data and Power technical paper.

Back to Top

Configuring Behaviour

The X-JOY3 works with Zaber's easy-to-use ASCII protocol by default, and we'll be using this protocol in the following instructions and examples. The X-JOY3 can also be configured with Zaber's Binary protocol; please refer to the Binary Protocol manual for details, or contact Zaber's customer support for more information.

To understand how to configure the manual knob and keys on the X-JOY3, let's take a look at some of the ASCII commands they use:

Joystick Commands  
Set the device that a joystick axis controls: /device joystick 1|2|3 target device axis
Example: Set joystick axis 1 (left|right) to control the second device connected in the daisy-chain /1 joystick 1 target 2 1
Key Commands  
Add a command to a key: /device joystick 1|2|3 target device axis
Example: Set key 1 to send a home command when it is held down for more than one second /1 key 1 3 add home

There are other commands and settings used to configure the joystick, and they are all outlined in detail in the X-JOY3 manual. While editing settings on the joystick can be done directly by using Zaber Console's Commands, Settings, or Terminal Tabs (or through any of the libraries Zaber supports for various programming languages), the easiest way is by using the Joystick tab in Zaber Console.

Back to Top

Using Zaber Console's Joystick Tab

The joystick tab in Zaber Console is specifically designed to simplify X-JOY3 configuration by offering intuitive graphical control.

To adjust the joystick settings, first click on the round Joystick button shown in Figure 4. You can choose a knob axis, and then you'll have controls for each of the settings mentioned earlier. After making changes, make sure you press the Write button to apply them before configuring the next axis.

Click any of the eight Key buttons shown in Figure 4 to configure the functions that the selected key will execute. For each key there are four panes, one for each event, and these have editable fields that match the ASCII message format. You can populate the fields by typing in the device and axis numbers and entering a command. Press the button with a plus sign to add the command. Once you have added a command to the key, you can drag it to other events or press the button with a minus sign to remove it. To upload all of the commands to the joystick, press the Write button in the top right corner.

Zaber console joystick tab

Figure 4: Zaber Console's Joystick tab.

The Options and Settings control offers a list of options, which includes saving and loading configurations, clearing keys, and restoring the settings to default. Figure 5 shows how you can clear some or all of the keys and how you can save a configuration that can be loaded later.

Options and settings on the joystick tab

Figure 5: Options and Settings on the Joystick Tab.

Back to Top

Using a Script to Configure in Zaber Console

In some cases, you may want to load a number of commands at once. While you can do this using the Joystick tab, if you're familiarized with the protocol, it may be faster to use a script. In the Zaber Console Script tab, you can program a list of commands to the X-JOY3 keys and/or joystick. The following example shows a simple script written in C# to program multiple keys at the same time.

        //Create a conversation with the X-JOY3, which is device 1
        var xjoy = PortFacade.GetConversation(1);       
        //Clear anything stored in key 1 event 3
        xjoy.Request("key 1 3 clear");                  
        //Program key 1 event 3 to home all axes
        xjoy.Request("key 1 3 add 0 home");             
        //Clear key 3 event 2
        xjoy.Request("key 3 2 clear");                  
        //Program key 3 event 2 to set the speeds of device 2 and 3 to different values
        xjoy.Request("key 3 2 add 2 set maxspeed 100000");
        xjoy.Request("key 3 2 add 3 set maxspeed 200000");

Back to Top

Use Cases and Examples

Now that we have reviewed features and configuration of the X-JOY3, let's look at a few practical examples to demonstrate where the a joystick can save time and effort.

Back to Top

Enclosed Environments (Vacuum or Pressure Chambers)

Zaber offers a variety of vacuum-rated devices, which are used in controlled, low-pressure chambers. This prevents you from being able to use manual control knobs on devices to adjust them by hand. By connecting a joystick outside the chamber, users are given the ability to make these manual movements without a computer connection. For more information on vacuum devices, see the technical paper: Design Consideration for Vacuum Applications.

Back to Top

Multi-axis Control and Toggling (3+ devices)

While the X-JOY3 has three axes of manual control, some systems to which it will connect will have more than three motors. Rather than using two joysticks, you can set-up buttons on the joystick to switch which axis the joystick knob targets.

4-Axis system with XY, rotation, and gripping

Figure 6: 4-Axis system with XY, rotation, and gripping.

Figure 6 shows an example of a 4-axis system, made up of two linear stages, one rotary stage, and a gripper. You can map the left/right and up/down knob axes to control the linear stages, and then have a button that switches control of the clockwise/counterclockwise knob axis between rotating the gripper and opening/closing it.

Two XYZ systems with one joystick

Figure 7: Two XYZ systems with one joystick.

Figure 7 shows a system of two separate XYZ setups that are daisy-chained together. While the system has 6 axes in total, you can use one joystick by setting a single key that switches the targeted devices between the first set of axes and the second set.

To share a joystick knob axis between two devices, simply configure two key events to toggle the control between one device and the other. Figure 8 shows an example in which Key 4 is programmed so that event 2 sets Joystick Axis 1 (Left and Right) to control device 2, and event 3 sets it to control device 3.

Configuring key 4 to toggle control

Figure 8: Configuring key 4 to toggle control.

Back to Top

Virtual Axis Control for Micromanipulators

For some XY applications, users need to move along a straight line in a direction between X and Y. This direction is called a virtual axis. This is a common requirement in micromanipulators, such as Zaber's M-LSM shown in Figure 9, where a probe may be held at an angle. A user may then want to insert the probe into a sample by moving along a virtual axis corresponding to the angle. Zaber's two-axis X-MCB2 controller supports this kind of movement. For example, to set up a virtual axis 30° between axis 1 and axis 2, you would send:

        /02 virtual 1 setup angle 1 2 30

Once a virtual axis is set up, you can configure one axis of the joystick knob to move along the virtual path similarly to controlling any other axis:

        /01 joystick 1 target 3 virtual 1

We include an X-JOY3 with our M-LSM micromanipulator orders when they are purchased with accessory kits.

Back to Top

Raster Scan with a Stream Buffer

A common use for XY systems is to move through a series of lines to scan an area or stop at an array of positions and perform an action at each stop. These kinds of movements are known as raster scans. In cases where having a computer connection is not feasible, raster scan movements can be saved to a stream buffer and run using a X-JOY3 key. For more information on streams, see Streamed and Interpolated Multi-Axis Motion.

Zaber's Micromanipulator bundle includes the X-JOY3

Figure 9: Zaber's Micromanipulator bundle includes the X-JOY3.

The following script stores a raster scan on an X-MCB2 controller and programs key 8 on the X-JOY3 to call the scan. At each position, it will turn on a digital output to trigger some action, wait for a period, then turn it off. Once this script is run, you will be able to initiate the raster scan by clicking key 8.


        var xjoy = PortFacade.GetConversation(1);       //X-JOY3 is device 1
        var xmcb2 = PortFacade.GetConversation(2);      //X-MCB2 is device 2
        var col_dist = 2000;                            //Distance in microsteps between each column in grid
        var row_dist = 2000;                            //Distance in microsteps between each row in grid
        var sittime = 500;                              //Time in milliseconds of pause at each position
        var digitaloutput = 1;                          //Which digital output pin to turn on at each position
        int col_num = 12;                               //Number of columns in raster
        int row_num = 8;                                //Number of rows in raster
        int col_count = 0;
        int row_count = 0;

        xjoy.Request("key 8 2 clear");                  //Clears Key 8 event 2
        xmcb2.Request("stream buffer 1 erase");         //Clears stream buffer
        xmcb2.Request("stream 1 setup disable");        //Disables stream 1 setup
        xmcb2.Request("stream 1 setup store 1 2");      //Start storing using stream 1
        while (row_count < row_num) {
            xmcb2.Request("stream 1 line abs " + (col_dist) + " " + (row_dist));
            xmcb2.Request("stream 1 io set do 1 1");    //Set DO1 high
            xmcb2.Request("stream 1 wait ", sittime);
            xmcb2.Request("stream 1 io set do 1 0");    //Set DO1 low

            while (col_count < col_num) {
                xmcb2.Request("stream 1 line rel " + (col_dist) + " " + (0));
                xmcb2.Request("stream 1 io set do 1 1");    //Set DO1 high
                xmcb2.Request("stream 1 wait ", sittime);
                xmcb2.Request("stream 1 io set do 1 0");    //Set DO1 low
            row_dist = row_dist + row_dist;
            col_count = 0;
        xmcb2.Request("stream 1 setup disable");
        //Program the key 8 to start and call the stream
        xjoy.Request("key 8 2 add 2 stream 1 setup live 1 2");
        xjoy.Request("key 8 2 add 2 stream 1 call 1");

Back to Top

Trigger A Script Using Alerts

Most of the examples we've looked at have focused on cases in which it's helpful to have either manual control or keys when you don't have a computer connection available. There are also uses for the joystick in conjunction with a computer script or program.

In particular, the Alert function is useful in sending information upstream from the joystick, back to the computer. Every key event on the joystick can be set to send an alert message to the connected COM port. The script or program can watch for these alerts, and based on which key event occurs, it can run a number of different programs. For example, if you're using the joystick to move a digital camera that is connected to a computer, you can write a script on the computer that captures an image when a particular key alert is received. This would allow you to focus on your subject rather than returning to the computer every time you wanted to capture an image.

To enable alerts for a particular key event, first enable alerts on your device:

        /1 set comm.alert 1

Next, enable alerts for the key events you'd like to respond. For example, to have key 2 event 1 send an alert, send:

        /1 key 2 1 alert 1

Now, when key 2 is pressed, the following alert will be sent back to the computer port:

        !01 0 key 2 1

Back to Top


We've discussed a number of applications and uses for Zaber's X-JOY3 joystick, but there are many more ways the features can be used. If you have an application where you think it may be useful, or if you have any questions, please contact our Applications Engineering Team at For additional information and troubleshooting, you can refer to our Joystick Manual, Zaber Console Joystick Guide, or our Zaber Console ASCII manual.

Feel free to contact our Applications Engineering Team at if you have any questions about this article, if you have a potential application in mind or need any other additional information.

Back to Top