Pololu Jrk G2 21v3 User manual

Jrk G2 Motor Controller User’s
Guide
Jrk G2 Motor Controller User’s Guide © 2001–2019 Pololu Corporation
https://www.pololu.com/docs/0J73/all Page 1 of 199

1. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
1.1. Supported operating systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
1.2. Comparison to the original Jrk controllers . . . . . . . . . . . . . . . . . . . . . . . . . . 6
2. Contacting Pololu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
3. Getting started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
3.1. Installing Windows drivers and software . . . . . . . . . . . . . . . . . . . . . . . . . 11
3.2. Installing Linux software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
3.3. Installing macOS software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
4. Basic setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
4.1. Choosing the motor, power supply, and Jrk . . . . . . . . . . . . . . . . . . . . . . . . 19
4.2. Connecting the motor and power supply . . . . . . . . . . . . . . . . . . . . . . . . . 21
4.3. Configuring and testing the motor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
5. Setting up the feedback method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
5.1. Setting up open-loop control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
5.2. Setting up analog feedback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
5.3. Setting up frequency feedback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
6. Setting up the control method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
6.1. Setting up USB control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
6.2. Setting up serial control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
6.3. Setting up I²C control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
6.4. Setting up analog control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
6.5. Setting up RC control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
7. Details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
7.1. L D feedback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
7.2. Graph window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
7.3. Analog/RC input handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
7.4. Analog/frequency feedback handling . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
7.5. PID calculation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
7.6. Motor settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
7.7. rror handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
7.8. Logic power output (5V) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
7.9. Upgrading firmware . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
8. Pinout and components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
9. Setting reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
10. Variable reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
11. Command reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
12. Serial command encoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154
13. I²C command encoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164
14. USB command encoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
15. Writing PC software to control the Jrk . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
Jrk G2 Motor Controller User’s Guide © 2001–2019 Pololu Corporation
Page 2 of 199

15.1. xample code to run jrk2cmd in C . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
15.2. xample code to run jrk2cmd in Ruby . . . . . . . . . . . . . . . . . . . . . . . . . 179
15.3. xample code to run jrk2cmd in Python . . . . . . . . . . . . . . . . . . . . . . . . 180
15.4. Running jrk2cmd with Windows shortcuts . . . . . . . . . . . . . . . . . . . . . . . 182
15.5. xample serial code for Linux and macOS in C . . . . . . . . . . . . . . . . . . . . 184
15.6. xample serial code for Windows in C . . . . . . . . . . . . . . . . . . . . . . . . . 189
15.7. xample serial code in Python . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
15.8. xample I²C code for Linux in C . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195
15.9. xample I²C code for Linux in Python . . . . . . . . . . . . . . . . . . . . . . . . . 197
Jrk G2 Motor Controller User’s Guide © 2001–2019 Pololu Corporation
Page 3 of 199

1. Overview
The second-generation Jrk G2 motor controllers are designed to enable easy closed-loop speed
control or position control (but not both!) of a single brushed DC motor. They feature integrated support
for analog voltage or tachometer (frequency) feedback and a variety of control interfaces–USB for
direct connection to a computer, TTL serial and I²C for use with a microcontroller, RC hobby servo
pulses for use in an RC system, and analog voltages for use with a potentiometer or analog joystick.
A free configuration utility simplifies initial setup of the device, provides access to a wide array of
configurable settings, and allows for in-system testing and monitoring of the controller via USB.
Side-by-side comparison of the different Jrk G2 USB Motor Controllers with Feedback.
The table below lists the members of the Jrk G2 family and shows the key differences among them.
Jrk G2
21v3
Jrk G2
18v19
Jrk G2
24v13
Jrk G2
18v27
Jrk G2
24v21
Minimum
operating voltage: 4.5 V(1) 6.5 V 6.5 V 6.5 V 6.5 V
Recommended max
operating voltage: 28 V(2) 24 V(3) 34 V(4) 24 V(3) 34 V(4)
Max nominal
battery voltage: 24 V 18 V 28 V 18 V 28 V
Max continuous current
(no additional cooling): 2.6 A 19 A 13 A 27 A 21 A
Dimensions: 1.0″ × 1.2″ 1.4″ × 1.2″ 1.7″ × 1.2″
1The 5V l gic v ltage dr ps when p wered fr m a supply bel w ab ut 5.2 V.
2Transient perati n (< 500 ms) up t 40 V.
330 V abs lute max.
440 V abs lute max.
Jrk G2 Motor Controller User’s Guide © 2001–2019 Pololu Corporation
1. Overview Page 4 of 199

