So you bought a balance bot kit... now what? 

First, thank you! We are excited to share this project with you. We'll break this tutorial into three parts.

1. Hardware and Mechanical setup 🔧
2. Software Setup 👾
3. Live Tuning over WiFi 📈

1. Hardware and Mechanical Setup 🔧

With your Scout kit, you should have received: 

1. Scout's main body 
2. One MotorGo Mini PCB
3. One IMU PCB
4. Two motors pre-assembled with motor mounts 
5. Two wheels
6. Googly eyes, motor cables/converter boards, encoder cables, nuts/bolts, and Allen keys 

Step 1 - Prepare Scout's Body 

The only thing more fun than making a cool robot is making a cute robot. We recommend slapping those googly eyes on (a dab of super glue helps them stick) and drawing your balance bot a face! There is a small flat rectangle on the bottom of the main body where you can name your balance bot too. We default to Scout, but you can choose whatever name you want.

You will also want to remove the retainer caps bolted to Scout's body. These were attached for shipping and will hold the motors in place. 

Step 2 - Prepare the PCB

For this demo, we attach an IMU (inertial measurement unit) to the MotorGo GPIO (general purpose input/output) pins. The main thing is, make sure that your "VCC" pin on the IMU lines up with the 5V pin on the MotorGo board. Refer to the image below for how it should look. If these pins aren't aligned, the software will get confused and won't work, so double check to make sure the IMU is installed as shown.

In our testing, the IMU's female pins fit snugly on the MotorGo's male pins. We don't want the IMU to be wobbly. If the IMU is wobbly in your build, you can tape it down to hold it securely. 

.

There are also two tiny PCBs labeled "converter boards". These convert the default motor connector (3-pin micro JST) to the pins we need for the MotorGo board (3-pin DuPont). Connect these to the motor mounts with the motor cables as shown below.

Step 3 - Assemble the Robot 🤖

Now for the fun! 

Space is a little tight in Scout's body, so we do this assembly in four parts. 

.

Part A - attach encoder cables to the MotorGo board and place the board in the balance bot body. 

don't bolt it down yet. We do this because the MotorGo board will need to move up a little bit for the motor mount installation. 

.

Part B - Install motor mounts into receivers. 

It's easier to connect the encoder to the motor mount outside of the robot like shown below... 

... and then install the motor mount into the robot. Careful not to pinch or smush wires in the motor mount receiver rail. 

Repeat this for the second side and you're done. 

Note: the encoder cables only let you install them one way. The motor leads can be installed either way because our calibration sets the motor's "positive" direction the same every time.

.

Part C - Bolt down the MotorGo board and the motor mount receiver caps. 

The kit includes M3x12 bolts and nuts. You can use these to install the MotorGo board to the balance bot body. We typically get these finger-tight and only use 2 bolts because we're not doing anything too extreme. The kit also has M3x8 bolts to secure the retainer rail caps. This locks the motor mounts to the body. Snug these down with the included Allen key and try to wiggle the motors to make sure they're secure.

.

Part D - Install the wheels. 

Use the supplied wheel bolts and small Allen key for this step. Make sure the rubber bands stay on the wheels, they give better traction on most surfaces.

There's no need to bolt these down too tight, it's easy to strip the threads for these smaller bolts. Just snugging down with the supplied Allen key is fine.

Nice work! Now the balance bot is fully assembled and ready for programming. 

.

2. Software Setup 👾

Set up MotorGo in Arduino

Check out our docs for software setup. The MotorGo Mini is a precursor to the MotorGo Axis, but the software setup is identical. 

See our Quickstart Guide and use the Arduino IDE setup. Once you have the MotorGo Mini Driver installed on the Arduino IDE, you just need to:

 

Set up IMU driver

Use this link to download a driver for the IMU we use for this project. You want to download the file "MPU6050_Driver.zip" as a zip file. Do not unzip it. After you have the .zip file downloaded, 

1. Go to Sketch -> Include Library -> Add .ZIP Library 
2. Select the MPU6050_Driver.zip file you just downloaded 

The software needed for the IMU should now be installed and ready to run in your Arduino IDE. 

Note for Safari: for some reason, Safari automatically unzips downloads. In this case, Arduino needs the package in .ZIP form. If you can't download just the .ZIP through Safari, we've had luck downloading it on Chrome instead.

You can also set this up in Platformio. The steps are similar and explained in our docs, but we will proceed with Arduino for the rest of this tutorial. 

.

Pick the right MotorGo board and port

With the MotorGo board definition and driver library set up, the MotorGo board should appear in the Arduino IDE when you're selecting boards. Make sure the right port is also selected. The MotorGo used in this project is the MotorGo Mini 1.

