Pololu Jrk User Manual

Pololu Jrk USB Motor Controller

User's Guide

http://www.pololu.com/docs/0J38/all Page 1 of 45

1. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

1.a. Module Pinout and Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

1.b. Supported Operating Systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

1.c. PID Calculation Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

2. Contacting Pololu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

3. Configuring the Motor Controller . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

3.a. Installing Windows Drivers and the Configuration Utility . . . . . . . . . . . . . . . . . . . . . . . . . 11

3.b. Input Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

3.c. Feedback Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

3.d. PID Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

3.e. Motor Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

3.f. Error Response Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

3.g. The Plots Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

3.h. Upgrading Firmware . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

4. Using the Serial Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

4.a. Serial Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

4.b. TTL Serial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

4.c. Command Protocols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

4.d. Cyclic Redundancy Check (CRC) Error Detection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

4.e. Motor Control Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

4.f. Error Reporting Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

4.g. Variable Reading Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

4.h. Daisy-Chaining . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

4.i. Serial Example Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

4.i.1. Cross-platform C . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

4.i.2. Windows C . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

5. Setting Up Your System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

6. Writing PC Software to Control the Jrk . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

Page 2 of 45

1. Overview

The jrk family of versatile, general-purpose motor controllers supports a variety of interfaces, including USB. Analog voltage and tachometer (frequency) feedback options allow quick implementation of closed-loop servo systems, and a free configuration utility (for Windows) allows easy calibration and configuration through the USB port.

There are two different jrk motor controllers:

