8. Variable reference

This variable holds bits specifying which features of the Motoron’s command protocol are enabled. A bit value of 1 indicates that the corresponding feature is enabled. For more information about these features, see the documentation of the “Set protocol options” command in Section 9.

There are several status flags that are latched, meaning that after they get set to 1, they stay set until they are cleared by a “Clear latched status flags” command. Most of these flags are also cleared by the Reinitialize command.

• The Protocol error flag indicates that the Motoron received an invalid byte in a command other than the CRC byte, as documented in Section 9.
• The CRC error flag indicates that CRC for commands was enabled and the Motoron received an incorrect CRC byte at the end of a command.
• The Command timeout latched flag indicates that the Motoron’s command timeout feature was activated because too much time has passed since it received a valid command. See the description of the Command timeout variable below for more information about this feature. This flag is the latched version of the “Command timeout” flag documented below.
• The Motor fault latched flag indicates that one or more of the motors experienced an error. This flag gets set to 1 whenever the “Motor faulting” flag below is 1, so see the documentation of that flag for more details.
• The No power latched flag indicates that the VIN voltage fell to a level that was definitely too low to run motors. This flag gets set to 1 whenever the “No power” flag documented below is 1, so see the documentation of that flag for more details.
• The UART error flag indicates that there was a problem preventing the Motoron from receiving serial data properly on its RX line, and some data could have been lost or corrupted. If this bit is set, you can read the UART faults variable to get more information about what specific error is happening. This bit is only implemented on Motorons with a UART serial interface.
• The Reset flag gets set to 1 when the Motoron powers on, or its processor is reset, or it receives a Reinitialize command.

There are several non-latched status flags which cannot be directly set or cleared.

• The Command timeout flag indicates that the Motoron’s command timeout feature is active because too much time has passed since it received a valid command. Every valid command clears this bit. See the description of the Command timeout variable below for more information about this feature.
• The Motor faulting flag is 1 if one or more of the motors is experiencing an error. This means that something is going wrong with the motor, and the outputs for it will be disabled until the problem is resolved. Due to hardware limitations, there is no way to tell which motor is experiencing the fault.
  • For the Motoron M1T550, M1U550, M2T550, M2U550, M3S550, and M3H550, this flag is always 0. Under-voltage, over-current, and over-temperature faults will shut down the motor but they can not be detected using this bit.
  • For the Motoron M1T256, M1U256, M2T256, M2U256, M3S256, and M3H256, a fault occurs if the VIN power drops below about 4.4 V and remains above about 3.4 V. A fault occurs if a motor current over 8 A or a temperature over 165 °C is measured. The over-current and over-temperature faults are latched, so the motor will not recover from those errors until you use the “Clear motor fault” command, command the motors to coast, or disconnect motor power. There are other hardware conditions that can cause temporary faults.
  • For the Motoron M2S and M2H controllers, a fault occurs if the VIN power drops below about 5.4 V and remains above about 3 V. Faults can also occur in response to various other internal conditions, but there is no over-temperature shutoff. None of the faults are latched, so they will end when the condition causing them goes away.
• The No power flag is 1 if the VIN voltage measurement indicates that the controller’s VIN voltage is definitely too low to run the motors. If this flag is 0, the VIN voltage might be sufficient.
  • For the Motoron M1T550, M1U550, M2T550, M2U550, M3S550, and M3H550, this flag is 1 if and only if the VIN voltage measurement is less than 19. This corresponds to a VIN of 0.9 V if the Motoron’s logic voltage is 5 V, and 0.6 V if the Motoron’s logic voltage is 3.3 V.
  • For the Motoron M1T256, M1U256, M2T256, M2U256, M3S256 and M3H256, this flag is 1 if and only if the VIN voltage measurement is less than 27. This corresponds to a VIN of 2.9 V if the Motoron’s logic voltage is 5 V, and 1.9 V if the logic voltage is 3.3 V.
  • For the Motoron M2S and M2H controllers, this flag is 1 if and only if the VIN voltage is less than 37. This corresponds to a VIN of 4.0 V if the Motoron’s logic voltage is 5 V and 2.6 V if the logic voltage is 3.3 V.
• The Error active flag is 1 if there is a firmware-level error that is causing the Motoron to stop its motors. By default, the only two errors are the “Reset” flag and the “Command timeout” flags (documented above), but you can change which flags are considered to be errors by changing the Error mask variable documented below.
• The Motor output enabled flag is 1 if the Motoron is currently trying to enable any of its motor outputs. If this is 0, all of the motor outputs are disabled, meaning that the motors are coasting. If this is 1, some of the outputs might be enabled, but others might be disabled if there is inadequate VIN power or a motor fault is happening.
• The Motor driving flag is 1 if the Motoron is currently trying to drive any of its motors at a non-zero speed. This bit can only be 1 if the “Motor output enabled” flag is also 1.

