3.7. Writing code

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

To control the Motoron, you need to send commands to it using its I²C or UART serial interface (whichever one it has). The commands are sequences of bytes (8-bit numbers from 0 to 255) and some of them generate responses which are also sequences of bytes. The details of what commands are supported and how to encode them in bytes are documented in Section 3.7. The details of the Motoron’s I²C interface are documented in Section 6, and the details of its UART serial interface are documented in Section 7. 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.

• I2CSimple and SerialSimple: Show how to control the Motoron in the simplest way.
• I2CCareful and SerialCareful: Show how to shut down the motors whenever any problems are detected.
• I2CRobust and SerialRobust: Show 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 or MotoronSerial object for each controller, and pass the device number (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 a examples named I2CSimpleMulti and SerialSimpleMulti which show how to control multiple Motorons this way.

Python library and examples

If you are controlling the Motoron from Python or MicroPython, 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: Show how to control the Motoron in the simplest way.
• *_careful_example.py: Show how to shut down the motors whenever any problems are detected.
• *_robust_example.py: Show 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 or MotoronSerial object for each controller, and pass the device number (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 a examples named *_multi_example.py which show how to control multiple Motorons this way.

The library also comes with examples named *_simple_no_library_example.py which are equivalent to the corresponding simple examples, but do not use the Motoron library. These examples are 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: 0x96 0x74

This command resets the Motoron to its default state. 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 11). 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 8. 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 9.

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 8 and see the I2CCurrentSenseCalibrate example that comes with the Arduino library.

Motion parameters

You can send a “Set variable” command (documented in Section 9) 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 Motoron only stores a few settings in its non-volatile EEPROM memory. Most settings, including the motion parameters and command timeout, get reset to their default values 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 9.