Using the RoboClaw Arduino Library

The RoboClaw Arduino library is now the Basicmicro Arduino library, published in the Arduino Library Manager as Basicmicro. It lets an Arduino control RoboClaw and MCP motor controllers over serial: create a serial object, create a Basicmicro controller object from it, call begin() with the baud rate, then call motor control functions on the controller object.

The Basicmicro Arduino library is easy to use and simple to include in Arduino sketches. It works with all RoboClaw and MCP motor controllers with a serial interface, using either hardware or software serial, on Arduino and Arduino-compatible boards like the ESP32 and ESP8266. This article covers installing the library, the general pattern for using it, and a description of the most commonly used functions it contains.

How Do You Install the Basicmicro Arduino Library?

The library is available in the Arduino Library Manager, so it installs directly from the Arduino IDE with nothing to download.

1. In the Arduino IDE, open the top menu and click “Sketch”, then “Include Library”, then “Manage Libraries”.
2. Search for “Basicmicro” in the Library Manager.
3. Click “Install”. The library is now added to the Arduino installation and can be referenced from sketches.

How Does the Basicmicro Library Work?

There is a general scheme for using the Basicmicro library. First a serial communication object is created; this can be either an Arduino hardware or software serial object. Then a Basicmicro object is created using the serial object and a timeout parameter. Communication with the attached RoboClaw begins when the begin() function of the Basicmicro object is called. From there, functions to control the RoboClaw are called on the Basicmicro object.

Which Boards Can Use Software Serial?

The stock SoftwareSerial library is only available on AVR-based boards; ARM-based Arduino models do not support it, so on those boards a hardware serial port is the only way to connect a RoboClaw. For details on connecting through a hardware serial port, see Using Hardware Serial with the RoboClaw Arduino Library. Software serial is also unreliable above 57600 bps. The table below shows which connection to use on common models.

How Do You Use the Library in a Sketch?

1. Include the Basicmicro library at the top of the sketch.

   // Include the Basicmicro library
   #include <Basicmicro.h>

2. Create a serial communications object. Either a hardware or a software serial object can be used. A hardware serial object like Serial1 is predefined and ready to use. A software serial object must be created in the sketch and only works on AVR-based boards like the Uno and Nano, as shown in the table above. The example below shows the top of a sketch set up for software serial, with the SoftwareSerial include added below the Basicmicro include.

   // Include the necessary libraries
   #include <Basicmicro.h>
   #include <SoftwareSerial.h>
   
   // The parameters to the constructor define the receive and transmit pins respectively
   SoftwareSerial controllerSerial(10, 11); // RX, TX

   Some Arduino models have their hardware serial I/O wired to the USB to serial adapter built into the board. On those boards the USB connection must be disconnected to run a sketch that uses hardware serial to communicate with the RoboClaw.

3. Create the Basicmicro object. Pass a pointer to the serial object (the name of the serial object prepended with ‘&’) and a timeout value for serial communication in microseconds.

   // 10000 microseconds = 10ms serial read timeout
   Basicmicro roboclaw(&controllerSerial, 10000);

4. Start communication with the RoboClaw. Once a Basicmicro object has been created, communication with the attached RoboClaw starts when the begin() function is called on it. The begin() function takes one parameter, the baud rate for serial communication. This baud rate should match the one set via BasicMicro Motion Studio.

   // Call the begin function passing it the baud rate for serial comms
   roboclaw.begin(38400);

5. Call functions on the Basicmicro object. After begin() is called the Basicmicro object is ready to use for controlling the attached RoboClaw. Functions can be called on the object at will.

   // Run motor 1 in the forward direction at about 30% duty cycle
   roboclaw.DutyM1(0x80, 10000);

Complete Example

Below is a complete example of the code to control a RoboClaw, from setup to calling a function to control the RoboClaw. The header is Basicmicro.h, the controller object is a Basicmicro object, and motor commands like DutyM1() take a signed duty cycle value from -32767 (full reverse) to 32767 (full forward). This example uses software serial, so it runs on AVR boards like the Uno and Nano; on boards without software serial support, connect through a hardware serial port instead, as covered in Using Hardware Serial with the RoboClaw Arduino Library.

// Include the necessary libraries
#include <Basicmicro.h>
#include <SoftwareSerial.h>

// Address of the motor controller as set in Motion Studio
#define ADDRESS 0x80

// Create the software serial object for the RoboClaw (RX, TX)
SoftwareSerial controllerSerial(10, 11);

// Create the Basicmicro object with a 10ms (10000 microsecond) timeout
Basicmicro roboclaw(&controllerSerial, 10000);

void setup() {
  // Start communicating with the RoboClaw hardware
  // The baud rate must match the one set in Motion Studio
  roboclaw.begin(38400);
}

void loop() {
  // Run motor 1 forward at about 30% duty cycle
  roboclaw.DutyM1(ADDRESS, 10000);
  delay(2000);

  // Stop motor 1
  roboclaw.DutyM1(ADDRESS, 0);
  delay(2000);
}

Basicmicro Library Functions

Each function in the library wraps one packet serial command that is sent to the controller. Every function takes the controller’s address as its first parameter, which is how multiple controllers can share a single serial bus. Command functions return true when the RoboClaw acknowledges the command, and read functions return the requested value. The most commonly used functions are grouped below; see the library’s examples folder on GitHub for a working sketch demonstrating each one.

Duty Cycle Functions

