11. Command reference

The Jrk G2 supports several different commands on its serial, I²C, and USB interfaces. This section describes the details of what each command does. The encoding of the commands for the different interfaces is described in later sections (Section 12 for serial, Section 13 for I²C, and Section 14 for USB).

For each command, this section contains several pieces of information:

• The list of Interfaces that support the command. Most of the commands are available on all three interfaces, but some of them are only available over USB.
• The Arguments that the command takes. This is the data you must supply to the Jrk G2 when sending the command.
• The Response is the data that the Jrk will return to you after you send the command.
• The jrk2cmd field shows how to run the command using the Jrk G2 Command-line Utility. Be sure to replace NUM with an actual number and FILE with a filename if you try to run these commands.
• The Arduino library field describes how to send the command using our Jrk G2 Library for Arduino.

List of commands

• Set target
• Stop motor
• Force duty cycle target
• Force duty cycle
• Get variables
• Set RAM settings
• Get RAM settings
• Get EEPROM settings
• Set EEPROM setting (USB only)
• Reinitialize (USB only)
• Start bootloader (USB only)

Set target

Interfaces	Serial, I²C, USB
Arguments	Target: a number between 0 and 4095
Response	None
jrk2cmd	jrk2cmd --target NUM jrk2cmd --run
Arduino library	jrk.setTarget(uint16_t target)

The “Set target” command is the most important command for controlling the Jrk, and in many applications it is the only command needed. The target can represent a target duty cycle, speed, or position depending on the feedback mode.

If the input mode is serial, this command sets the “Input” and “Target” variables equal to specified target value, which should be between 0 and 4095. In any input mode, it clears the “Awaiting command” error flag, clears the serial timeout timer, and terminates the effect of any previous “Force duty cycle” and “Force duty cycle target” commands.

You can send this command using the Jrk G2 Configuration Utility. If the input mode is serial, you can specify the target value to send using scroll bar in the “Status” tab. In any input mode, you can click “Run motor” to clear latched errors and send a “Set target” command.

You can also send this command using the Jrk G2 Command-line Utility, jrk2cmd. The --target NUM option allows you to specify a target. For example, you can run jrk2cmd --target 1234 to send a Set Target command with an argument of 1234. You can run jrk2cmd --run to clear latched errors and send a “Set target” command that sets the target to its current value in order to trigger the side effects of the command that are described above. You can add the -d NUM option to either of the commands above to specify the serial number of the Jrk you want to control, which is required if there are multiple Jrk controllers connected to the computer over USB.

Stop motor

Interfaces	Serial, I²C, USB
Arguments	None
Response	None
jrk2cmd	jrk2cmd --stop NUM
Arduino library	jrk.stopMotor()

The “Stop motor” command, also known as “Motor off”, sets the “Awaiting command” error flag and clears the serial timeout timer. You can use this command to stop the motor in any input mode.

If you have configured a deceleration limit, the Jrk will respect the deceleration limit while decelerating to a duty cycle of 0, unless the “Awaiting command” error has been configured as a hard stop error. Once the duty cycle reaches zero, the Jrk will either brake or coast, depending on its settings.

You can send this command using the Jrk G2 Configuration Utility by pressing the “Stop motor” button. You can send this command using the Jrk G2 Command-line Utility by running jrk2cmd --stop from a command prompt.

Force duty cycle target

Interfaces	Serial, I²C, USB
Arguments	Duty cycle target: a number between −600 and 600
Response	None
jrk2cmd	jrk2cmd --force-duty-cycle-target NUM
Arduino library	jrk.forceDutyCycleTarget()

When the Jrk receives this command, it will start ignoring the results of the usual algorithm for choosing the duty cycle target, and instead set it to be equal to the target specified by this command. This command clears the “Awaiting command” error flag and clears the serial timeout timer. While this command is in effect, the Jrk will set its “Integral” variable to 0.

This command is useful if the Jrk is configured to use feedback and PID but you want to take control of the motor for some time, while still respecting errors and motor limits as usual. It could also be useful to temporarily take control of a Jrk that is normally controlled via an analog or RC input.

To get out of this mode, send a Set target, Force duty cycle, Stop motor, or Reinitialize command.

Force duty cycle

Interfaces	Serial, I²C, USB
Arguments	Duty cycle: a number between −600 and 600
Response	None
jrk2cmd	jrk2cmd --force-duty-cycle NUM
Arduino library	jrk.forceDutyCycle()

