6.1. Setting up USB control

This section explains how to control the Jrk G2 over USB.

If you have not done so already, you should follow the instructions in Section 4.3 to configure and test your motor, and follow the instructions in the appropriate part of Section 5 to set up your desired feedback method.

Those sections include explanations of how to use the slider in the “Status” tab of the Jrk G2 Configuration Utility to control the Jrk. If that interface is good enough for you, you do not need to set up anything else and can skip the rest of this section.

Another option for controlling the Jrk G2 over USB is to use the Jrk G2 Command-line Utility, jrk2cmd. You can either run the utility directly by typing commands in your command prompt (shell), or you can write your own software that runs it.

To try out jrk2cmd, you should open a new command prompt (also called a terminal or a shell) and run jrk2cmd without any arguments. This causes jrk2cmd to print a help screen listing all the options it supports. You can combine multiple options in one invocation.

If your command prompt prints out a message indicating that jrk2cmd is not found or not recognized, make sure you have installed the Jrk G2 software properly as described in Section 3. Also, make sure that the directory containing the jrk2cmd executable is in your PATH environment variable, and try starting a new command prompt after installing the software.

To clear any latched errors and set the target of the Jrk, try running these commands:

jrk2cmd --clear-errors --target 1848
jrk2cmd --clear-errors --target 2248

If you are using open-loop speed control (“Feedback mode” is “None”), you might prefer to use the --speed option instead of --target. The --speed option is equivalent to the --target option except that it adds 2048 to specified number, so you can specify the full range of speeds as numbers from −600 to 600 instead of 1448 to 2648.

If the commands above do not produce movement, you should run jrk2cmd --status to print out the errors that are currently stopping the motor. This might tell you what is going wrong.

On Microsoft Windows, only one device can access the Jrk’s USB interface at a time, so you will need to close the Jrk G2 Configuration Utility software before running the command-line utility.

To get the status of the Jrk, try running these commands, which give different levels of details:

jrk2cmd --status
jrk2cmd --status --full

The output of these commands is designed to be compatible with the YAML format, so if you are writing a computer program that needs to get some information from the Jrk, you can parse the output with a YAML parser in the language of your choice.

If you have multiple Jrk G2 devices connected to the computer, you will need to use the -d option to specify the serial number of the device you want to use. For example, to get the status of the Jrk G2 with serial number 12345678, run jrk2cmd -d 12345678 --status. You can run jrk2cmd --list to get the serial numbers (they are listed in the first column). If you omit the -d option, jrk2cmd will print: “Error: There are multiple qualifying devices connected to this computer. Use the -d option to specify which device you want to use, or disconnect the others.”

For more details about the commands you can send to the Jrk over USB, see Section 11.

If you want to write your own software to send USB commands to the Jrk instead of just using jrk2cmd or the Jrk G2 Configuration Utility, see Section 15.

Using the USB virtual serial ports

The instructions above use the Jrk’s native USB interface. It is also possible to control the Jrk over USB using one of its virtual USB serial ports. To do this, you would set the serial mode to “USB Dual Port” (or “USB Chained”), connect to the Jrk’s command port (one of the two USB virtual serial ports provided by the Jrk), and then send the serial commands as specified in Section 12. For example code that shows how to use the Jrk’s serial interface from a computer, see Section 15.

It is important to note that the Jrk’s serial command protocol is a binary protocol that requires you to send arbitrary bytes between 0 and 255. The Jrk does not use any kind of ASCII or Unicode character encoding, making it incompatible with most serial terminal software. You can use the Pololu Serial Transmitter utility for Windows to send and receive binary serial bytes on the Jrk’s serial ports. This can be useful because it lets you test the Jrk’s serial port before attempting to write your own code to communicate with it. When you do write code to communicate with it, make sure you are using an API that allows you to send and receive arbitrary binary data, and make sure to disable any serial port options that might modify the data (e.g. by performing newline conversions).

If you get a “Permission denied” error when trying to access the Jrk’s USB serial ports on Linux, you might have to add your user to the dialout group by running sudo usermod -a -G dialout $(whoami) and restarting. You can check the permissions of your serial ports by running ls -l /dev/ttyACM*. Another workaround is to simply run your program as root by adding sudo to the beginning of your command.

Besides sending commands to the Jrk, you can also send and receive bytes on its TX and RX lines over USB, essentially using the Jrk as a USB-to-TTL serial adapter. If your serial mode is “USB Dual Port”, then you can connect to the Jrk G2’s TTL port to do this. If your serial mode is “USB Chained”, then you can connect to the command port to do this, but you will have to be careful about what bytes you send because the Jrk will try to interpret them as serial commands. Either way, make sure to set the baud rate in whatever software you are using to connect to the serial port; this determines what baud rate the Jrk will use on its RX and TX lines.

Determining serial port names

The USB interface of the Jrk G2 provides two virtual serial ports: the command port and the TTL port. The “Device info” tab of the Jrk G2 Configuration Utility displays the names of the command port and the TTL port assigned by the operating system (e.g. COM9). You can also see the names by running jrk2cmd -s. With either of these two methods, a port name will be displayed as “?” if it cannot be determined.

You can also run jrk2cmd --cmd-port or jrk2cmd --ttl-port in a command prompt. Each of these commands simply prints the name assigned to the corresponding serial port. These commands will print an error message on the standard error pipe if anything goes wrong.

On Windows you can also determine the COM port names by looking in the Device Manager. Usually, both ports will be displayed in the “Ports (COM & LPT)” category. The descriptive name of the port (e.g. “Pololu Jrk G2 18v27 Command Port”) will be displayed, followed by the COM port name in parentheses. If the descriptive name is just “USB Serial Device” for both of the Jrk’s ports, then you can identify the two ports by double-clicking on each one and looking at the “Hardware Ids” property in the “Details” tab. The command port will have an ID ending in MI_01 while the TTL port will have an ID ending in MI_03. If you have trouble finding the ports in the Device Manager, see the USB troubleshooting tips in Section 3.1.

On Linux, the Jrk’s two serial ports should show up as devices with names like /dev/ttyACM0 and /dev/ttyACM1. The name with the lower number usually corresponds to the command port. You can run ls /dev/ttyACM* to list those ports. These serial port names are not generally reliable, because if /dev/ttyACM0 is already in use when the Jrk gets plugged in, then its ports will be assigned to higher numbers. If you want more reliable names for the serial ports, you can use the symbolic links in the /dev/serial/by-id/ directory. The links for the Jrk ending with if01 are for the command port, while the links ending with if03 are for the TTL port. For example, the command port of a Jrk 18v27 with serial number 00001234 would be something like:

/dev/serial/by-id/usb-Pololu_Corporation_Pololu_Jrk_G2_18v27_00001234-if01

On macOS, the Jrk’s two serial ports will have names like /dev/cu.usbmodem00022331. The name with the lower number usually corresponds to the command port. You can run ls /dev/cu.usbmodem* to list these posts. You can also find these names by running ioreg -trc IOSerialBSDClient. The output from this command is somewhat complicated, but you should see entries for the Jrk G2. An entry for the Jrk with IOUSBHostInterface@2 in it corresponds to the command port, while an entry with IOUSBHostInterface@4 in it corresponds to the TTL port.