Features and specifications
• asy open-loop or closed-loop control of one brushed DC motor
• A variety of control interfaces:
◦USB for direct connection to a computer
◦TTL serial operating at 5 V for use with a microcontroller
◦I²C for use with a microcontroller
◦RC hobby servo pulses for use in an RC system
◦Analog voltage for use with a potentiometer or analog joystick
• Feedback options:
◦Analog voltage (0 V to 5 V), for making a closed-loop servo system
◦Frequency, for closed-loop speed control using pulse counting (for higher-
frequency feedback) or pulse timing (for lower-frequency feedback)
◦None, for open-loop speed control
◦Note: the Jrk does not support using quadrature encoders for position control
• Ultrasonic 20 kHz PWM for quieter operation (can be configured to use 5 kHz instead)
• Simple configuration and calibration over USB with free configuration software utility (for
Windows, Linux, and macOS)
• Configurable parameters include:
◦ PID period and PID coefficients (feedback tuning parameters)
◦ Maximum current
◦ Maximum duty cycle
◦ Maximum acceleration and deceleration
◦ rror response
◦ Input calibration (learning) for analog and RC control
• Optional CRC error detection eliminates communication errors caused by noise or software
faults
• Reversed-power protection
• Field-upgradeable firmware
• Optional feedback potentiometer disconnect detection
Jrk G2 Motor Controller User’s Guide © 2001–2019 Pololu Corporation
1. Overview Page 5 of 199

