3.6. Writing code

This section documents what you need to know to get started writing code to control the Motoron.

The Motoron’s I²C interface allows you to send commands to it and receive responses from it. The commands are sequences of bytes (8-bit numbers from 0 to 255) and the responses are also sequences of bytes. The details of how the I²C interface works are documented in Section 6. The details of what commands are supported and how to encode them in bytes are documented in Section 3.6. Numbers prefixed with “0x” here are written in hexadecimal notation (base 16), and they are written with their most significant digits first, just like regular decimal numbers.

Arduino library and examples

If you are controlling the Motoron from an Arduino or Arduino-compatible board, we recommend that you install our Motoron Arduino library and use one of the examples that comes with it as a starting point for your code. The library comes with these beginner-friendly examples, which you can find in the Arduino IDE under Files > Examples > Motoron.

  • Simple: Shows how to control the Motoron in the simplest way.
  • Careful: Shows how to shut down the motors whenever any problems are detected.
  • Robust: Shows how to ignore or automatically recover from problems as much as possible.

Each of these examples just controls one Motoron. If you are using multiple Motorons, you can create an additional MotoronI2C object for each controller, and pass the I²C address of each Motoron to the constructor for each object. This can be done for any of the examples listed above, and the library comes with an example named SimpleMulti which is based on the Simple example and shows how to control multiple Motorons this way.

Python library and examples

If you are controlling the Motoron from a Raspberry Pi, you might consider downloading our Motoron Python library and using one of the examples that comes with it as a starting point for your code. The Python library was designed to have the same features and behave nearly the same as the Arduino library. However, one major difference is that it generally throws an exception whenever there is a communication error, whereas the Arduino library only reports errors via its getLastError() method.

Like the Arduino library, the Python library comes with these beginner-friendly examples:

  • simple_example.py: Shows how to control the Motoron in the simplest way.
  • careful_example.py: Shows how to shut down the motors whenever any problems are detected.
  • robust_example.py: Shows how to ignore or automatically recover from problems as much as possible.

Each of these examples just controls one Motoron. If you are using multiple Motorons, you can create an additional MotoronI2C object for each controller, and pass the I²C address of each Motoron to the constructor for each object using the address parameter. This can be done for any of the examples listed above, and the library comes with an example named simple_multi_example.py which is based on simple_example.py and shows how to control multiple Motorons this way.

The library also comes with an example called simple_no_library_example.py which is equivalent to simple_example.py, but does not use the Motoron library. This example is meant to be used as a reference for people trying to get started with the Motoron from a different programming environment, since it is easier to see exactly what bytes are being sent.

Initialization sequence

This is a sequence of commands you can run near the beginning of your code to help you get started with controlling the Motoron.

Description: Reinitialize
Bytes: 0x94 0x74

This command resets the Motoron to its default state (mostly). We recommend doing this when starting up to ensure that the behavior of your system will only depend on the code you are currently running, instead of being affected by settings that you might have set previously in an old version of your code. The bytes shown above are the command byte for the “Reinitialize” command followed by a cyclic redundancy check (CRC) byte.

Description: Disable CRC
Bytes: 0x8B 0x04 0x7B 0x43

This command disables the cyclic redundancy check (CRC) feature of the Motoron (documented in Section 9). The CRC feature is enabled by default to make the Motoron less likely to execute incorrect commands when there are communication problems. Disabling CRC makes it easier to get started writing code for the Motoron because you do not have to implement the CRC computation or append CRC bytes to each command you send. Once you have gotten your system to work, you might consider implementing CRC and removing this command to make things more robust. This is an example of the more general “Set protocol options” command, and the last byte shown above is a CRC byte.

Description: Clear reset flag
Bytes: 0xA9 0x00 0x04

This command clears (sets to 0) a bit in the Motoron called the “Reset flag”. This flag gets set to 1 after the Motoron powers on or experiences a reset, and with the default configuration it is considered to be an error, so it prevents the motors from running.This is an example of the more general “Clear latched status flags” command, and there is no CRC byte appended because we disabled the CRC feature above.

The reset flag exists to help prevent running motors with incorrect settings. In case the Motoron itself gets reset while your system is running, the Reset flag will be set and the motors will not run.

Initialization sequence (with CRC)

This is similar to the initialization sequence above, except it leaves CRC enabled.

Description: Reinitialize
Bytes: 0x94 0x74

Description: Clear reset flag
Bytes: 0xA9 0x00 0x04

The bytes at the end of each command are CRC bytes. Instead of hard coding those bytes, you should be able to calculate each one by applying the CRC algorithm to the command and data bytes immediately before it.

Command timeout

By default, the Motoron will turn off its motors if it has not received a valid command in the last 1.5 seconds. The details of the command timeout feature are documented in Section 7. This means that the motors will stop running if your microcontroller crashes, goes into programming/bootloader mode, or stops running your motor control code for any other reason. You can send a “Set variable” command to configure the timeout period or disable the feature altogether. Change the “Command timeout” variable if you want to change the amount of time it takes for the Motoron to time out, or change the “Error mask” variable if you want to disable the command timeout. The “Set variable” command and all other commands are documented in Section 8.

Current limit

The Motoron M2S and M2H controllers have configurable hardware current limiting and the default value of the current limit is generally lower than what the controller is capable of, so you might need to set the current limit to get the desired performance of your system. However, note that the current limit should be set carefully because these high-power controllers do not have meaningful over-temperature protection. For more information see the “Current limit” variable in Section 7 and see the CurrentSenseCalibrate example that comes with the Arduino library.

Motion parameters

You can send a “Set variable” command (documented in Section 8) to configure how the motors move and other settings. In particular, you can set acceleration and deceleration limits for each motor and each direction of motion, which helps to reduce sudden current spikes or jerky motions.

The only Motoron setting that is stored in non-volatile memory is its I²C address. Every other setting, including the motion parameters and command timeout, gets reset to its default value whenever the Motoron powers on, resets, or receives a “Reinitialize” command.

Motor control

Once you have taken care of the initialization and configuration described above, you are ready to run some motors! See the “Set speed” and “Set all speeds” commands in Section 8.

Related Products

Motoron M3S256 Triple Motor Controller Shield for Arduino (Connectors Soldered)
Motoron M3H256 Triple Motor Controller for Raspberry Pi (Connectors Soldered)
Motoron M2S18v18 Dual High-Power Motor Controller Shield for Arduino (Connectors Soldered)
Motoron M2H18v18 Dual High-Power Motor Controller for Raspberry Pi (Connectors Soldered)

Related Categories

Motoron Motor Controllers
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