4.g. Variable Reading Commands
Compact protocol: read variable command byte
Pololu protocol: 0xAA, device number, read variable command byte with MSB clear
The jrk has several serial commands for reading its variables. Most of the variables are two bytes long. For each of those variables, three variable reading commands are provided:
- Two bytes: These commands will result in a two-byte serial response from the jrk containing both bytes of the variable. All variables are little endian, so the first byte transmitted will be the least-significant byte, and the second byte transmitted will be the most-significant byte. For variables that can have negative values, the two’s complement system is used (a response of 0xFE, 0xFF means -2).
- Low byte: These commands will result in a one-byte serial response from the jrk containing just the least-significant byte of the variable.
- High byte: These commands will result in a one-byte serial response from the jrk containing just the most-significant byte of the variable.
The command bytes are listed in the table below.
|Variable||Range||Read Variable Command Byte|
|Two bytes||Low byte||High byte|
|Input||0 to 4095||0xA1||0x81||0x82|
|Target||0 to 4095||0xA3||0x83||0x84|
|Feedback||0 to 4095||0xA5||0x85||0x86|
|Scaled feedback||0 to 4095||0xA7||0x87||0x88|
|Error sum (integral)||-32,768 to 32,767||0xA9||0x89||0x8A|
|Duty cycle target||-32,768 to 32,767||0xAB||0x8B||0x8C|
|Duty cycle||-600 to 600||0xAD||0x8D||0x8E|
|Current||0 to 255||0x8F|
|PID period count||0 to 65535||0xB1||0x91||0x92|
The meaning of the variables is described below:
- Input: The input is the raw, un-scaled input value, representing a measurement taken by the jrk of the input to the system. In serial input mode, the input is equal to the target, which can be set to any value 0–4095 using serial commands. In analog input mode, the input is a measurement of the voltage on the RX pin, where 0 is 0 V and 4092 is 5 V. In pulse width input mode, the input is the duration of the last pulse measured, in units of 2/3 μs. See Section 3.b for more information.
- Target: In serial input mode, the target is set directly with serial commands. In the other input modes, the target is computed by scaling the input. The scaling can be configured in the “Scaling” box of the Input tab in the configuration utility.
- Feedback: The feedback is the raw, un-scaled feedback value, representing a measurement taken by the jrk of the output of the system. In analog feedback mode, the feedback is a measurement of the voltage on the FB pin, where 0 is 0 V and 4092 is 5 V. In no feedback mode (speed control mode), the feedback is always zero.
- Scaled feedback: The scaled value of feedback. The feedback scaling can be configured in the “Scaling” box of the Feedback tab in the configuration utility.
- Current: The value of this variable is proportional to the current running through the motor: on the jrk 21v3, a value of 1 nominally represents 38 mA of current in the motor, while on the jrk 12v12 a value of 1 nominally represents 149 mA of current in the motor . However, the circuitry on the motor driver chips varies between different units, and they can vary depending on which direction the motor is driving, so these calibration values will not always be right for every jrk. The value of this variable will always be zero unless a current limit is enabled. See Section 3.e for more information about current measurement and calibration.
- Error sum (integral): Every PID period, the error (scaled feedback minus target) is added to the error sum. The error sum gets reset to zero whenever the jrk is not driving the motor, and can optionally be reset whenever the proportional term of the PID calculation exceeds the maximum duty cycle. There is also a configurable integral limit that the integral can not exceed.
- Duty cycle target: Represents 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 braking. In no feedback mode (speed control mode), the duty cycle target is the target minus 2048. In other feedback modes, the duty cycle target is the sum of the proportional, integral, and derivative terms of the PID algorithm.
- Duty cycle: Represents the duty cycle that the jrk is driving the motor with. 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 braking. The absolute value of the duty cycle will always be less than the absolute value of the duty cycle target. The duty cycle is different from the duty cycle target because it takes in to account all of the jrk’s configurable limits: maximum acceleration, maximum duty cycle, maximum current, and also brake duration (Section 3.e).
- PID period count: This is the number of PID periods that have elapsed. It resets to 0 after reaching 65535. The duration of the PID period can be configured (Section 3.d).
Note: All command bytes from 0x81 to 0xBF that are not listed in this section or Section 4.f are undocumented variable reading commands that will result in a serial response from the jrk and not generate a serial protocol error. These commands are not useful, but they are not harmful.