Building a Robot

A RoboRuckus robot can really be built to any design you want, provided it fits on the board and can properly communicate with the server and execute move orders. This page documents how to build the simplest, least expensive robot we could come up with for the game (though others smarter than us may have better ideas).


This should be a complete list of everything you need to build your robot (excepting tools like a soldering iron, flush cutters, etc…):

Prepping the Materials

The first step is to solder pins to the magnetometer and 9-DOF board; details on how to solder won’t be covered here, as there are already excellent tutorials out there. This assembly guide for the magnetometer provides an example of how to do this, the important thing to do is make sure the long side of the pins are pointing out the back (the side without the chip on it).

Pins should also be soldered around the entire perimeter of the Teensy in the same fashion. It’s also recommended that you cut the trace in between the 5V pads in preparation for using a battery power supply, like in this guide (Option #1). For the Teensy LC, the pads to cut between are the small ones next to the VUSB label.

PCB Assembly

Once all the items are organized and the pins soldered on, it’s time to attach things to the PCB. All the components should be soldered to the PCB following the silkscreen on the board. While the order you do this in doesn’t really matter, I do recommend starting with the large components like the Teensy, LED display, Wi-Fi module, and LED driver DIP socket (make sure the notch in the socket matches the notch on the silkscreen, in the “up” orientation).

You’ll need to add four sets of 0.1″ headers, two sets of three for the servos, and two sets of four for the sensors. These should be soldered in from the front, so that the long part of the header is facing up on the same side with the Teensy and other components.

If you don’t see where to solder the 0.1uF capacitors, look for two holes with a | in between them and with 0.1uF below them; the orientation of these doesn’t matter. For the 100uF capacitor, the orientation does matter, so be sure the negative lead is in the hole with the - symbol.

Soldering the voltage regulator in place can be tricky. It can stand upright, or it can be bent backwards. It won’t, and shouldn’t, lay flat, so you should solder it in place without pushing it all the way in if you want to lay it down. That way it can be bent backwards a bit but still have some space between its back and the PCB to allow for airflow and cooling. It’s probably best to bend the voltage regulator in place before soldering it.

Once the soldering is done, you can insert the LED driver into the socket, matching the notches for the orientation.

Setting Up

Following the instructions on the Teensy website, set up the Teensyduino software. During the software setup when you are asked to install libraries, check the box for i2c_t3. If that library is unavailable, you can manually download and install it from GitHub (see these instructions for installing libraries).

Next, following the same instructions as above, install the Adafruit Unified Sensor Library, and then download and install the modified Adafruit_HMC5883 and Adafruit_L3GD20_U libraries from the RoboRuckus GitHub repository.

Finally, you can download the bot code (BotCode.ino and movement.ino; these files should be kept in the same directory) from the repository. Once you open BotCode.ino in the Arduino software, you should be able to upload it to your Teensy (you’ll need to power the Teensy from the battery pack while uploading software via USB).

Testing the Motors

Once the board is assembled, the motors need to be tested and set up. Plug one motor into either of the motor headers. The orange signal wire should be on the bottom, plugged into the pin labeled “sig”. Power up the board and then, holding the motor in your left hand with the back facing towards the right and the wire running out the back towards your body, insert a tiny Phillips screwdriver in the hole on the rear. The screwdriver should catch on a small potentiometer in the rear of the motor.


Holding the motor for tuning.

Slowly rotate the screwdriver clockwise (away from you) until the motor starts to spin, if the motor is already spinning, do this anyway to see if the motor slows down and, if it does, keep turning until it stops and then speeds up again, if it doesn’t slow down, stop turning. Once the motor is turning, slowly turn the screwdriver back the other way just until the motor stops turning, then turn it an additional quarter turn.

Repeat this process with the other motor. Now your system is ready for assembly, testing, and tuning!

Testing the Robot

To test your system you must first hook up the sensors. Following the labels on the back of the PCB silkscreen, use the F/F jumpers to connect the magnetometer to the front sensor pins, and the 9-DOF board to the rear sensor pins. VCC should be connected to the VIN pin on the sensor, GND to GND, SDA to SDA, and SCL to SCL.

Now power on your board. The decimal point on the LED display should light up, followed in a little bit by the letter E. This indicates that the system powered up successfully, but was unable to contact the game server, which is good since presumably there isn’t one currently running.

If you don’t see the letter E after a minute, power things off and double-check that the senors are hooked up correctly, also check all your solder joints for errors or shorts. If you still have problems, plug your Teensy into your computer via USB and power on your board. Open the Arduino software and serial monitor (make sure to select the correct COM port) then power cycle the board. Hopefully, the output from the Teensy should provide helpful debug information (it may be necessary to quickly close and reopen the serial monitor as the board is powering up to see output).

Robot Assembly

Hot glue makes a quick and easy way to stick the robot together and allows for easy rearrangement if necessary, though it does tend to require semi-regular repairs. For permanent sticking, you can use epoxy, E6000, or your favorite adhesive.

To clarify some terminology, the front of the robot is the end of the PCB with the LED display, and the rear is the end with the Teensy.

First, remove the screw from the battery case, as you likely won’t be able to access it once things are together. Next, glue the PCB to the battery case. You want to make sure the switch on the case is facing down (on the opposite side from which the PCB is glued to), and the case should open sideways—i.e. perpendicular to the front-rear axis—to allow access to the batteries.

Next, glue the front and rear sensors in place on the bottom of the battery case. The chips should face downwards and be aligned in the center of the front-rear axis (the chip to have centered in the 9-DOF board is the rectangular one), with the pins and wires facing towards the outside. It may be helpful to offset the rear sensor vertically by gluing a few spacers, like pennies, between the sensor and the battery case.


A fully assembled robot as seen from the bottom. The left-right axis appears reversed because the robot is upside-down.

Next, press the wheels onto the motors and screw the wheels in place. Glue the wheels/motors onto the bottom of the battery case. The center of the motor case should be centered on the left-right axis with the wires running out towards the back. Doing this places the wheels themselves slightly back from center, which helps prevent the tipping over when moving, and also allows the robot to rotate easily around its center.

Then assemble and glue the caster in place. It should be near the front and, if using a plastic caster, it can even be glued on top of the front sensor. To increase stability, two front casters could be used, one on each side of the front of the case.

Finally, you’ll need to add some weight to the front of the robot to keep it from tipping over. A stack or two of pennies is a cheap and effective way to go, but any weights or washers would work.


A fully assembled robot.

Once your posse of robots is assembled, you can decorate them to get them ruckus ready!

Robot lineup, front.

Robot lineup, back.

Robot lineup, top.

Tuning the System

Tuning the system takes two phases done in order.

Tuning Wheel Speeds

First, open the BotCode.ino file and find these lines:

Uncomment the second line so it looks like this (note the highlighted line that was altered):

Now upload the updated code to the robot and set it down on a flat surface with plenty of room, like a wood floor or the game board. The robot will then proceed to drive forward for three seconds before driving backwards for three seconds. Your robot almost certainly won’t drive straight, and your next goal is to fix that.

Modifying the below lines in the BotCode.ino file…

…will allow you to adjust the speed of your robot’s wheels (the actual values you see in your BotCode.ino file may be different, this is normal). Increasing the leftForwardSpeed or rightBackwardSpeed values will make those wheels turn faster when driving in the appropriate direction. Decreasing the rightForwardSpeed or leftBackwardSpeed values will do the same.

Adjust these values as needed, re-uploading the code and testing the bot’s driving after each adjustment. You want to iterate the adjustments until the the robot is driving as straight as possible both forwards and backwards (it doesn’t have to be perfect). You also want to make sure the bot is driving close to the same speed forwards and backwards, and that it’s not driving too terribly fast.

If the robot has been stored for a while, or transported and bumped around, you may need to repeat this process to re-tune the wheel speeds.

Tuning Movement

To tune the robot movement you will need at least one section of completed game board. Start by commenting out setup1 and uncommenting setup2, as shown below:

Upload the code and place the robot on a space on the game board. The robot will attempt to drive forward two spaces, backup one space, turn right, turn left, and then perform a U-turn. If your robot completes this sequence without problem, then congratulations, you’re done!

If your robot has problems, you’ll want to look for this section in the BotCode.ino file:

If the robot doesn’t drive the correct number of spaces, i.e. if drives too many or too few spaces when moving forwards or backwards, you can adjust the Z_threshold value; making it less negative will make the robot more likely to stop sooner and vice versa.

If the robot has trouble going in a straight line, first try increasing the turnBoost value, which controls how fast the robot moves to correct itself when drifting off course (a small increase of two or three is usually enough). If that doesn’t help, you can try adjusting the drift_threshold and turn_drift_threshold values. These values, respectively, control how sensitive the magnetometer (in μT) and gyroscope (in radians) are to the robot drifting off course. Decreasing these values will make the robot more sensitive to changes in its direction to help keep it on a straight line. If these values are too small, the robot may shake back and forth a lot, or over-correct and drive completely off course.

Ideally, the robot will rely mostly on the magnetometer to follow the magnetic tape line, but in case it drifts too far from the magnetic line the gyroscope should push it back on course until the magnetometer can take over again.

Lastly, adjusting the turnFactor will alter how far, in radians, the robot turns when attempting to make a 90° turn, or twice that for a 180° turn. If the robot is turning too far, lower this value, if it’s not turning far enough, increase it.

It might take some experimentation, but by adjusting all these values you should be able to get a robot that can move fairly reliably. This is still a chaotic game, so don’t expect any robot to move perfectly; that’s part of the fun!

Now that your robot is a lean, mean, board navigating machine, comment out all the setup code, as shown below:

You should also change your robot’s name to whatever you want by editing the text between the quotation-marks in this line of code (%20 in this instance represents the URL encoding of a space):

Upload the code to your robot, and get ready for some ruckus!

Further Debugging

You may have noticed these two lines of code while tuning your robot:

Uncommenting the line with debug will make the robot more verbose in outputting information through the Arduino serial monitor (or really, any serial monitor), especially while moving or communicating with the game server. By enabling this and keeping the robot connected via USB to a computer running the serial monitor while testing the robot, you can get a lot more information that will hopefully be helpful in tracking down any strange bugs in the robots movement or behavior.

Uncommenting debug2 will disable most of the robot’s behavior. Instead, by communicating over the Arduino serial monitor (with the robot plugged in to the computer via USB), you can send commands directly to the Wi-Fi module, and see the Wi-Fi module’s responses. This is useful if you’re having trouble getting the robot to communicate with the server and want to track down the problem.