The functions below drive the motors directly with a PWM duty cycle, with no encoders or PID tuning required. Duty is a signed 16-bit value from -32767 (full reverse) to 32767 (full forward), where 0 stops the motor. The DutyAccel versions add an accel parameter that ramps the duty cycle change.

DutyM1(address, duty)
DutyM2(address, duty)
DutyM1M2(address, duty1, duty2)
DutyAccelM1(address, duty, accel)
DutyAccelM2(address, duty, accel)
DutyAccelM1M2(address, duty1, accel1, duty2, accel2)

Below is an example of using one of these functions:

// Run motor 1 forward at about 30% duty cycle
roboclaw.DutyM1(0x80, 10000);

Speed Functions

The functions below run the motors at a commanded speed using encoder feedback and the controller’s velocity PID. Speed is in encoder counts per second, and accel is in counts per second squared. Velocity PID parameters must be set and tuned, in Motion Studio or with SetM1VelocityPID/SetM2VelocityPID, before these commands will work correctly.

SpeedM1(address, speed)
SpeedM2(address, speed)
SpeedM1M2(address, speed1, speed2)
SpeedAccelM1(address, accel, speed)
SpeedAccelM2(address, accel, speed)
SpeedAccelM1M2(address, accel, speed1, speed2)

Below is an example of using one of these functions:

// Run motor 1 at 1000 encoder counts per second
roboclaw.SpeedM1(0x80, 1000);

Mixed Mode Functions

The functions below are compatibility commands for using the RoboClaw when mixing is enabled. This is the type of drive setup that a tank-style robot uses, also referred to as differential drive. Unlike DutyM1M2(), which sets each motor’s duty cycle directly, the mixed mode functions assume a differential steering setup and handle the mixing between the two motors internally. The value from 0 to 127 sets motor power, not a measured speed. For ForwardMixed, BackwardMixed, TurnRightMixed, and TurnLeftMixed, 0 is 0% power and 127 is 100% power. For ForwardBackwardMixed the range is centered: 0 is full reverse, 64 is stop, and 127 is full forward. LeftRightMixed works the same way, with 0 full left, 64 straight, and 127 full right. For most projects the duty cycle functions described earlier are the simpler choice; use the mixed mode functions when you want the controller to handle the differential drive mixing for you.

ForwardMixed(address, power)
BackwardMixed(address, power)
TurnRightMixed(address, power)
TurnLeftMixed(address, power)
ForwardBackwardMixed(address, power)
LeftRightMixed(address, power)

Below is an example of using one of these functions:

// Drive both motors in the forwards direction at about half power
roboclaw.ForwardMixed(0x80, 64);

Encoder Functions

The functions below are for reading and setting encoder values. The read functions return a 32-bit unsigned value (uint32_t). The status and valid parameters are optional: status returns the encoder’s direction and underflow/overflow flags, and valid reports whether the read succeeded. The set functions take a 32-bit value as their parameter.

ReadEncM1(address, status, valid)
ReadEncM2(address, status, valid)
SetEncM1(address, val)
SetEncM2(address, val)
ReadSpeedM1(address, status, valid)
ReadSpeedM2(address, status, valid)
ResetEncoders(address)

Below is an example of using one of these functions:

// Read the current value of the encoder on channel 1
uint32_t 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 quadrature counts. Flag 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 it controls motor channel 1 and M2 means that it controls motor channel 2. Functions with both M1 and M2 in their name can be used to control both motors at the same time. Like the speed functions, these commands use encoder feedback, so Velocity PID parameters must be set and tuned before they will work correctly.

SpeedDistanceM1(address, speed, distance, flag)
SpeedDistanceM2(address, speed, distance, flag)
SpeedDistanceM1M2(address, speed1, distance1, speed2, distance2, flag)
SpeedAccelDistanceM1(address, accel, speed, distance, flag)
SpeedAccelDistanceM2(address, accel, speed, distance, flag)
SpeedAccelDistanceM1M2(address, accel, speed1, distance1, speed2, distance2, flag)

Position Functions

The functions below are used for motor positioning. Address is the address of the RoboClaw to control. Accel and deccel set the acceleration and deceleration of the motor. Speed sets the speed of the motor in quadrature pulses per second. Position sets the position of the motor in encoder counts. Flag 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 position command immediately. M1 in the function name means it controls motor channel 1 and M2 means that it controls motor channel 2. Functions with both M1 and M2 in their name can be used to control both motors at the same time. Position PID parameters must be set and tuned, in Motion Studio or with SetM1PositionPID/SetM2PositionPID, before these commands will work correctly.

SpeedAccelDeccelPositionM1(address, accel, speed, deccel, position, flag)
SpeedAccelDeccelPositionM2(address, accel, speed, deccel, position, flag)
SpeedAccelDeccelPositionM1M2(address, accel1, speed1, deccel1, position1, accel2, speed2, deccel2, position2, flag)

Next Steps

With the library installed and the basic pattern in hand, Using Hardware Serial with the RoboClaw Arduino Library covers connecting through a hardware serial port, which works on every board the library supports. To put the encoder functions to work, see Using Encoders with the Arduino Library.

Related Products

RoboClaw 2x7A Motor Controller

In Stock · Part: IMC404

$79.95

View Product

RoboClaw 2x30A Motor Controller

In Stock · Part: IMC413

$134.95

View Product

RoboClaw 2x60A Motor Controller

In Stock · Part: IMC414

$229.95

View Product