This two-byte variable holds a measurement of the voltage on the Motoron’s VIN pin. It is a 10-bit ADC reading of the VIN voltage divided by 1047/47, with the Motoron’s logic voltage used as the reference voltage.

For the M1T256, M1U256, M2T256, M2U256, M3S256, M3H256, M2S, and M2H motors, the following C/C++ code shows how to take the raw value of this variable, along with the reference voltage in millivolts (typically 3300 or 5000), and compute the VIN voltage in millivolts:

uint32_t vinVoltageMv = (uint32_t)vinVoltage * referenceMv / 1024 * 1047 / 47;

For the M1T550, M1U550, M2T550, M2U550, M3S550, and M3H550, the C/C++ code would be:

uint32_t vinVoltageMv = (uint32_t)vinVoltage * referenceMv / 1024 * 459 / 47;

The command timeout feature helps ensure that your motors will stop running if the device controlling the Motoron malfunctions, powers off, or gets disconnected.

The Motoron keeps track of how many milliseconds have passed since it received a valid command documented in Section 9 that did not trigger a CRC error or a protocol error. If that time is greater than or equal to the time specified by the “Command timeout” variable, and the “Command timeout” variable is non-zero, then the Motoron will set two flags in the Status flags variable: “Command timeout” and “Command timeout latched”. When a valid command is received, the “Command timeout” flag gets cleared, and the “Command timeout latched” flag can be cleared with the “Clear latched status flags” command.

By default the non-latched command timeout flag is configured to be treated as an error, so when it is set, the each motor will decelerate to a stop and then coast.

This variable uses units of four milliseconds. For example, a value of 100 means the timeout will be 400 ms. However, if you set the variable using the setCommandTimeoutMilliseconds function in our Arduino library, you should specify the timeout in milliseconds and the Arduino library will take care of converting that value to correct units.

If you want to disable the command timeout feature, you can use the “Set variable” command to clear the command timeout bit in the “Error mask” variable.

This variable defines how the Motoron will stop its motors when an error is happening. (The conditions that count as errors are defined by the Error mask variable.)

• Coast means that the Motoron will make all of its motors coast while obeying deceleration limits. This is equivalent to sending a “Set braking” command with a brake amount of 0 to each motor. If no deceleration limits are set, this is also equivalent to the “Coast now” error response.
• Brake means that the Motoron will make all of its motors brake while obeying deceleration limits. This is equivalent to sending a “Set braking” command with a brake amount of 800 to each motor. If no deceleration limits are set, this is also equivalent to the “Brake now” error response.
• Coast now means that the Motoron will make all of its motors coast immediately without obeying deceleration limits. This is equivalent to sending the “Coast now” command, and it is also equivalent to sending a “Set braking now” command with a brake amount of 0 to each motor.
• Brake now means that the Motoron will make all of its motors brake immediately without obeying deceleration limits. This is equivalent to sending a “Set braking now” command with a brake amount of 800 to each motor.

This variable defines which status flags are considered to be errors. Each bit in this variable corresponds to the bit in the “Status flags” register in the same position. For example, bit 9 in this register corresponds to bit 9 in the “Status flags” register, which is the “Reset” bit.

The only flags that can be considered errors are the latching status flags (the flags that must be explicitly cleared before they will change to 0) and the “Command timeout” flag. If you try to set any other bits in the error mask to 1, those bits will be changed to 0.

This variable indicates whether there is currently a jumper installed from the JMP1 pin to GND. This is determined with a digital reading on the JMP1 pin.

Bit 1 is always the logical inverse of bit 0, but if you read this variable and see that both bits are zero, it could mean that there are multiple Motorons using the same address, and they have different jumper states, and both of them are responding to your controller when you attempt to read this variable.

This variable can be useful as part of a procedure for verifying that every Motoron in your system has the correct address.

Every time the Motoron sets the UART error bit in the Status flags variable, it also sets one of the bits in this variable to indicate the specific error that occurred. This variable is only implemented on Motorons with a UART serial interface.

• The framing and noise bits are errors detected by the Motoron’s UART which indicate that the serial signal on the RX pin did not match the expected format.
• The software overrun error indicates that a byte was received but there was no space in the Motoron’s buffers to store it. This should not happen if you are using a baud rate of 115200 or less, and are delaying for an appropriate amount of time after sending certain special commands like “Write EEPROM” that take a long time to execute.
• The hardware overrun error indicates that a byte was received but there was no space in the Motoron’s UART to store it. This should not happen.