The jrk 21v3 [http://www.pololu.com/product/1392] has a broad operating range from 5 V to 28 V. The continuous output current of 3 A (5 A peak) allow this board to control most small DC brushed motors.

The jrk 12v12 [http://www.pololu.com/product/1393] has an operating range from 6 V to 16 V. The high continuous output current of 12 A (30 A peak) allow this board to control many medium-sized DC brushed motors

Main Features of the Jrk 21v3

Pololu jrk 21v3 USB motor controller with

dimensions.

• 5 V to 28 V operating supply range.

• 3 A maximum continuous current output (5 A peak).

• Automatic motor driver shutdown on under-voltage, over-current, and over-temperature conditions.

Main Features of the Jrk 12v12

• 6 V to 16 V operating supply range.

Bottom of the jrk 12v12 USB motor controller

with feedback with dimensions.

• 12 A maximum continuous current output (30 A peak).

Main Features of all Jrk Motor Controllers

• Simple bidirectional control of one DC brush motor.

• Four communication or control options: ◦ USB interface for direct connection to a PC.

◦ Full-duplex, TTL-level asynchronous serial interface for direct connection to microcontrollers or other embedded controllers.

◦ Hobby radio control (RC) pulse width (PWM) interface for direct connection to an RC receiver or RC servo controller.

◦ 0–5 V analog voltage interface for direct connection to potentiometers and analog joysticks.

• Two closed-loop feedback options: ◦ 0–5 V analog voltage.

◦ Frequency/tachometer digital input up to 2 MHz with 1 ms PID period.

◦ (Open-loop control with no feedback also available.)

1. Overview Page 3 of 45

• Simple configuration and calibration over USB with free configuration program (Windows 8, Windows 7,

Vista, Windows XP compatible).

• Configurable parameters include: ◦ PID period and PID constants (feedback tuning parameters).

◦ Maximum current.

◦ Maximum duty cycle.

◦ Maximum acceleration.

◦ Error 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.

Specifications

_ Jrk 21v3 Jrk 12v12

Motor channels: 1 1

Operating voltage: 5 – 28 V 6 – 16 V

Continuous output current: 3 A 12 A

Peak output current: 5 A 30 A

Auto-detect baud rate range: 300 – 115,200 bps 300 – 115,200 bps

Available fixed baud rates: 300 – 115,200 bps 300 – 115,200 bps

Available PWM frequencies: 20 kHz, 5 kHz 20 kHz, 5 kHz

Reverse voltage protection?: Yes Yes

USB connector style: USB Mini-B USB Mini-B

Included Hardware

1. Overview Page 4 of 45

The jrk 21v3 and jrk 12v12 each ship with a straight 0.1″ breakaway male header [http://www.pololu.com/product/965] strip and two appropriately sized 2-pin terminal blocks (3.5 mm pitch for the 21v3 and 5 mm pitch for the 12v12). To provide maximum flexibility, none of these parts are soldered to the board (unless you ordered our fully assembled

jrk 21v3 [http://www.pololu.com/product/1394], which ships with these parts soldered in as shown in the assembled jrk

21v3 picture above).

For the most compact installation, you can solder wires directly to the jrk pads themselves and skip using the included hardware. The included hardware allows you to make less permanent connections. You can break the header strip into smaller pieces, such as an 8×1 piece and two 3×1 pieces, and solder these strips into the jrk’s I/O pads.

The three mounting holes are intended for use with #2 screws [http://www.pololu.com/category/101/nuts-and-screws] (not included).

Note: A USB A to mini-B cable [http://www.pololu.com/product/130] (not included) is required to connect this device to a computer.

1.a. Module Pinout and Components

Pololu jrk 21v3 USB motor controller with feedback, labeled top view.

1. Overview Page 5 of 45

Pololu jrk 12v12 USB motor controller with feedback, labeled top view.

The Pololu jrk USB motor controller can connect to a computer’s USB port via a USB A to mini-B cable

[http://www.pololu.com/product/130] (not included). The USB connection is used to configure the motor controller. It can

also be used to send commands to the motor controller, get information about the motor controller’s current state, and send and receive TTL serial bytes on the TX and RX lines.

Power for the motor must be supplied to the jrk on the VIN and GND lines pictured on the right side of the diagram above. Your power source must be capable of delivering the current your motor will draw. The jrk has reverse power protection on the motor power input lines, so the board will not be damaged if the motor power inputs are accidentally switched. If the VIN supply is not present, the jrk’s microcontroller can be powered directly from USB and perform all of its functions except for driving the motor.

For the jrk 21v3, the input voltage should be 5–28 V (the recommended operating voltage is 8–28 V, but the jrk 21v3’s motor driver has derated performance down to 5 V and transient protection to 40 V). The jrk 21v3’s motor driver can supply a continuous 3 A with peaks up to 5 A.

For the jrk 12v12, the input voltage should be 6–16 V. The jrk 12v12’s motor driver can supply a continuous 12 A with peaks up to 30 A.

The jrk has a linear voltage regulator that derives 5 V from the VIN supply. The 5 V supply is used as the internal logic supply for the jrk and is also available at several pins for powering devices such as external microcontrollers and feedback sensors (such as potentiometers). Because the regulator must dissipate excess power as heat, the available output current is dependent on the input voltage: 50 mA is available for VIN up to 12 V; the available current drops off linearly from 50 mA at 12 V to zero at 30 V.

The jrk has three indicator LEDs:

• The green USB LED indicates the USB status of the device. When the jrk is not connected to a computer via

the USB cable, the green LED will be off. When you connect the jrk to USB, the green LED will start blinking slowly. The blinking continues until the jrk receives a particular message from the computer indicating that the jrk’s USB drivers are installed correctly. After the jrk gets this message, the green LED will be on, but it will flicker briefly when there is USB activity. The configuration utility constantly streams data from the jrk, so when the configuration utility is running and connected to the jrk, the green LED will flicker constantly.

1. Overview Page 6 of 45

• The red error LED indicates an error. If there is an error stopping the motor (besides the Awaiting Command

error bit), then the red LED will be on. The red LED is tied to the active-high output ERR, so when there is an error, ERR will be driven high, and otherwise it will be pulled low through the LED.

• The yellow output status LED indicates the status of the motor. If the yellow LED is off, then an error (other

than the Awaiting Command error bit) is stopping the motor. If the yellow LED is flashing slowly (once per second), then either the motor is off (the Awaiting Command Error bit is set) or the jrk is in speed control mode and the duty cycle is zero. If the yellow LED is on solid, then the motor is on and the motor has reached the desired state. For analog and pulse width feedback modes, this means that the target is within 20 of the scaled feedback. For speed control mode, this means that the duty cycle equals the duty cycle target. If the yellow LED is flashing quickly (16 times per second), then the motor is on and the motor has not reached its desired state.

The ERR line is an optional output that is tied to the red error LED described above. It is driven high when the red LED is on, and it is a pulled low through the red LED when the red LED is off. Since the ERR line is never driven low, it is safe to connect the ERR line of multiple jrks together. Please note, however, that doing this will cause the error LEDs of all connected jrks to turn on whenever one jrk experiences an error; the ERR output of the jrk experiencing the error will drive the LEDs of any other jrks it is connected to, even though they are not experiencing error conditions themselves. For more information on the possible error conditions and response options, please see

Section 3.f.

The TX line transmits non-inverted, TTL (0 – 5 V) serial bytes. These bytes can either be responses to serial commands sent to the jrk, or arbitrary bytes sent from the computer via the USB connection. For more information about the jrk’s serial interface, see Section 4.

The RX line is the jrk’s control input. In serial input mode, the RX line is used to receive non-inverted, TTL (0 – 5 V) serial bytes. These bytes can either be serial commands for the jrk, arbitrary bytes to send back to the computer via the USB connection, or both. For more information about the jrk’s serial interface, see Section 4. In analog input mode, RX is the analog input line used to determine the system’s target output. In pulse width input mode, the jrk measures the duration of pulses on the RX line to determine the system’s target output. Please see Section 3.b for more information on control input signals.

The FB line is the jrk’s feedback input. In analog feedback mode, the voltage on the FB line is used as a measurement of the output of the system. In frequency feedback mode, the frequency of low-to-high transitions on the FB line is used as a measurement of the output of the system. Please see Section 3.c for more information on feedback signals.

The AUX line is an output that is generally high whenever the jrk has power. The line will only go low for two reasons:

1. If the jrk’s microcontroller goes to sleep (because there is no VIN supply and the device has entered USB

suspend mode), the pin is tri-stated and pulled low through a resistor.

2. If the Detect disconnect with AUX option is enabled for either the feedback or the input, then the jrk will

drive AUX low for about 150 μs each PID period to check if the feedback and/or analog inputs are disconnected.

The RST pin can be driven low to perform a hard reset of the jrk’s microcontroller, but this should generally not be necessary for typical applications. The line is internally pulled high, so it is safe to leave this pin unconnected.

1.b. Supported Operating Systems

The jrk works under Microsoft Windows 8, Windows 7, Windows Vista, Windows XP, Linux, and Max OS X 10.7 or later.

The configuration utility works only in Windows, so the jrk must be initially configured from a Windows computer, but after that it can be controlled from a Linux or Mac computer.

1. Overview Page 7 of 45

Under Linux, the two virtual COM ports created by the jrk should appear as devices with names like /dev/ttyACM0 and /dev/ttyACM1 (the number depends on how many other ACM devices you have plugged in) and you can use any terminal program (such as screen) to send and receive bytes on those ports. Alternatively, you can use the Pololu USB Software Development Kit which supports Linux and has example applications that control the jrk using its native USB interface (see Section 6).

Under Mac OS X 10.7 or later, the two virtual COM ports created by the jrk should appear as devices with names like /dev/cu.usbmodem00034567 and you can use any terminal program (such as screen) to send and receive bytes on those ports.

Mac OS X compatibility: we have confirmed that the jrk works on Mac OS X 10.7 and we can assist with advanced technical issues, but most of our tech support staff does not use Macs, so basic support for Mac OS X is limited.

1.c. PID Calculation Overview

The jrk is designed to be part of a control system in which the output (usually a motor position or speed) is constantly adjusted to match a specified target value. To achieve this, it constantly measures the state of the system and responds based on the latest information. The information processing performed by the jrk is outlined in the diagram below:

Diagram of a typical feedback system, showing

quantities computed by the jrk.

In this diagram, each arrow represents a specific number measured or computed by the jrk, and the blue boxes represent the internal computations that each occur once per PID period. The PID period can be set in 1 ms increments and is one of about 50 configurable parameters that affect the behavior of the system. For more information about configuring the jrk, see Section 3. The jrk uses the following measurements to determine the output:

• The input is measured as a value from 0 to 4095. In analog voltage input mode, this represents a voltage level

of 0 to 5 V. In RC mode, the number is a pulse width in units of 2/3 μs. The input is adjusted according to input scaling parameters to determine the target, also a value from 0 to 4095 (see Section 3.b).

1. Overview Page 8 of 45

• The feedback is measured as a value from 0 to 4095. In analog voltage feedback mode, this represents a

voltage level of 0 to 5 V. In digital frequency mode, it is a representation of the output speed (see Section 3.c.) The jrk uses this value to compute the scaled feedback, which is a representation of the output of the entire control system. A scaled feedback of 0 should represent the minimum position of the system, and 4095 should represent the maximum position.

• The current through the motor is measured as a number from 0 to 255. A calibration value relates this to an

actual current in amps.

Every PID cycle, the jrk performs the following computations to determine the behavior of the motor (see Section

3.d for more information):

1. The error is computed as the difference of scaled feedback and target (error = scaled feedback − target).

2. An implementation of the PID algorithm is applied to the error. PID stands for the three terms that are added

together: proportional (proportional to the error), integral (proportional to the accumulated sum of the error over time), and derivative (proportional to the difference of the error relative to the previous PID period.) The three constants of proportionality are the most important parameters determining the behavior of the control system. The result of the PID algorithm is a number from -600 to +600 called the duty cycle target.

3. The duty cycle target is reduced according to various configurable limits, including acceleration, current, and

maximum duty cycle limits (Section 3.e). The limits are intended to prevent the system from causing damage to itself under most circumstances.

The resulting value becomes the duty cycle of the PWM (pulse width modulation) signal applied to the motor. A value of +600 corresponds to 100% duty cycle in the forward direction, a value of -600 corresponds to 100% duty cycle in the reverse direction, and a value of 0 corresponds to 0% duty cycle or off.

Various parameters and commands have an effect on the steps described above. For example, feedback may be turned off so that the jrk can become a simple speed controller; in this case the PID calculation is bypassed and the duty cycle target is just equal to the target minus 2048. In this mode, limits applied to the duty cycle continue to provide a useful way of preventing damage to the system. As another example, a command to turn the system off prevents the motors from being driven, but all measurements and calculations continue to occur normally.

1. Overview Page 9 of 45

2. Contacting Pololu

You can check the Pololu Jrk 21v3 USB Motor Controller page

[http://www.pololu.com/product/1392] or the Pololu Jrk 12v12 USB Motor

Controller page [http://www.pololu.com/product/1393] for additional information.

We would be delighted to hear from you about any of your projects and about your experience with the jrk. You can contact us [http://www.pololu.com/contact] directly or post on our forum [http://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!

2. Contacting Pololu Page 10 of 45

3. Configuring the Motor Controller

3.a. Installing Windows Drivers and the Configuration Utility

If you use Windows XP, you will need to have Service Pack 3 [http://www.microsoft.com/downloads/

details.aspx?FamilyId=68C48DAD-BC34-40BE-8D85-6BB4F56F5110] installed before installing the drivers for

the jrk. See below for details.

Before you connect your Pololu jrk USB motor controller to a computer running Microsoft Windows, you must install its drivers:

1. Download the jrk drivers and configuration software [http://www.pololu.com/file/download/jrk-

windows-121204.zip?file_id=0J221] (5MB zip)

2. Open the ZIP archive and run setup.exe. If the installer fails, you may have to extract all the files to a

temporary directory, right click setup.exe, and select “Run as administrator”. The installer will guide you through the steps required to install the Pololu Jrk Configuration Utility, the jrk command-line utility (JrkCmd), and the jrk drivers on your computer.

3. During the installation, Windows will ask you if you want to install the drivers. Click “Install” (Windows 8,

7, and Vista) or “Continue Anyway” (Windows XP).

4. After the installation is finished, your start menu will have a shortcut to the Jrk Configuration Utility (in

the Pololu folder). This is a Windows application that allows you to change all of the settings of your motor controller, as well as see real-time information about its state.

Windows 8, Windows 7, and Windows Vista users: Your computer should now automatically install the necessary drivers when you connect a jrk. No further action from you is required.

Windows XP users: Follow steps 5-9 for each new jrk you connect to your computer.

5. Connect the device to your computer’s USB port. The jrk shows up as three devices in one so your XP

computer will detect all three of those new devices and display the “Found New Hardware Wizard” three times. Each time the “Found New Hardware Wizard” pops up, follow steps 6-9.

6. When the “Found New Hardware Wizard” is displayed, select “No, not this time” and click “Next”.

3. Configuring the Motor Controller Page 11 of 45

7. On the second screen of the “Found New Hardware Wizard”, select “Install the software automatically” and

click “Next”.

3. Configuring the Motor Controller Page 12 of 45

8. Windows XP will warn you again that the driver has not been tested by Microsoft and recommend that you

stop the installation. Click “Continue Anyway”.

9. When you have finished the “Found New Hardware Wizard”, click “Finish”. After that, another wizard will

pop up. You will see a total of three wizards when plugging in the jrk. Follow steps 6-9 for each wizard.

3. Configuring the Motor Controller Page 13 of 45

If you use Windows XP and experience problems installing or using the serial port drivers, the cause of your problems might be a bug in older versions of Microsoft’s usb-to-serial driver usbser.sys. Versions of this driver prior to version

5.1.2600.2930 will not work with the jrk. You can check what version of this driver you have by looking in the “Details” tab of the “Properties” window for usbser.sys in C:\Windows\System32\drivers. To get the fixed version of the driver, you will need to install Service Pack 3 [http://www.microsoft.com/downloads/details.aspx?FamilyId=68C48DAD-

BC34-40BE-8D85-6BB4F56F5110]. If you do not want Service Pack 3, you can try installing Hotfix KB918365 instead, but

some users have had problems with the hotfix that were resolved by upgrading to Service Pack 3. The configuration utility will work even if the serial port drivers are not installed properly.

After installing the drivers, if you go to your computer’s Device Manager and expand the “Ports (COM & LPT)” list, you should see two COM ports: the Command Port and the TTL Port. In parentheses after these names, you will see the name of the port (e.g. “COM5” or “COM6”). If you expand the “Pololu USB Devices” list you should see an entry for the Pololu jrk motor controller.

3. Configuring the Motor Controller Page 14 of 45

+ 31 hidden pages