10. Variable reference

The Jrk G2 maintains a set of variables in RAM that contain information about its inputs, outputs, and status. Many of these variables are displayed in real time in the “Status” tab of the Jrk G2 Configuration Utility. You can also retrieve variables from the Jrk over USB by running jrk2cmd --status or jrk2cmd --status --full (the --full option shows every variable). The Jrk’s “Get variable” and “Get variables” commands allow you to read the variables over serial, USB, and I²C.

This section lists all of the variables that the Jrk G2 supports. For each variable, this section contains several pieces of information, if applicable:

• The Offset of each variable is its location within the variable data. The offset is measured in bytes. You can use this offset to specify which variables you want to read in the “Get variable” and “Get variables” commands.
• The Type of each variable specifies how many bits the variable occupies, and says whether it is signed or unsigned. All the multi-byte variables use little-endian format, meaning that the least-significant byte comes first.
• The Range of each variable specifies what values the variable can have.
• The Units of each variable specify the relationship between values of the variable real-world quantities.
• The Data of each variable indicates how to interpret different possible values of the variable.

List of variables

• Input
• Target
• Feedback
• Scaled feedback
• Integral
• Duty cycle target
• Duty cycle
• Current (low resolution)
• PID period exceeded
• PID period count
• Error flags halting
• Error flags occurred
• Force mode
• VIN voltage
• Current
• Last reset
• Up time
• RC pulse width
• FBT reading
• Analog reading SDA/AN
• Analog reading FBA
• Digital readings
• Raw current
• Hard current limit
• Last duty cycle
• Current chopping consecutive count
• Current chopping occurrence count

Input

Offset	0x00
Type	unsigned 16-bit
Range	0 to 4095
Units	Depends on the input mode

The input variable is a raw, unscaled value representing a measurement taken by the Jrk of the input to the system. The meaning of this variable depends on the “Input mode” setting. In serial input mode, the input is equal to the target, which can be set to any value from 0 to 4095 over serial, USB, and I²C. In analog input mode, the input is a measurement the voltage on the SDA pin, where 0 is 0 V and 4092 is a voltage equal the Jrk’s 5V pin (approximately 4.8 V). In RC input mode, the input is the duration of the last pulse measured, in units of 2/3 us.

Target

Offset	0x02
Type	unsigned 16-bit
Range	0 to 4095

The target variable represents the speed or position that you are commanding the Jrk to maintain.

In serial input mode, the target is set directly with serial, USB, or I²C commands.

In the other input modes, the target is computed by scaling the Input variable using the configurable input scaling settings (see Section 7.3).

If feedback is enabled, the Jrk tries to drive the motor to make the Scaled feedback variable equal to the target (see Section 7.5).

If the feedback mode is “None” (open-loop speed control mode), the target directly determines the Duty cycle target variable that tells the Jrk how much voltage to apply to the motor (see Section 5.1).

Feedback

Offset	0x04
Type	unsigned 16-bit
Range	0 to 4095
Units	Depends on the feedback mode

The feedback variable is a raw, unscaled feedback value representing a measurement taken by the Jrk of the output of the system. In analog mode, the feedback is a measurement of the voltage on the FBA pin, where 0 is 0 V and 4092 is a voltage equal to the Jrk’s 5V pin (approximately 4.8 V). In frequency feedback mode, the feedback is 2048 plus or minus a measurement of the frequency of pulses on the FBT pin. See Section 7.4 for more information about analog and frequency feedback. If the feedback mode is “None” (open-loop speed control mode), the feedback is always zero.

Scaled feedback

Offset	0x06
Type	unsigned 16-bit
Range	0 to 4095

If feedback is enabled, the scaled feedback is calculated from the Feedback using the Jrk’s configurable feedback scaling settings (see Section 7.4). Generally, when feedback is enabled, the Jrk tries to drive the motor to make the scaled feedback equal to the Target (see Section 7.5).

Integral

Offset	0x08
Type	signed 16-bit
Range	Plus or minus the “Integral limit” setting

In general, every PID period, the error (Scaled feedback minus Target) is added to the integral (also known as error sum). There are several settings to configure the behavior of this variable, and it is used in the PID calculation. See Section 7.5.

Duty cycle target

Offset	0x0A
Type	signed 16-bit
Range	−32,768 to 32,767
Units	−600 is full speed reverse, 600 is full speed forward