When the Jrk receives this command, it will start ignoring the results of the usual algorithm for choosing the duty cycle, and instead set it to be equal to the value specified by this command, ignoring all motor limits except the maximum duty cycle parameters, and ignoring the “Input invalid”, “Input disconnect”, and “Feedback disconnect” errors. This command will have an immediate effect, regardless of the PID period. This command clears the “Awaiting command” error flag and clears the serial timeout timer. The Jrk will set its “Integral” variable to 0 while in this mode.

This is useful if the Jrk is configured to use feedback and PID but you want to take control of the motor for some time, without respecting most motor limits. It could also be useful to temporarily take control of a Jrk that is normally controlled via an analog or RC input.

To get out of this mode, send a Set target, Force duty cycle target, Stop motor, or Reinitialize command.

Get variables

Interfaces	Serial, I²C, USB
Arguments	Offset: The address of the first variable to fetch. Length: The number of bytes to fetch. Clear error flags halting: true or false Clear error flags occurred: true or false Clear current chopping occurrence count: true or false
Response	The requested bytes.
jrk2cmd	jrk2cmd --status jrk2cmd --status --full (or use -s instead of --status)
Arduino library	jrk.getVariables(uint8_t offset, uint8_t length, uint8_t * buffer) jrk.get___() functions

This command fetches a range of bytes from the Jrk’s variables, which are stored in the Jrk’s RAM and represent the current state of the Jrk. The offset argument specifies the location of the first byte you want to fetch: an offset of zero indicates the first variable (the “Input” variable). The length argument specifies how many bytes to read. Each variable, along with its offset and size, is documented in Section 10.

For example, if you want to read the 16-bit VIN voltage variable, you can specify an offset of 23 (0x17 when written in hexadecimal) and a length of 2. The Jrk will return the two bytes of that variable. If you want to read the feedback and scaled feedback variables together, you can specify an offset of 4 and a length of 4, since the offset of the feedback variable is 4 and the scaled feedback variable it stored immediately after it at offset 6.

It is OK to read past the last variable. The Jrk will return zeroes when you try to read from any unimplemented areas of the variable space.

When reading multiple variables, the Jrk will give you a consistent snapshot of the state of those variables as they were at the end of the previous PID period. The snapshot is taken right after the Jrk has finished calculating a new duty cycle and stored it in the “Duty cycle” variable. When the Jrk receives a “Get variables” command, it copies the requested data into a dedicated buffer, so the variables in the response to that command will be consistent with each other.

This command has several optional side effects:

• If the clear error flags halting argument is true, the Jrk will clear latched errors in its “Error flags halting” variable, except for the “Awaiting command” error flag. It will also clear the serial timeout timer.
• If the clear error flags occurred argument is true, the Jrk will clear errors in its “Error flags occurred” variable.
• If the clear current chopping occurrence count argument is true, the Jrk will clear its “Current chopping occurrence count” variable (i.e. reset it to zero).

These side effects take place after the variable data has been copied into a dedicated buffer to be sent as a response to the command. This means that you can reliably detect errors and current chopping even if you are constantly clearing the corresponding variables, as long as you read from those variables at the same time as clearing them.

The Jrk G2 Configuration Utility reads the Jrk’s variables over USB many times per second, and displays many of them in the “Status” tab. It sets the “Clear error flags occurred” and “Clear current chopping occurrence count” flags to true so it can get rough counts of how many times an error has occurred, or how many times current chopping has occurred. This means that you might have trouble detecting that those errors happened if you are trying to read them while the configuration utility is running.

The “Clear errors” button in the “Errors” tab of the Jrk G2 Configuration Utility sends this command with the “Clear error flags halting” parameter set to true.

The Jrk’s USB interface provides a flexible version of the “Get variables” command that lets you specify an offset, length, and any combination of side effects. The serial and I²C commands are less flexible: the length is limited to be at most 15 bytes, and the side effects can only be triggered using special variants of the “Get variables” command that retrieve the variable being cleared. For more details, see the command encoding specifications in the following sections.

Set RAM settings

Interfaces	Serial, I²C, USB
Arguments	Offset: The address of the first setting to write to. Length: The number of bytes to write. Data: The bytes to write.
Response	None
jrk2cmd	jrk2cmd --ram-settings FILE Run jrk2cmd --help and look at the other “RAM (volatile) settings” options.
Arduino library	jrk.setRAMSettings(uint8_t offset, uint8_t length, uint8_t * buffer) jrk.set___() functions documented in the “RAM settings commands” section of the library documentation

This command temporarily overrides the selected settings by writing to the copy of the settings that the Jrk stores in RAM. Each setting is documented in Section 9, along with its offset and size and whether it can be temporarily overridden.

