8. Variable reference

The Motoron maintains a set of variables in RAM that contain information about its inputs, outputs, and status. The Motoron’s “Get variable” command allows you to read the variables, and there are other commands that allow you to set or modify the variables.

The variables are divided into two categories:

  • General variables apply to all the motors, or the controller as a whole. The Motoron just stores one copy of each general variable.
  • Motor-specific variables can be different for each motor. The Motoron stores a separate copy of the variable for each motor, and you must provide a motor number when accessing the variable.

This section lists all of the variables that the Motoron supports. In addition to the category, this section contains several pieces of information for each variable, if applicable:

  • The Offset of each variable is its location among the variables in the same category. The offset is measured in bytes.
  • The Type specifies how many bits the variable occupies, and says whether it is signed or unsigned.
  • The Range specifies what values the variable can have.
  • The Default specifies the value that the variable has when the controller starts up, before it has been modified.
  • The Units specify the relationship between values of the variable and real-world quantities.
  • The Data indicates how to interpret different possible values of the variable.
  • The Command is the name of a command that can be used to set the variable.
  • The Arduino library field shows the methods in the Arduino library that can be used to access the variable.

The term “bit 0” refers to the least significant bit of a variable (the bit that contributes a value of 1 to the variable when it is set). Accordingly, the other bits of a variable are numbered in order from least significant to most significant. All variables use little-endian byte ordering, meaning that the least-significant byte comes first.

List of variables

Protocol options

Category general
Offset 0
Type unsigned 8-bit
Data
  • Bit 0: CRC for commands
  • Bit 1: CRC for responses
  • Bit 2: I²C general call
Default 7 (all options enabled)
Command Set protocol options
Arduino library void setProtocolOptions(uint8_t options)
void enableCrc()
void disableCrc()
void enableCrcForCommands()
void disableCrcForCommands()
void enableCrcForResponses()
void disableCrcForResponses()
void enabeI2cGeneralCall()
void disableI2cGeneralCall()

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.

Status flags

Category general
Offset 1
Type unsigned 16-bit
Default 0x2200 (Reset, Error active)
Data
  • Bit 0: Protocol error
  • Bit 1: CRC error
  • Bit 2: Command timeout latched
  • Bit 3: Motor fault latched
  • Bit 4: No power latched
  • Bit 9: Reset
  • Bit 10: Command timeout
  • Bit 11: Motor faulting
  • Bit 12: No power
  • Bit 13: Error active
  • Bit 14: Motor output enabled
  • Bit 15: Motor driving
Command Clear latched status flags
Set latched status flags
Arduino library uint16_t getStatusFlags()
bool getProtocolErrorFlag()
bool getCrcErrorFlag()
bool getCommandTimeoutLatchedFlag()
bool getMotorFaultLatchedFlag()
bool getNoPowerLatchedFlag()
bool getResetFlag()
bool getMotorFaultingFlag()
bool getNoPowerFlag()
bool getErrorActiveFlag()
bool getMotorOutputEnabledFlag()
bool getMotorDrivingFlag()
void clearLatchedStatusFlags(uint16_t flags)
void clearResetFlag()
void setLatchedStatusFlags(uint16_t flags)

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 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 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.
  • 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 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 IOREF is 5 V, and 1.9 V if IOREF 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.

VIN voltage

Category general
Offset 3
Type unsigned 16-bit
Range 0 to 1023
Units IOREF × 0.02175
Arduino library void getVinVoltage()
void getVinVoltageMv(uint16_t referenceMv)

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 GND and IOREF used as the reference voltages.

If you are using our Arduino library, you can use the getVinVoltageMv() function to read this variable and convert it to millivolts.

The following C/C++ code shows how to take the raw value of this variable, along with the reference voltage (IOREF) in millivolts, and compute the VIN voltage in millivolts:

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

If you are using a 5 V Arduino, you can simply set referenceMv to 5000 in the code above. If you are using a 3.3 V Arduino, you can simply set referenceMv to 3300 in the code above.

