Using the RoboClaw Python Library

April 9, 2019

Introduction

BasicMicro provides a library written in Python for controlling the RoboClaw motor controller. The library handles setting up serial communications with the RoboClaw and contains a wealth of functions for controlling a project built around the RoboClaw. This Application Note covers the usage of the library and an overview of the functions available within it.

Downloading the RoboClaw Python library

The RoboClaw Python library can be downloaded from here. Save the file to a location where it is easily found, as it will need to be referenced/included in any Python code used to control the RoboClaw.

Installing pip

Pip is the package manager for Python, it needs to be installed before using the library so that the package called “pyserial” can be installed. This is the only prerequisite for using the BasicMicro Python library.
Check the Python version currently installed by entering the following command in a terminal window:
python –version
If the Python version installed is greater than 2.7.9 for Python2 or greater than Python 3.4 for Python3 no further steps need to be taken as Pip is included with these releases. If the version of Python installed is older than these releases an upgrade to a more recent version is recommended. This is the easiest way to ensure that pip is installed.
If running a version of Python without pip installed see this page for information about how to install pip manually.

Installing the pyserial library

For the RoboClaw Python library to work properly the “pyserial” package needs to be installed. It can be installed via pip with the following command:
If using Python 2:
pip install pyserial
If using Python 3:
pip3 install pyserial

Overview

Using the library only involves a few lines code and is rather straightforward. First a RoboClaw object is created by passing it the name of the serial port and the baudrate to be used. Then the “Open()” function is called on the previously created object to start the communication with the RoboClaw hardware. From here it is a simple matter of calling the available functions in the library to control the RoboClaw. Below each of these steps is detailed with example code.

>

Include the RoboClaw Library

The first step in using the Python library is to import the relevant section of code from the RoboClaw Python library. In the example below two import statements are shown, one for Python 2 and one for Python 3. Only use the import statement that is relevant for the version of Python being used.
# import the relevant code from the RoboClaw library

# if using Python 2
from roboclaw import Roboclaw

#if using Python 3
from roboclaw_3 import Roboclaw

Create the RoboClaw object

# Create the RoboClaw object, passing the serial port and baudrate

roboclaw = Roboclaw(“/dev/ttyS0”, 38400)

Start Communication with the RoboClaw

Communication with the RoboClaw begins when the “Open()” function is called on the newly created RoboClaw object. This function takes no parameters.
# Call the Open() function on the RoboClaw object

roboclaw.Open()

Calling Functions on the RoboClaw object

# Start motor 1 in the forward direction at half speed

# the first parameter is the address, the second is the speed in a range from 0 to 127

roboclaw.ForwardM1(0x80, 63)

A Complete Example

# Complete example of using the RoboClaw library

#import the relevant code from the RoboClaw library

from roboclaw import Roboclaw

# address of the RoboClaw as set in Motion Studio

address = 0x80

# Creating the RoboClaw object, serial port and baudrate passed

roboclaw = RoboClaw(“/dev/ttyS0”, 38400)

# Starting communication with the RoboClaw hardware

roboclaw.Open()

# Start motor 1 in the forward direction at half speed

roboclaw.ForwardM1(address, 63)

RoboClaw Library Functions

Operating Individual Motors

The functions below are used to control the speed and direction of individual motors. Address is the address of an individual RoboClaw as set in Motion Studio. Speed is a value between 0 and 127 used to set the speed of the motor.
ForwardM1(address, speed)

BackwardM1(address,speed)

ForwardM2(address, speed)

BackwardM2(address,speed)

ForwardBackwardM1(address,speed)

ForwardBackwardM2(address,speed)

Below is an example of using one of these functions:
// Run motor 1 in the forwards direction at half speed

roboclaw.ForwardM1(0x80,63);

Mixed Mode Functions

The functions below are for using the RoboClaw when mixing is enabled. This is the type of drive setup that a tank-style robots uses. It is also referred to as differential drive. The ForwardsBackwards and LefRight functions take a value between 0 and 127 where half the max value is the divide between forwards/backwards and left/right. In all of the other functions the values between 0 and 127 denote min and max speed.
ForwardMixed(address,speed)

BackwardMixed(address,speed)

TurnRightMixed(address,speed)

TurnLeftMixed(address,speed)

ForwardBackwardMixed(address,speed)

LeftRightMixed(address,speed)

Below is an example of using one of these functions:

// Run both motors in the forwards direction at half speed

roboclaw.ForwardMixed(0x80,63);

Encoder Functions

The functions below are for using the RoboClaw when mixing is enabled. This is the type of drive setup that a tank-style robots uses. It is also referred to as differential drive. The read functions return a 32-bit value and a long int should be used to store the value. The set functions take a 32-bit value as their parameter.

>

ReadEncM1(address)

ReadEncM2(address)

SetEncM1(address,val)

SetEncM2(address,val)

ReadSpeedM1(address)

ReadSpeedM2(address)

ResetEncoders(address)

Below is an example of using one of these functions:
// Read the current value of the encoder on channel 1

encoder_1_count = roboclaw.ReadEncM1(0x80);

Distance Functions

The functions below are used to move attached motors a specific distance. Address is the address of the RoboClaw to control. Speed is the speed of the motor in quadrature pulses per second. Distance is the distance to move in quadrate counts. Buffer controls whether the command is executed immediately or stored until any previous commands are finished. A buffer value of 0 stores the command and a value of 1 executes the distance command immediately. Accel sets the acceleration for the motor. M1 in the function name means in controls motor channel 1 and M2 means that it controls motor channel 2. Functions with M1 and M2 in their name can be used to control both motors at the same time.
SpeedDistanceM1(address,speed,distance,buffer)
SpeedDistanceM2(address,speed,distance,buffer)
SpeedDistanceM1M2(address,speed1,distance1,speed2,distance2,buffer)
SpeedAccelDistanceM1(address,accel,speed,distance,buffer)
SpeedAccelDistanceM2(address,accel,speed,distance,buffer)
SpeedAccelDistanceM1M2(address,accel,speed1,distance1,speed2,distance2,buffer)

Position Functions

The functions below are used for motor positioning. Address is the address of the RoboClaw to control. Accel and deccel set the accelearation and decceleration of the motor. Speed set the speed of the motor in quadrate pulses per second. Position set the position of the motor in encoder counts. Buffer controls whether the command is executed immediately or stored until any previous commands are finished. A buffer value of 0 stores the command and a value of 1 executes the distance command immediately. M1 in the function name means in controls motor channel 1 and M2 means that it controls motor channel 2. Functions with M1 and M2 in their name can be used to control both motors at the same time.
SpeedAccelDeccelPositionM1(self,address,accel,speed,deccel,position,buffer)
SpeedAccelDeccelPositionM2(self,address,accel,speed,deccel,position,buffer)
SpeedAccelDeccelPositionM1M2(self,address,accel1,speed1,deccel1,position1,accel2,speed2,deccel2,position2,buffer)