You can use the “Set variable” command to clear bits in this variable, however, that command can only clear bits: it does not change any bits from a 0 to 1.

The lower 4 bits of this byte specify the PWM frequency to use for this motor.

You can set this variable with a “Set variable” command, which takes a 14-bit argument. The upper 6 bits are ignored, while the lower 8 bits get copied to this variable.

Due to hardware limitations on the M2T550, M2U550, M2T256, M2U256, M2S, and M2H, both motors must have the same PWM frequency, so setting the PWM mode of one of motor also sets the PWM mode of the other.

Due to hardware limitations on the M3S256 and M3H256, motors 2 and 3 must have the same PWM frequency, so setting the PWM mode of one of these motors also sets the PWM mode of the other.

This is the speed at which the motor has been commanded to move. The “Current speed” (documented below) will move towards this over time, limited by the acceleration and deceleration limits (if enabled).

This is the desired amount of braking to apply to the motors when the current speed is 0. A value of 0 corresponds to full coasting, while a value of 800 corresponds to full braking.

Due to hardware limitations, this amount of braking might not necessarily be applied when the current speed of the motor reaches zero.

All current Motorons are only capable of full coasting and full braking, and they can only use coasting if they coast all the motors at once. Therefore, if the current speed of any of the motors is non-zero, or any of the motors has a non-zero target brake amount, the Motoron will not use coasting, and will instead use full braking for any motor whose current speed is zero. Also, the motor outputs might be inoperative due to inadequate VIN power or a motor fault, even if the Motoron is trying to apply full braking.

This is the speed that the Motoron is currently trying to apply to the motor.

• A value of 0 means the motor is braking (both outputs driving low), coasting (both outputs disabled), or something in between, as determined by the target brake amount variable and the hardware limitations of the controller.
• A value of 800 corresponds to the MxA output driving high (VIN) and the MxB output driving low (GND). This direction is called forward, and causes the green motor indicator LED to turn on.
• A value of −800 corresponds to the MxA output driving low (0 V) and the MxB output driving high (VIN). This direction is called reverse, and causes the red motor indicator LED to turn on.
• Intermediate values correspond to rapidly switching the motor outputs between braking and driving the motor in the specified direction.

Note: The “Current speed” variable only says the speed value that the Motoron is trying to apply to the motor. It is not based on any kind of sensor measurement. Also, the motor outputs might be inoperative due to inadequate VIN power or a motor fault even if the “Current speed” is non-zero,

This is a speed that can be set ahead of time with the “Set speed” or “Set all speeds” commands. When you are ready to use the buffered speeds, you can use the “Set all speeds using buffers” command to make it actually take effect.

If you are using multiple Motoron controllers and want to change all of the motor speeds (nearly) instantaneously, the buffered speed feature can help you achieve that.

This variable specifies how quickly the motor’s current speed is allowed to increase when it is greater than or equal to 0. A value of 0 (the default) disables this acceleration limit, so the current speed can increase by any amount in a fraction of a millisecond. A non-zero value means that once every 10 ms, the current speed can increase by the specified value divided by 8. The Motoron keeps track of any fractional parts of the speed internally. Another way to think about this variable is that it is how much the current speed can change in 80 ms.

For example, if you set the max acceleration forward to 124, then the current speed can only increase by 15.5 speed units every 10 ms, or 124 speed units every 80 ms. This means it would take 520 ms (0.52 s) to accelerate from 0 (stopped) to 800 (full speed forward).

Note: Even if you set a maximum acceleration limit, the motor could experience abrupt acceleration if the current speed of the motor is non-zero while motor power is getting connected to the Motoron. To avoid this, you might want to set the “No power latched” bit in the Error mask.

This is like Max acceleration forward, but for the reverse direction.

This variable specifies how quickly the motor’s current speed is allowed to decrease when it is greater than 0. A value of 0 (the default) disables this deceleration limit, so the current speed can decrease all the way to 0 in a fraction of millisecond. A non-zero value means that once every 10 ms, the current speed can decrease by the specified value divided by 8.

This is like Max deceleration forward, but for the reverse direction.

The Motoron allows the speed of the motor to accelerate instantly from 0 to the value of this variable, ignoring the max acceleration forward. This can be useful if you want your motor to accelerate faster by not spending any time accelerating through speeds that are too low to actually move the motor. This variable does not affect deceleration.

This is like Starting speed forward, but for the reverse direction. The Motoron allows the speed of the motor to accelerate instantly from 0 to the negated value of this variable, ignoring the max acceleration reverse.