In general, this is the duty cycle that the jrk is trying to achieve. A value of −600 or less means full speed reverse, while a value of 600 or more means full speed forward. A value of 0 means stopped (braking or coasting).

When the feedback mode is “None” (open-loop speed control mode), the duty cycle target is normally the target minus 2048. In other feedback modes, the duty cycle target is normally zero minus the sum of the proportional, integral, and derivative terms of the PID algorithm (see Section 7.5). In any mode, the duty cycle target can be overridden with a “Force duty cycle target” command.

If an error is stopping the motor, the duty cycle target variable will not be directly affected, but the duty cycle variable will change/decelerate to zero.

Duty cycle

Offset	0x0C
Type	signed 16-bit
Range	−600 to 600
Units	−600 is full speed reverse, 600 is full speed forward

The duty cycle variable indicates the voltage that the Jrk is currently applying to the motor. A value of −600 means full speed reverse, while a value of 600 means full speed forward. A value of 0 means stopped (braking or coasting). The duty cycle could be different from the Duty cycle target because it normally takes into account the Jrk’s configurable motor limits and errors, and its absolute value cannot exceed 600. The duty cycle can be overridden with a “Force duty cycle” command.

Current (low resolution)

Offset	0x0E
Type	unsigned 8-bit
Units	256 mA

This variable is the upper 8 bits of the higher-resolution current variable described below, and it only exists for compatibility with the original Jrk 12v12 and Jrk 21v3. For new applications, we recommend using the Current variable instead.

PID period exceeded

Offset	bit 0 of byte 0x0F
Type	boolean
Range	0 or 1

This variable is true if the Jrk’s most recent PID cycle took more time than the configured PID period. This indicates that the Jrk does not have time to perform all of its tasks at the desired rate. Most often, this is caused by the configured number of analog samples for input, feedback, or current sensing being too high for the configured PID period.

PID period count

Offset	0x10
Type	unsigned 16-bit

This is the number of PID periods that have elapsed. It resets to 0 after reaching 65535.

Error flags halting

Offset	0x12
Type	unsigned 16-bit

This variable indicates which errors are currently stopping the motor. Each bit in the variable represents a different error. Each bit in this register will only be set to 1 if the corresponding error is enabled. See Section 7.7.

Error flags occurred

Offset	0x14
Type	unsigned 16-bit

This variable indicates which errors have occurred since the last time the variable was cleared, regardless of whether the error is enabled or not. Each bit in the variable represents a different error. See Section 7.7.

Force mode

Offset	bits 0 and 1 of byte 0x16
Data	0: None 1: Duty cycle target 2: Duty cycle

This variable indicates whether the Jrk is currently obeying a “Force duty cycle” or “Force duty cycle target” command. A value of 0 indicates normal operation, a value of 1 means the duty cycle target is being forced, and a value of 2 means the duty cycle is being forced.

VIN voltage

Offset	0x17
Type	unsigned 16-bit
Units	mV

This is the measurement of the voltage supplied to the Jrk’s VIN pin, in millivolts.

Current

Offset	0x19
Type	unsigned 16-bit
Units	mA

This is the Jrk’s measurement of the current running through the motor, in milliamps. See Section 7.6 for more details about current measurement.

Last reset

Offset	0x1F
Type	unsigned 8-bit
Data	0: Power up 1: Brown-out reset 2: Reset line (RST) pulled low by external source 4: Watchdog timer reset (should never happen) 8: Software reset (by firmware upgrade process) 16: Stack overflow (should never happen) 32: Stack underflow (should never happen)

This is the cause of the Jrk’s last full microcontroller reset.

Up time

Offset	0x20
Type	unsigned 32-bit
Range	0 to 4,294,967,295
Units	ms

This is the time since the last full reset of the Jrk’s microcontroller, in milliseconds. It resets to 0 after reaching 4,294,967,295.

RC pulse width

Offset	0x24
Type	unsigned 16-bit
Range	2400 (200 µs) to 32400 (2700 µs) or 0
Units	1/12 µs

This is the raw RC pulse width measured on the Jrk’s RC input, in units of twelfths of a microsecond. A value of 0 means the RC input is missing or invalid. The jrk always measures this input, even if the RC signal is not being used to control the motor.