Jrk G2 21v3 USB Motor Controller with
Feedback, bottom view with dimensions.
Jrk G2 18v19 USB Motor Controller with
Feedback, bottom view with
dimensions.
Jrk G2 18v27 USB Motor Controller with
Feedback, bottom view with
dimensions.
Note: This guide only applies to the Jrk G2 motor controllers, which have black circuit
boards. If you have one of the first-generation Jrk 21v3 or Jrk 12v12 controllers, which
have green circuit boards, you can find their user’s guide here [https://www.pololu.com/docs/
0J38].
1.1. Supported operating systems
We support using the Jrk G2 and its configuration software on Windows 7, Windows 8, Windows 10,
Linux, and macOS 10.11 or later. The Jrk G2 software is not likely to work on Windows 10 IoT Core,
which is very different from the normal desktop versions of Windows. The software is open source
[https://github.com/pololu/pololu-jrk-g2-software], so it could be ported to more platforms.
1.2. Comparison to the original Jrk controllers
This section lists most of the things you should consider if you have an existing application using the
original Jrk 21v3 or Jrk 12v12 controllers and are considering upgrading to a Jrk G2.
Jrk G2 Motor Controller User’s Guide © 2001–2019 Pololu Corporation
1. Overview Page 6 of 199

Motor driver improvements
Compared to the original Jrk controllers, the discrete MOSF T H-bridges on the Jrk G2 18v19,
24v13, 18v27, and 24v21 support higher operating voltages and larger output currents. Additionally,
those Jrk G2 models have configurable hardware current limiting: when the motor current exceeds a
configurable threshold, the motor driver uses current chopping to actively limit it.
The Jrk G2 21v3 uses a TB9051FTG motor driver that features hardware current chopping with a fixed
threshold of approximately 6.5 A.
Physical connection changes
You will need to keep some things in mind when updating the physical connections of an existing
application:
• The Jrk G2 circuit boards have different dimensions, mounting hole locations, and pin
locations.
• On the Jrk G2, the RC pulse input should be connected to the pin named RC instead of RX.
• On the Jrk G2, analog control inputs should be connected to SDA/AN instead of RX.
• An analog control potentiometer should generally be powered from SCL and GND if you want
to detect disconnection (instead of AUX and GND).
• The Jrk G2 does not have a pin named FB: analog feedback signals should be connected
to the FBA pin and frequency/tachometer feedback signals should be connected to the FBT
pin.
• An analog feedback potentiometer should generally be powered from AUX and POT− (21v3,
18v19, and 24v13 only), or AUX and GND.
• Unlike the FB pin on the original jrks, the FBA pin does not have a pull-up resistor. If you need
one, you can add it externally or connect FBA to FBT to take advantage of the FBT pull-up
resistor.
• The Jrk G2 uses a USB Micro-B connector (the original Jrks used Mini-B).
Configuration and software changes
There are several changes to keep in mind when configuring the Jrk G2 or updating any software that
communicates with it:
• The Jrk G2 uses different configuration software from the original Jrk controllers. It is
open source [https://github.com/pololu/pololu-jrk-g2-software] and works on Windows, Linux, and
macOS. See Section 3 for installation instructions.
• The Jrk G2 serial protocol is generally a superset of the original Jrk serial protocol, so in many
Jrk G2 Motor Controller User’s Guide © 2001–2019 Pololu Corporation
1. Overview Page 7 of 199

cases, serial interface software running on a microcontroller or computer (using the Jrk’s RX
and TX lines or its virtual USB serial ports) will not need to be modified to work with the Jrk
G2.
• The Jrk G2 native USB interface uses different product IDs and supports a different set of
USB commands. However, the “Set target” and “Motor off” commands are unchanged.
• The “detect baud rate” feature was removed, so you will need to configure the baud rate of
your Jrk ahead of time using the Jrk G2 Configuration Utility if you are controlling it over serial
with a microcontroller.
• The default “Feedback mode” on the Jrk G2 is “None” instead of “Analog”.
• On the Jrk G2, the analog control input pin (SDA/AN) does not have its pull-up resistor
enabled by default, but there is an option to enable it in the “Pin configuration” tab of the Jrk
G2 configuration utility. (The original Jrk always enabled a pull-up on RX, which served as
the analog input.)
• The Jrk G2’s “Feedback deadzone” feature has been changed so that it applies to “Duty cycle
target” instead of “Duty cycle”, which makes it compatible with the new deceleration limits.
• The Jrk G2’s “Duty cycle” variable will move towards zero (either immediately or limited by the
configurable deceleration limit) when there is an error, so the Jrk G2 will respect acceleration
limits properly once the error is resolved.
• The 8-bit “Current” variable (which can be fetched with the serial command 0x8F) has units
of 256 mA on the Jrk G2. A new 16-bit current variable is available with higher resolution.
• Unlike the original Jrk controllers, the Jrk G2 does not reset the state of all of its error
flags when you click “Apply settings” in the configuration utility. rror flags will generally be
preserved.
• The current limiting and current regulation options have changed. See Section 7.6 for details.
New features
The Jrk G2 also supports a variety of new, optional features. These features were added in a
backward-compatible way and should not have an effect on your application unless you purposely use
them. Some of the most notable new features are:
• The Jrk G2 has configurable deceleration limiting. Additionally, you can choose which errors
respect the deceleration limits.
• The Jrk G2 has a new “Wraparound” option for analog feedback, which is useful for systems
that continuously rotate over a full circle.
• PID coefficients and many other settings can be adjusted on the fly over serial, I²C, or USB,
using the new “Set RAM settings” command.
Jrk G2 Motor Controller User’s Guide © 2001–2019 Pololu Corporation
1. Overview Page 8 of 199

• The new “Force duty cycle target” command lets you override the result of the PID algorithm.
• The new “Force duty cycle” command lets you override the result of the PID algorithm while
also ignoring acceleration and deceleration limits.
• New frequency feedback options allow closed-loop speed control using a much larger range
of tachometer frequencies.
• Measurements of the RC input, analog control input, analog feedback input, and the
tachometer input can all be enabled even if the Jrk’s main algorithm is not using them to
control the motor.
• The Jrk G2’s new I²C interface provides another option to connect a microcontroller to the
Jrk, and allows you to control multiple Jrks without using AND gates or level shifters.
• The Jrk G2 can measure the voltage of its VIN power supply and provide this reading over
serial, I²C, and USB.
Jrk G2 Motor Controller User’s Guide © 2001–2019 Pololu Corporation
1. Overview Page 9 of 199

2. Contacting Pololu
We would be delighted to hear from you about any of your projects and about your experience with
the Jrk G2 motor controllers. You can contact us [https://www.pololu.com/contact] directly or post on our
forum [https://forum.pololu.com/]. Tell us what we did well, what we could improve, what you would like
to see in the future, or anything else you would like to say!
Jrk G2 Motor Controller User’s Guide © 2001–2019 Pololu Corporation
2. Contacting Pololu Page 10 of 199

3. Getting started
3.1. Installing Windows drivers and software
To install the drivers and software for the Jrk G2 on a computer running Microsoft Windows, follow
these steps:
1. Download and install the Jrk G2 Software and Drivers for Windows [https://www.pololu.com/
file/0J1494/pololu-jrk-g2-1.4.0-win.msi] (10MB msi).
2. During the installation, Windows will ask you if you want to install drivers. Click “Install” to
proceed.
3. After the installation has completed, plug the Jrk into your computer via USB. Windows
should recognize the Jrk and load the drivers that you just installed.
4. Open your Start Menu and search for “Jrk G2”. Select the “Jrk G2 Configuration Utility”
shortcut (in the Pololu folder) to launch the software.
5. In the upper left corner of the window, where it says “Connected to:”, make sure that it shows
something like “18v19 #01234567”. This indicates the version and serial number of the Jrk
G2 that the software has connected to. If it says “Not connected”, see the troubleshooting
section below.
The Jrk’s native USB interface implements Microsoft OS 2.0 Descriptors, so it will work
on Windows 8.1 or later without needing any drivers. The Jrk’s USB serial ports will work
on Windows 10 or later without drivers.
This Jrk G2 software consists of two programs:
• The Jrk G2 Configuration Utility is a graphical user interface (GUI) for configuring the Jrk,
viewing its status, and controlling it manually. You can find the configuration utility in your
Start Menu by searching for it or looking in the Pololu folder.
• The Jrk G2 Command-line Utility (jrk2cmd) is a command-line utility that can do most of what
the GUI can do, and more. You can open a Command Prompt and type jrk2cmd with no
arguments to a see a summary of its options.
The source code for the software [https://github.com/pololu/pololu-jrk-g2-software] is available.
USB troubleshooting for Windows
If the Jrk G2 software cannot connect to your Jrk after you plug it into the computer via USB, the tips
here can help you troubleshoot the Jrk’s USB connection.
Jrk G2 Motor Controller User’s Guide © 2001–2019 Pololu Corporation
3. Getting started Page 11 of 199

If you are using the Jrk G2 configuration utility, try opening the “Connected to:” drop-down box to see
if there are any entries in the list. If there is an entry, try selecting it to connect to it.
Make sure you have a Jrk G2. The Jrk G2 software does not work with the older Jrk 21v3 or Jrk 12v12.
If you have one of those products, you should refer to its user’s guide instead of this user’s guide.
Make sure you are using software that supports the Jrk G2. The original Jrk Configuration Utility does
not work with the Jrk G2. The Jrk G2 controllers have new USB product IDs. Third-party software for
the older Jrk 21v3 and Jrk 12v12 controllers might need to be updated, depending on how the software
works. If you are a developer of such software, see Section 1.2.
If you have connected any electronic devices to your Jrk besides the USB cable, you should
disconnect them.
You should look at the L Ds of the Jrk. If the L Ds are off, then the Jrk is probably not receiving power
from the USB port. If the green L D is flashing very briefly once per second, then the Jrk is receiving
power from USB, but it is not receiving any data. These issues can be caused by using a broken USB
port, using a broken USB cable, or by using a USB charging cable that does not have data wires.
Using a different USB port and a different USB cable, both of which are known to work with other
devices, is a good thing to try. Also, if you are connecting the Jrk to your computer via a USB hub, try
connecting it directly.
If the Jrk’s green L D is on all the time or flashing slowly, but you can’t connect to it in the Jrk software,
then there might be something wrong with your computer. A good thing to try is to unplug the Jrk from
USB, reboot your computer, and then plug it in again.
If that does not help, you should go to your computer’s Device Manager and locate all the entries for
the Jrk. Be sure to look in these categories: “Other devices”, “Ports (COM & LPT)”, and “Universal
Serial Bus devices”.
If the driver for the Jrk’s native USB interface is working, you should see an entry in the “Universal
Serial Bus devices” category named something like “Pololu Jrk G2 18v19” (or the corresponding name
if you have a different version).
If the drivers for the Jrk’s USB serial ports are working, you should see two entries in the “Ports
(COM & LPT)” category named something like “Pololu Jrk G2 18v19 Command Port” and “Pololu
Jrk G2 18v19 TTL Port”. The serial ports might be named “USB Serial Device” instead if you are
using Windows 10 or later and you plugged the Jrk into your computer before installing our drivers
for it. The generic names in the Device Manager will not prevent you from using the ports, but we
recommend fixing the names by right-clicking on each “USB Serial Device” entry, selecting “Update
Driver Software…”, and then selecting “Search automatically for updated driver software”. Windows
should find the drivers you already installed, which contain the correct name for the port.
Jrk G2 Motor Controller User’s Guide © 2001–2019 Pololu Corporation
3. Getting started Page 12 of 199

If any of the entries for the Jrk in the Device Manager has a yellow triangle displayed over its icon, you
should double-click on the entry to get information about the error that is happening.
If you do not see entries for the Jrk in the Device Manager, then you should open the “View” menu
and select “Devices by connection”. Then expand the entries until you find your computer’s USB
controllers, hubs, and devices. See if there are any entries in the USB area that disappear when you
unplug the Jrk. This might give you important information about what is going wrong.
Do not attempt to fix driver issues in your Device Manager using the “Add legacy hardware” option.
This is only for older devices that do not support Plug-and-Play, so it will not help. If you already tried
this option, we recommend unplugging the Jrk from USB and then removing any entries you see for
the Jrk by right-clicking on them and selecting “Uninstall”. Do not check the checkbox that says “Delete
the driver software for this device”.
Windows 10 Device Manager showing the Jrk G2.
3.2. Installing Linux software
To install the software for the Jrk G2 on a computer running Linux, follow these steps:
1. Download the version for your system from this list:
◦Jrk G2 Software for Linux (x86) [https://www.pololu.com/file/0J1500/pololu-jrk-
Jrk G2 Motor Controller User’s Guide © 2001–2019 Pololu Corporation
3. Getting started Page 13 of 199

g2-1.4.0-linux-x86.tar.xz] (9MB xz) — works on 32-bit and 64-bit systems
◦Jrk G2 Software for Linux (Raspberry Pi) [https://www.pololu.com/file/0J1501/pololu-
jrk-g2-1.4.0-linux-rpi.tar.xz] (6MB xz) — works on the Raspberry Pi and might work on
other ARM Linux systems
2. In a terminal, use cd to navigate to the directory holding the downloaded file. For example,
run cd ~/Downloads if it was downloaded to the “Downloads” folder in your home directory.
3. Run tar -xvf pololu-jrk-g2-*.tar.xz to extract the software. If you downloaded multiple
versions of the software, you should use an exact file name instead of an asterisk.
4. Run sudo pololu-jrk-g2-*/install.sh to install the software. You will need to have sudo
privilege on your system and you might need to type your password at this point. Look at the
output of the script to see if any errors happened.
5. After the installation has completed, plug the Jrk into your computer via USB. If you already
connected the Jrk earlier, unplug it and plug it in again to make sure the newly-installed udev
rules are applied.
6. Run jrk2cmd --list to make sure the software can detect the Jrk. This command should
print the serial number and product name of the Jrk. If it prints nothing, see the “USB
troubleshooting for Linux” section below.
7. If you are using a graphical desktop environment, run jrk2gui to start the configuration
utility. In the upper left corner of the window, where it says “Connected to:”, make sure that it
shows something like “18v19 #01234567”. This indicates the version and serial number of the
Jrk G2 that the software has connected to. If it says “Not connected”, see the troubleshooting
section below.
This Jrk G2 software consists of two programs:
• The Jrk G2 Configuration Utility (jrk2gui) is a graphical user interface (GUI) for configuring
the Jrk G2 and viewing its status. You can open a terminal and type jrk2gui to run it.
• The Jrk G2 Command-line Utility (jrk2cmd) is a command-line utility that can do most of what
the GUI can do, and more. You can open a terminal and type jrk2cmd with no arguments to
a see a summary of its options.
The Jrk G2 software for Linux is statically linked; it does not depend on any shared libraries. The
source code for the software [https://github.com/pololu/pololu-jrk-g2-software] is available. The Jrk G2
does not require any driver installation on Linux.
Software installation troubleshooting for Linux
If you do not have sudo privilege or you do not remember your password, you can skip running
Jrk G2 Motor Controller User’s Guide © 2001–2019 Pololu Corporation
3. Getting started Page 14 of 199

install.sh and just run the programs directly from the directory you extracted them to. You should
also consider moving the software to a more permanent location and adding that location to your PATH
as described below.
If you get a “No such file or directory” error while running ./install.sh , it is possible that your
system is missing one of the directories that the install script assumes will be present. Please contact
[https://www.pololu.com/contact] us to let us know about your system so we can consider supporting it
better in the future.
If you get the error “command not found” when you try to run jrk2cmd or jrk2gui , then you should
run echo $PATH to see what directories are on your PATH, and then make sure one of those directories
contains the Jrk executables or symbolic links to them. The installer puts symbolic links in /usr/local/
bin , so if that directory is not on your PATH, you should run export PATH=$PATH:/usr/local/bin to
add it. Also, you might want to put that line in your ~/.profile file so the directory will be on your
PATH in future sessions.
If you get the error “cannot execute binary file: xec format error” when you try to run jrk2cmd or
jrk2gui , then it is likely that you downloaded the wrong version of the software from the list above.
If all of the listed versions give you this error, you will probably need to compile the software from
source by following the instructions in BUILDING.md [https://github.com/pololu/pololu-jrk-g2-software/blob/
master/BUILDING.md] in the source code [https://github.com/pololu/pololu-jrk-g2-software]. Please contact
[https://www.pololu.com/contact] us to let us know about your system so we can consider supporting it
better in the future.
If the Jrk G2 Configuration Utility window is too big to fit on your screen properly, try setting the
JRK2GUI_FONT_SIZE environment variable to “6” before running the software. You can do this by
running the command JRK2GUI_FONT_SIZE=6 jrk2gui in your terminal. You can experiment with font
sizes other than 6 to see if they work for you. You could also add the line export JRK2GUI_FONT_SIZE=6
to your ~/.profile to make the change permanent.
USB troubleshooting for Linux
If the Jrk G2 software cannot connect to your Jrk after you plug it into the computer via USB, the tips
here can help you troubleshoot the Jrk’s USB connection.
If you are using the Jrk G2 Configuration Utility, try opening the “Connected to:” drop-down box to see
if there are any entries in the list. If there is an entry, try selecting it to connect to it.
Make sure you have a Jrk G2. The Jrk G2 software does not work with the older Jrk 21v3 or Jrk 12v12.
If you have one of those products, you should refer to its user’s guide instead of this user’s guide.
Make sure you are using software that supports the Jrk G2. The original Jrk Configuration Utility does
Jrk G2 Motor Controller User’s Guide © 2001–2019 Pololu Corporation
3. Getting started Page 15 of 199

not work with the Jrk G2. The Jrk G2 controllers have new USB product IDs. Third-party software for
the older Jrk 21v3 and Jrk 12v12 controllers might need to be updated, depending on how the software
works. If you are a developer of such software, see Section 1.2.
If you have connected any electronic devices to your Jrk besides the USB cable, you should
disconnect them.
You should look at the L Ds of the Jrk. If the L Ds are off, then the Jrk is probably not receiving power
from the USB port. If the green L D is flashing very briefly once per second, then the Jrk is receiving
power from USB, but it is not receiving any data. These issues can be caused by using a broken USB
port, using a broken USB cable, or by using a USB charging cable that does not have data wires.
Using a different USB port and a different USB cable, both of which are known to work with other
devices, is a good thing to try. Also, if you are connecting the Jrk to your computer via a USB hub, try
connecting it directly.
If the Jrk’s green L D is on all the time or flashing slowly, but you can’t connect to it in the Jrk software,
then there might be something wrong with your computer. A good thing to try is to unplug the Jrk from
USB, reboot your computer, and then plug it in again.
If you get a “Permission denied” error when trying to connect to the Jrk, you should make sure to copy
the 99-pololu.rules file into /etc/udev/rules.d and then unplug the Jrk and plug it back in again.
The install script normally takes care of installing that file for you.
If that does not help, you should try running lsusb to list the USB devices recognized by your
computer. Look for the Pololu vendor ID, which is 1ffb. You should also try running dmesg right after
plugging in the Jrk to see if there are any messages about it.
3.3. Installing macOS software
To install the configuration software for the Jrk G2 on a computer running macOS, follow these steps:
1. Download the Jrk G2 Software for macOS [https://www.pololu.com/file/0J1502/pololu-jrk-
g2-1.4.0-macos.pkg] (8MB pkg).
2. Double-click on the downloaded file to run it, and follow the instructions.
3. After the installation has completed, plug the Jrk into your computer via USB.
4. In your Applications folder, look for “Pololu Jrk G2”. Double-click on “Pololu Jrk G2” to start
the configuration utility.
5. In the upper left corner of the window, where it says “Connected to:”, make sure that it shows
something like “18v19 #01234567”. This indicates the version and serial number of the Jrk
G2 that the software has connected to. If it says “Not connected”, see the troubleshooting
Jrk G2 Motor Controller User’s Guide © 2001–2019 Pololu Corporation
3. Getting started Page 16 of 199

section below.
This Jrk G2 software consists of two programs:
• The Jrk G2 Configuration Utility (jrk2gui) is a graphical user interface (GUI) for configuring the
Jrk G2 and viewing its status. You can run it by clicking on “Pololu Jrk G2” in the Applications
folder, or you can open a terminal and type jrk2gui to run it.
• The Jrk G2 Command-line Utility (jrk2cmd) is a command-line utility that can do most of what
the GUI can do, and more. You can open a terminal and type jrk2cmd with no arguments to
a see a summary of its options.
The source code for the software [https://github.com/pololu/pololu-jrk-g2-software] is available. The Jrk
G2 does not require any driver installation on macOS.
Software installation troubleshooting for macOS
If you get the error “command not found” when you try to run jrk2cmd or jrk2gui , then you should try
starting a new Terminal window. The installer adds a file named 99-pololu-jrk2 in the /etc/paths.d
directory to make sure the software gets added to your PATH, but the change will not take effect until
you open a new Terminal window.
The Jrk G2 software will not work on versions of macOS prior to 10.11.
USB troubleshooting for macOS
If the Jrk G2 software cannot connect to your Jrk after you plug it into the computer via USB, the tips
here can help you troubleshoot the Jrk’s USB connection.
If you are using the Jrk G2 Configuration Utility, try opening the “Connected to:” drop-down box to see
if there are any entries in the list. If there is an entry, try selecting it to connect to it.
Make sure you have a Jrk G2. The Jrk G2 software does not work with the older Jrk 21v3 or Jrk 12v12.
If you have one of those products, you should refer to its user’s guide instead of this user’s guide.
Make sure you are using software that supports the Jrk G2. The original Jrk Configuration Utility does
not work with the Jrk G2. The Jrk G2 controllers have new USB product IDs. Third-party software for
the older Jrk 21v3 and Jrk 12v12 controllers might need to be updated, depending on how the software
works. If you are a developer of such software, see Section 1.2.
If you have connected any electronic devices to your Jrk besides the USB cable, you should
disconnect them.
You should look at the L Ds of the Jrk. If the L Ds are off, then the Jrk is probably not receiving power
Jrk G2 Motor Controller User’s Guide © 2001–2019 Pololu Corporation
3. Getting started Page 17 of 199

from the USB port. If the green L D is flashing very briefly once per second, then the Jrk is receiving
power from USB, but it is not receiving any data. These issues can be caused by using a broken USB
port, using a broken USB cable, or by using a USB charging cable that does not have data wires.
Using a different USB port and a different USB cable, both of which are known to work with other
devices, is a good thing to try. Also, if you are connecting the Jrk to your computer via a USB hub, try
connecting it directly.
If the Jrk’s green L D is on all the time or flashing slowly, but you can’t connect to it in the software,
then there might be something wrong with your computer. A good thing to try is to unplug the Jrk from
USB, reboot your computer, and then plug it in again.
Another thing to try is to run dmesg right after plugging in the Jrk to see if there are any messages
about it.
Jrk G2 Motor Controller User’s Guide © 2001–2019 Pololu Corporation
3. Getting started Page 18 of 199

4. Basic setup
4.1. Choosing the motor, power supply, and Jrk
The information in this section can help you select a motor [https://www.pololu.com/category/22/motors-and-
gearboxes], a power supply [https://www.pololu.com/category/84/regulators-and-power-supplies], and a Jrk G2
controller that will work well together.
The Jrk requires a DC power supply. The Jrk is designed to drive a brushed DC motor, either by itself
or as part of a device like a linear actuator [https://www.pololu.com/category/127/linear-actuators].
Voltage and current ratings
When selecting your motor, power supply, and Jrk controller, you must consider the voltage and
current ratings of each.
The rated voltage of a DC motor is the voltage it was designed to run at, and this is the voltage
at which it will draw its rated currents. It is fine to drive a motor with a lower voltage than what it is
rated for, in which case its current draw will be proportionally lower, as well as its speed and torque.
Conversely, using a higher-than-rated voltage will result in proportionally higher current draw, speed,
and torque, and could negatively affect the lifetime of the motor. However, you can limit the PWM
duty cycle used to drive the motor to keep its average current draw within rated limits. (For example,
running a 6 V motor at 12 V but limiting its duty cycle to a maximum of 50% should generally be OK).
The stall current of a DC motor is how much current the motor will draw when power is applied but it
is not spinning (for example, if the motor shaft is prevented from rotating), producing maximum torque
and minimum (zero) speed. The stall current depends on the voltage that is applied to the motor, and
the stall current is usually measured at the rated voltage of the motor. Most brushed DC motors are
not designed to be stalled for extended periods and can be damaged if they are.
It is not unusual for the stall current of a motor to be an order of magnitude (10×) higher
than its free-run current. When a motor is supplied with full power from rest, it briefly
draws the full stall current, and it draws nearly twice the stall current if abruptly switched
from full speed in one direction to full speed in the other direction.
The free-run current of a DC motor (or no-load current) is how much current the motor draws when it
is running freely, producing maximum speed and minimum torque (since there is no external opposing
torque). Like the stall current, the free-run current depends on the voltage that is applied to the motor,
and is usually measured at the rated voltage of the motor.
The voltage range of your power supply is the range of voltages you expect your power supply to
produce while operating. There is usually some variation in the output voltage so you should treat it as
Jrk G2 Motor Controller User’s Guide © 2001–2019 Pololu Corporation
4. Basic setup Page 19 of 199

a range instead of just a single number. In particular, keep in mind that a fully-charged battery might
have a voltage that is significantly higher than its nominal voltage.
The current limit of a power supply is how much current the power supply can provide. Note that the
power supply will not force this amount of current through your system; the properties of the system
and the voltage of the power supply determine how much current will flow, but there is a limit to how
much current the power supply can provide.
The minimum operating voltage of a Jrk is the lowest voltage that is acceptable for the Jrk’s motor
power supply. If you try to power the Jrk with a voltage lower than this, it might fail to deliver power to
the motor, but it should not cause any permanent damage.
The absolute maximum operating voltage of a Jrk is the maximum voltage that can be tolerated by
the Jrk. If the voltage of the power supply rises above this voltage, even for just a brief period of time,
the Jrk could be permanently damaged.
The recommended maximum operating voltage of a Jrk is the maximum voltage we recommend
using for the Jrk’s motor power supply. We have chosen this number to be significantly lower than the
absolute max operating voltage so that if there is noise on the power supply it is unlikely to exceed the
absolute max operating voltage.
The maximum nominal battery voltage of a Jrk is the maximum nominal voltage we recommend
using for batteries that supply power to the Jrk. We have chosen this number to be significantly
lower than the recommended maximum operating voltage because fully-charged batteries can have a
voltage that is significantly higher than their nominal voltage.
The maximum continuous current of a Jrk indicates the motor current that it can continuously
supply without overheating in typical conditions (at room temperature with no additional cooling). The
Jrk’s MOSF Ts can handle large current spikes for short durations (e.g. 100 A for a few milliseconds),
and the Jrk’s hardware current limit can be configured to help it handle large transients, such as when
starting a motor. However, note that the Jrk does not have an over-temperature shut-off. (The Jrk’s
motor driver error can indicate an over-temperature fault, but the Jrk does not directly measure the
temperature of the MOSF Ts, which are usually the first components to overheat.) As a result, an
over-temperature or over-current condition can still cause permanent damage.
The voltage and current ratings of the different Jrk G2 controllers are shown in the table below.
Jrk G2 Motor Controller User’s Guide © 2001–2019 Pololu Corporation
4. Basic setup Page 20 of 199