This variable specifies how long the Motoron should wait with the motor at speed 0 while switching directions from forward to reverse. For example, if the motor is currently driving in reverse (current speed less than 0), and the target speed is in the forward direction (positive), then the Motoron will decelerate the speed to 0, wait for an amount of time equal to the direction change delay forward, and then it will start accelerating in the forward direction (current speed greater than 0).

This is like Direction change delay forward but for the reverse direction.

This variable is only supported on the Motoron M2S and M2H controllers.

This variable sets the hardware current limiting threshold for the specified motor. When the motor’s current exceeds the specified level, the Motoron will automatically reduce the motor current by turning the motor outputs off for a small fraction of a millisecond.

The units of this variable depend on the model of Motoron you have and the logic voltage of your system. There is also an offset that is different for each motor channel.

To calculate the value to use for the current limit, you can use the calculateCurrentLimit function in the Arduino library or follow these steps:

1. Measure the Current sense offset for this motor as described in the documentation for that variable. Multiply this offset by 125 and divide it by 128 (this is only a slight reduction).
2. Express the desired current limit as a number of milliamps. Multiply that number by 20 and then divide it by the logic voltage of your system in millivolts. If you are using the M2S18v20 or M2H18v20, further divide this number by 2.
3. Add together the offset calculated in step 1 and the scaled current limit calculated in step 2. This is the value to write to the current limit variable.

This variable is only supported on the Motoron M2S and M2H controllers.

This is a 10-bit analog reading of the current sense signal for the specified motor. This reading is updated multiple times per millisecond.

This reading is the sum of two components:

1. A motor-specific offset that is typically 50 mV but varies widely from unit to unit.
2. The average current flowing into the Motoron’s motor outputs and going to GND, multiplied by 10 mV/A for the M2S18v20 and M2H18v20, and 20 mV/A for the other Motoron M2S and M2H controllers.

This reading (including the offset) goes to zero if the motor power supply voltage is not high enough or the motors are coasting or there is some fault preventing the motors from running.

This reading does not measure the current that recirculates through a motor while both of the motor outputs are low, because during that time, the current goes into one motor output and out of the other, without going to GND.

This variable is only supported on the Motoron M2S and M2H controllers.

This is the value that the Current speed variable held the last time the current sense measurements for this motor were updated.

This variable is almost always equal to the current speed, but after the current speed is updated, it will take a fraction of a millisecond before this variable gets updated to be the same.

It can be useful to use a single “Get variables” command to read this variable at the same time as the “Current sense raw” variable (offset 28) or the “Current sense processed” variable (offset 32). There is no point in reading this variable by itself because you can just read the current speed instead.

This variable is only supported on the Motoron M2S and M2H controllers.

This processed current reading is proportional to the average current through the motor, assuming that the Current sense offset variable has been measured and set appropriately and the average current flowing through the motor during the off time of the PWM cycle (when both motor outputs are driving low) is equal to the average current flowing through the motor during the on time of the PWM cycle.

The units of this reading depend on the logic voltage of your system and the specific Motoron you have. To convert this reading to milliamps, multiply it by the logic voltage of your system in millivolts, then multiply by 2 if you are using the M2S18v20 or M2H18v20, then multiply by 25, and finally divide by 512. Alternatively, you can multiply by the units specified in the table below:

Essentially, the Motoron calculates this variable by taking the Current sense raw minus the Current sense offset, multiplying by 800, and then dividing by the absolute value of the Current sense speed or the Current sense minimum divisor, whichever is larger. The actual computation is more complicated than this because it detects underflows and overflows, avoids dividing by zero, and uses 16-bit division.

Note that this reading will be 65535 (0xFFFF) if an overflow happens during the calculation due to very high current.

This variable is only supported on the Motoron M2S and M2H controllers.

This is one of the settings that determines how the current sense readings are processed. The offset is supposed to be the value of the Current sense raw variable when motor power is supplied to the Motoron and it is driving is motor outputs at speed 0. The Motoron does not perform this measurement automatically; it is up to the user to measure the offset and write it into this variable.

Setting the offset makes the processed current sense readings much more accurate, especially at low speeds. The offset is also useful for calculating appropriate current limit values.

The I2CCurrentSenseCalibrate example that comes with the Arduino library shows how to measure the current sense offsets and load them onto the Motoron

This variable is only supported on the Motoron M2S and M2H controllers.

This is one of the settings that determines how current sense readings are processed. It specifies the minimum value to use when dividing by the speed (see Current sense processed). Using a non-zero value for this variable helps to avoid getting extremely high, unrealistic processed current sense readings at low speeds.