Command timeout

Category general
Offset 5
Type unsigned 16-bit
Range 0 to 16250 (65 seconds)
Default 375 (1.5 seconds)
Units 4 ms
Command Set variable
Arduino library void setCommandTimeoutMilliseconds(uint16_t ms)
void getCommandTimeoutMilliseconds()

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.

Error response

Category general
Offset 7
Type unsigned 8-bit
Default 0 (Coast)
Data
  • 0: Coast
  • 1: Brake
  • 2: Coast now
  • 3: Brake now
Command Set variable
Arduino library void setErrorResponse(uint8_t response)
void getErrorResponse()

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.

Error mask

Category general
Offset 8
Range 0 to 0x7FF
Type unsigned 16-bit
Default 0x600 (Command timeout and Reset)
Command Set variable
Arduino library void setErrorMask()
void disableCommandTimeout()
void getErrorMask()

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.

Jumper state

Category general
Offset 10
Type unsigned 8-bit
Data
  • Bit 0: JMP1 to GND jumper installed
  • Bit 1: JMP1 to GND jumper not installed
Bits 2 to 7 are reserved and should each have a value of 1.
Arduino library void getJumperState()

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.

PWM mode

Category motor-specific
Offset 1
Type unsigned 8-bit
Data Bits 0 to 3 specify the PWM frequency:
  • 0: Default (20 kHz)
  • 1: 1 kHz
  • 2: 2 kHz
  • 3: 4 kHz
  • 4: 5 kHz
  • 5: 10 kHz
  • 6: 20 kHz
  • 7: 40 kHz
  • 8: 80 kHz
Bits 4 to 7 are reserved and should be set to 0.
Default 0
Command Set variable
Arduino library void setPwmMode(uint8_t motor, uint8_t mode)
uint8_t getPwmMode(uint8_t motor)

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

Target speed

Category motor-specific
Offset 2
Type signed 16-bit
Range −800 to 800
Default 0
Command Set speed
Set all speeds
Set all speeds using buffers
Arduino library void setSpeed(uint8_t motor, int16_t speed)
void setSpeedNow(uint8_t motor, int16_t speed)
void setAllSpeeds(int16_t speed1, ...)
void setAllSpeedsNow(int16_t speed1, ...)
void setAllSpeedsUsingBuffers()
void setAllSpeedsNowUsingBuffers()
void getTargetSpeed(uint8_t motor)

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).

Target brake amount

Category motor-specific
Offset 4
Type unsigned 16-bit
Range 0 to 800
Default 0
Command Set braking
Set braking now
Coast now
Arduino library void setBraking(uint8_t motor, uint16_t amount)
void setBrakingNow(uint8_t motor, uint16_t amount)
void coastNow()
uint16_t getTargetBrakeAmount(uint8_t motor)

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.

For the Motoron M3S256 and M3H256: this type of Motoron is only capable of full coasting and full braking, and it can only use coasting if it coasts 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 M3S256/M3H256 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.

Current speed

Category motor-specific
Offset 6
Type signed 16-bit
Range −800 to 800
Default 0
Command Set speed
Set all speeds
Set all speeds using buffers
Arduino library void setSpeed(uint8_t motor, int16_t speed)
void setSpeedNow(uint8_t motor, int16_t speed)
void setAllSpeeds(int16_t speed1, ...)
void setAllSpeedsNow(int16_t speed1, ...)
void setAllSpeedsUsingBuffers()
void setAllSpeedsNowUsingBuffers()
void getCurrentSpeed(uint8_t motor)

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,

Buffered speed

Category motor-specific
Offset 8
Type signed 16-bit
Range −800 to 800, or −8192 for coasting
Default 0
Command Set speed
Set all speeds
Arduino library void setBufferedSpeed(uint8_t motor, int16_t speed)
void setAllBufferedSpeeds(int16_t speed1, ...)
void setAllSpeedsUsingBuffers()
void setAllSpeedsNowUsingBuffers()
void getCurrentSpeed(uint8_t motor)

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.