Calibrate the motors

First thing you'll want to do is run the calibrate_motors example sketch. This sketch tells the MotorGo to run through its automated calibration procedure to map the motor's position to the magnetic encoder (EncoderGo), saving the calibration to the MotorGo's onboard memory.

.

For a given motor, encoder, and motor lead orientation (don't flip your wires!), you only need to calibrate once. The MotorGo will remember this calibration value until you run the calibration procedure again.

.

 Flash the balance bot code 

Now find the balance_bot example sketch. You will need to edit a couple of fields before running this successfully.

.

Near the top of the example, there are two strings: WIFI_SSID and WIFI_PASSWORD. Replace these with your home wifi network name and password. This needs to be the same network your computer is connected to.

With your wifi SSID and password updated, you should be able to upload this code to the balance bot. Again, make sure the right board and port are selected within the Arduino IDE.

.

The program will compile, upload to the MotorGo, and then start running through standard serial outputs on your serial monitor. Watch this serial output. It gives you the http address you need to connect to the board over wifi in the next section.

Notice also that the MotorGo starts reporting pitch values in the serial terminal. This is the code default. Pitch refers to the measured 'balancing angle' of the robot from the IMU. This is useful for initial playing around and for troubleshooting if anything comes up.

.

3. Live Tuning over WiFi 📈

With the code working, the last step is to start configuring the robot over wifi. At this stage, we recommend unplugging the robot from your computer and plugging it into a USB-C wall brick or power supply. In general, it is best practice to run robots on an external power supply. Computers have low current limits and you don't want to overload yours!

.

If the code is working fine on your computer, the MotorGo will simply reboot and reconnect to your wifi router when you plug it into the wall charger. Make sure you copied and pasted the http address. This address won't change between power cycles, and having it copied will let you connect directly to the robot over wifi once the web app is installed.

.

We have beta distributions for our PID tuning app available here. Full stable release coming soon.

.

After downloading and installing our robot tuning GUI, you will see a blank screen when you open it.

From here, paste the http address from your MotorGo's serial output into the "Enter server IP address" field. This will connect your computer to your MotorGo over your wifi router.

The 4 controllers in this example are all configured in the balance_bot code. You can name and configure custom PID controllers in your sketch, and then tune them in real-time through this interface.

.

Some notes on this interface:

1. This is a beta distribution and works well for basic projects
2. "Pull Parameters" pulls the stored value for a controller from the MotorGo. Defaults are 0, but you can write different controller defaults into your code.
3. "Push Parameters" sends the current values in a given controller on the GUI to the MotorGo board and updates it.
4. "Enable Motors" enables both channels simultaneously. Make sure the robot is safely positioned before you enable motors.
5. "Disable Motors" disables both channels simultaneously.
6. The graph in the upper right is a work in progress, but we are aiming to soon release an impulse response test to evaluate your controllers in real time.

For the balance bot in particular:

• The velocity controller acts like a damper to stop drift from inaccurate balance point and vibration from too much balance gain
• The balancing controller tries to control the measured pitch to equal the balance point target pitch.
• The steering controller tries to make sure the position difference between the wheels is 0 (every time you push parameters, the steering difference resets to 0).
• The balance point controller is not a PID controller at all, but the balance bot code reads this controller and sets the balance point target pitch equal to "P".

If you want to figure out the right PID parameters yourself, have fun!! Defaults we use are way down in the bottom.

.

Wrapping up

Nicely done! We hope this tutorial was fun and interesting. The robot will work much better on carpet than hard floors/tables for now, because choosing the perfect balance point is tough with a USB-C power cable.

.

We are planning to release a new controller architecture for this robot soon. This will be a full state controller, so the overall performance will be much better than the current version. You will see this in the Arduino examples as "balance_bot_upgrade" or something similar.

.

Remember, this entire project is open source. 

1. If you break parts, you can download and re-print them for free on our Printables. 
2. If you run into trouble and need help, we are most responsive on Discord. 
3. We need your help! Feedback, new ideas, code updates, getting the word out. If you find this project cool or exciting, we would love for you to join our community and help make things better. This is just a start. The MotorGo is enabling us to build tons of new robots quickly, and we look forward to seeing what you come up with too!

Thanks, and until next time!

The MotorGo Team

.

.

.

.

.

.

.

.

.

.

.

.

If you wanted the controller defaults,

velocity P = 0.05

balancing P = 5-10

steering P = 0.5 - 1

balance point = -0.1 - 0.1, depending on your IMU. You can use the pitch readout to get close to the right balance point.