FBT reading

Offset	0x26
Type	unsigned 16-bit
Units	Depends on the FBT settings

This is the raw pulse rate or pulse width measured on the Jrk’s FBT (tachometer feedback) pin. The Jrk always measures this input, even if the FBT reading is not being used for feedback.

In pulse counting mode, this will be the number of pulses on the FBT pin seen in the last N PID periods, where N is the “Pulse samples” setting.

In pulse timing mode, this will be a measurement of the width of pulses on the FBT pin. This measurement is affected by several configurable settings.

Analog reading SDA/AN

Offset	0x28
Type	unsigned 16-bit
Range	0 to 65,472 or 65,535
Units	0 means 0 V, 65,472 means roughly the voltage on the Jrk’s 5V pin

This is the analog reading on the SDA/AN pin. The Jrk updates this reading once per PID period if the “Input mode” setting is “Analog voltage” or the “Always configure SDA/AN for analog input” setting is enabled. Otherwise, the value of this variable will be 65,535 (0xFFFF), indicating that the input is not enabled.

Analog reading FBA

Offset	0x2A
Type	unsigned 16-bit
Range	0 to 65,472 or 65,535
Units	0 means 0 V, 65,472 means roughly the voltage on the Jrk’s 5V pin

This is the analog reading on the FBA pin. The Jrk updates this reading once per PID period if the “Feedback mode” setting is “Analog voltage” or the “Always configure FBA for analog input” setting is enabled. Otherwise, the value of this variable will be 65,535 (0xFFFF), indicating that the input is not enabled.

Digital readings

Offset	0x2C
Type	unsigned 8-bit
Data	Bit 0: Digital reading for SCL Bit 1: Digital reading for SDA/AN Bit 2: Digital reading for TX Bit 3: Digital reading for RX Bit 4: digital reading for RC Bit 5: Digital reading for AUX Bit 6: Digital reading for FBA Bit 7: Digital reading for FBT

This variable contains digital readings for the Jrk’s control pins. Each pin corresponds to a bit in this variable. The Jrk disables digital readings for pins that are used as analog inputs (except SDA when its internal pull-up is enabled), so the digital readings of those pins will always be zero.

Raw current

Offset	0x2D
Type	unsigned 16-bit
Units	Depends on the hard current limit

This is an analog voltage reading from the Jrk’s internal current sense pin. The units of the reading depend on the Encoded hard current limit. The Jrk Configuration Utility and jrk2cmd convert this reading to millivolts before displaying it.

Hard current limit

Offset	0x2F
Type	unsigned 16-bit

This variable specifies the hardware current limit that the Jrk is currently using.

This variable is not actually a current; it is an encoded value telling the Jrk how to set up its current limiting hardware. It is encoded in the same way as the “Hard current limit forward” and “Hard current limit reverse” settings. This variable is only available on the Jrk G2 18v19, 24v13, 18v27, and 24v21.

Last duty cycle

Offset	0x31
Type	signed 16-bit
Range	−600 to 600
Units	−600 is full speed reverse, 600 is full speed forward

This is the duty cycle from the previous PID period. The Jrk reports this variable because it is used in the calculation of the measured current, and you might want to reproduce that calculation yourself instead of relying on the Jrk’s Current variable. The other Duty cycle variable indicates the final outcome of the Jrk’s feedback and PID algorithms, and it is the duty cycle that the Jrk is going to use for the next period. This variable indicates the duty cycle that the Jrk was using during the previous period, so it is the duty cycle that was being used while the Raw current reading was measured.

Current chopping consecutive count

Offset	0x33
Type	unsigned 8-bit
Range	0 to 255

This is the number of consecutive PID periods during which current chopping due to the hard current limit has been active. When it reaches 255, it stops increasing. This variable is only available on the Jrk G2 18v19, 24v13, 18v27, and 24v21. The Jrk 21v3 cannot sense when current chopping occurs.

Current chopping occurrence count

Offset	0x34
Type	unsigned 8-bit
Range	0 to 255

This is the number of PID periods during which current chopping due to the hard current limit has been active, since the last time the variable was cleared. The PID periods counted here are not necessarily consecutive. This variable is only available on the Jrk G2 18v19, 24v13, 18v27, and 24v21. The Jrk 21v3 cannot sense when current chopping occurs.