For example, if you want to temporarily override the proportional PID coefficient, you could send a “Set RAM settings” command with an offset of 0x51 and a length of 2. The offset of the “Proportional multiplier” setting is 0x51 and it occupies 2 bytes. You could change the length to 3 if you want to also override the “Proportional exponent” setting, which is one byte long and lives at offset 0x53.

The Jrk firmware does not validate or fix any of the settings that you provide with this command. If you choose invalid settings then you might get some unexpected behavior. The usual way to change the Jrk’s settings is to use the Jrk G2 Configuration Utility or Jrk G2 Command-line Utility, which validate the settings and fix any errors before writing them to the Jrk’s EEPROM memory.

It is OK to write past the end of the last setting. The Jrk will ignore these writes, and always report zero when you try to read from unimplemented areas of the settings space with the Get RAM settings command.

The effect of this command is temporary. The Jrk reloads all of its settings from EEPROM whenever there is a full microcontroller reset and whenever it receives a Reinitialize command.

The Jrk G2 Command-line Utility has a --ram-settings option that you can use to override all of the Jrk’s RAM settings. It requires a settings file, which you can obtain with jrk2cmd --get-settings FILE, jrk2cmd --get-ram-settings FILE, or from the “File” menu of the Jrk G2 Configuration Utility. It also supports a variety of more streamlined options that just override a small number of settings instead of overriding all of them.

The Jrk G2 Configuration Utility does not support this command.

Get RAM settings

Interfaces	Serial, I²C, USB
Arguments	Offset: The address of the first setting to read. Length: The number of bytes to read.
Response	The requested bytes.
jrk2cmd	jrk2cmd --get-ram-settings FILE
Arduino library	jrk.getRAMSettings(uint8_t offset, uint8_t length, uint8_t * buffer) jrk.get___() functions documented in the “RAM settings commands” section of the library documentation

This command reads from the copy of the settings that the Jrk stores in RAM. You can use this to retrieve the current values of these settings, in case any of them have been temporarily overridden with the Set RAM settings command.

It is OK to read past the end of the last setting. The Jrk will always return zeros when you try to read from unimplemented areas of the settings space.

Get EEPROM settings

Interfaces	Serial, I²C, USB
Arguments	Offset: The address of the first setting to read. Length: The number of bytes to read.
Response	The requested bytes.
jrk2cmd	jrk2cmd --get-settings FILE
Arduino library	jrk.getEEPROMSettings(uint8_t offset, uint8_t length, uint8_t * buffer)

This command reads the specified bytes from the Jrk’s EEPROM memory, where the non-volatile copy of its settings are stored. Each setting is documented in Section 9, along with its offset and size.

Set EEPROM setting (USB only)

Interfaces	USB only
Arguments	Offset: The address of the byte to write to. Value: The new value of the byte, from 0 to 255.
Response	None
jrk2cmd	jrk2cmd --settings FILE

This command modifies the specified byte in the Jrk’s EEPROM. Each setting is documented in Section 9, along with its offset and size.

The Jrk G2 Configuration Utility uses this command many times whenever you click “Apply settings”. The Jrk G2 Command-line Utility uses this command to apply a settings file specified with the --settings option. In both cases, the software also sends a Reinitialize command to make the new settings take effect.

The Jrk’s EEPROM is only rated 100,000 erase/write cycles, so be careful about using this command in a loop.

Reinitialize (USB only)

Interfaces	USB only
Arguments	Preserve errors: true or false
Response	None
jrk2cmd	jrk2cmd --reinitialize

This command tells the Jrk to reload all of its settings from non-volatile memory (discarding changes made by previous Set RAM settings commands), make the settings take effect, and terminate the effect of any previous “Force duty cycle” and “Force duty cycle target” commands.

If the Preserve errors argument is true, this command will clear all of the error bits in “Error flags halting” for errors that are not enabled in the new settings. If the input mode is changing from some other input mode to “Serial / I²C / USB”, the Jrk will set the “Awaiting command” error, so that the Jrk does not drive the motor before it gets a valid command. The Jrk G2 software sets the “Preserve errors” flag to true whenever it applies settings.

If the Preserve errors argument is false, this command will behave as it did on the original Jrk controllers. It will clear all of the bits in “Error flags halting”, but if the input mode is serial then it will immediately set the “Awaiting command” error bit, meaning that you will have to send a command to get the Jrk moving again.

Start bootloader (USB only)

Interfaces	USB only
Arguments	None
Response	None

This command causes the Jrk to go into bootloader in preparation for receiving a firmware upgrade over USB. It will briefly disconnect from USB and reappear as a new USB device.