Max acceleration forward

Category motor-specific
Offset 10
Type unsigned 16-bit
Range 0 to 6400
Units Speed change per 80 ms
Default 0
Command Set variable
Arduino library void setMaxAccelerationForward(uint8_t motor, uint16_t accel)
void setMaxAcceleration(uint8_t motor, uint16_t accel)
uint16_t getMaxAccelerationForward(uint8_t motor)

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.

Max acceleration reverse

Category motor-specific
Offset 12
Type unsigned 16-bit
Range 0 to 6400
Default 0
Command Set variable
Arduino library void setMaxAccelerationReverse(uint8_t motor, uint16_t accel)
void setMaxAcceleration(uint8_t motor, uint16_t accel)
uint16_t getMaxAccelerationReverse(uint8_t motor)

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

Max deceleration forward

Category motor-specific
Offset 14
Type unsigned 16-bit
Range 0 to 6400
Default 0
Command Set variable
Arduino library void setMaxDecelerationForward(uint8_t motor, uint16_t decel)
void setMaxDeceleration(uint8_t motor, uint16_t decel)
uint16_t getMaxDecelerationForward(uint8_t motor)

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.

Max deceleration reverse

Category motor-specific
Offset 16
Type unsigned 16-bit
Range 0 to 6400
Default 0
Command Set variable
Arduino library void setMaxDecelerationReverse(uint8_t motor, uint16_t decel)
void setMaxDeceleration(uint8_t motor, uint16_t decel)
uint16_t getMaxDecelerationReverse(uint8_t motor)

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

Starting speed forward

Category motor-specific
Offset 18
Type unsigned 16-bit
Range 0 to 800
Default 0
Command Set variable
Arduino library void setStartingSpeedForward(uint8_t motor, uint16_t speed)
void setStartingSpeed(uint8_t motor, uint16_t speed)
uint16_t getStartingSpeedForward(uint8_t motor)

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.

Starting speed reverse

Category motor-specific
Offset 20
Type unsigned 16-bit
Range 0 to 800
Default 0
Command Set variable
Arduino library void setStartingSpeedReverse(uint8_t motor, uint16_t speed)
void setStartingSpeed(uint8_t motor, uint16_t speed)
uint16_t getStartingSpeedReverse(uint8_t motor)

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.

Direction change delay forward

Category motor-specific
Offset 22
Type unsigned 8-bit
Range 0 to 250 (2500 ms)
Default 0
Units 10 ms
Command Set variable
Arduino library void setDirectionChangeDelayForward(uint8_t motor, uint8_t duration)
void setDirectionChangeDelay(uint8_t motor, uint8_t duration)
uint8_t getDirectionChangeDelayForward(uint8_t motor)

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).

Direction change delay reverse

Category motor-specific
Offset 23
Type unsigned 8-bit
Range 0 to 250 (2500 ms)
Default 0
Units 10 ms
Command Set variable
Arduino library void setDirectionChangeDelayReverse(uint8_t motor, uint8_t duration)
void setDirectionChangeDelay(uint8_t motor, uint8_t duration)
uint8_t getDirectionChangeDelayReverse(uint8_t motor)

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

Related Products

Motoron M3S256 Triple Motor Controller Shield for Arduino (Connectors Soldered)
Motoron M3S256 Triple Motor Controller Shield Kit for Arduino
Motoron M3S256 Triple Motor Controller Shield for Arduino (No Connectors)
Motoron M3H256 Triple Motor Controller for Raspberry Pi (Connectors Soldered)
Motoron M3H256 Triple Motor Controller Kit for Raspberry Pi
Motoron M3H256 Triple Motor Controller for Raspberry Pi (No Connectors or Standoffs)
Log In
Pololu Robotics & Electronics
Shopping cart
(702) 262-6648
Same-day shipping, worldwide
Menu
Shop Blog Forum Support
My account Comments or questions? About Pololu Contact Ordering information Distributors