Running your Omniwheel Bot

Getting Started

We'll be running the bot using the Virtual Wiring system, so download and install Virtual Wiring on a suitable host, if you haven't already. If you have one available, we recommend starting with a PC Linux or Apple OS X based host. These hosts have the best response times and will speed up your testing. Later, once you have everything running, you can use slower, smaller hosts (Raspberry Pis, etc.).

Once you have Virtual Wiring running on your host system, you can plug in the USB cables for controlling your bot and your joystick Arduinos. Initially, to keep things simple, we will not use wireless control. Instead, we'll plug the bot Arduino into your host system directly. Once we've seen the non-wireless version of the system work, we'll replace the bot's USB cable with a wireless connection.

Isolate the Arduino

Before plugging the bot's Arduino into your host system, we are going to take a small precaution. We are going to isolate the motor power supply (the batteries) from the Arduino power supply. On your motor shield, there is a jumper which connects the Arduino's power supply to the battery. Normally, we want the battery to power the Arduino, but for our test system, we will power our Arduino over USB. Remove the power jumper on your Motor shield (the VIN jumper on the Adafruit Shield, the EXT jumper on the Wicked Device Shield). Leave it off until we tell you to put it back on.

Discover the USB Port Names

Plug your bot's Arduino into a free USB port on your host. From a command line on your host type: ls -lrt /dev. This command will list all the devices on your host, most recently added devices last. Since you just plugged in your Arduino, it should be listed on your screen (or you may have to scroll a little bit back in your screen). Typical Arduino USB port names are "/dev/ttyUSB0", "/dev/ttyACM0", and "/dev/cu.usbmodem1411". If you don't see something that looks like one of these names, try unplugging the Arduino and see what name goes away from the list. Once you know your USB port name, write it down. Leave your bot's Arduino plugged in.

Plug your joystick's Arduino into your host system. Do the same experiment to find out its USB port name. Write that name down and leave the 2nd Arduino plugged in as well. Your hardware is hooked up and ready to go.

Starting Up Your Bot

With your USB device names in hand, you are ready to run your bot. Open a web browser and navigate to your Virtual Wiring system's home page. If you are running your browser on the same host as your Virtual Wiring system with its default settings, the home page will be at "localhost:4567".

On your Virtual Wiring System, navigate to the Scripts page by clicking on "Scripts" at the top of the page. Using the Scripts Page's View Filter, select "projects". With the "projects" View Filter, it narrows the number of scripts we have to look at considerably. Depending on whether you have an Adafruit Shield or a Wicked Device Shield, click the "Run" action for either the "adafruit_startup.script" or the "wickeddevice_startup.script" Script file.

After clicking the Run action, you should see the Run screen for your shield. Here we show the screen for a bot with an Adafruit Shield running on a MacBook.

You will need to substitute your own bot_port and joystick_port values. These are the USB port names you have have just learned. You can leave the other values as they are.

• Before going any further, you may want to pick up your bot and hold it. If all goes well, when you start up your bot, it shouldn't do anything. But hold onto it, just in case.

Click the "Submit" button at the bottom of the screen. Wait a few moments, and you should get an OK message.

While holding your bot (you don't want it to drag off your host), move your joystick around. Your wheels should start spinning.

It's alive!

Possible Errors

If you get an error message, here are some things to try.

• Read the error message for clues
  
• Make sure both your Arduinos are plugged into your host
  
• Try clicking the "Restart" button at the bottom of your Scripts page and then re-running your bot Script
  
• Try resetting your Arduino (using its reset button), clicking the "Restart" button at the bottom of the Scripts page, and rerunning your Script
  
• Check your USB port names to be sure you have typed them in correctly
• Make sure your Arduino's are running Firmata 2.3 or higher

Remember, whenever you make a mistake and want to restart your system, hit the "Restart" button at the bottom of the Scripts page first. Restarting will clear out your system so that it starts fresh.

Tip: if you have already run your Script once and don't feel like going through the run screen each time you rerun the Script, use the Console. The Console lists whatever you've done. Just put your cursor at the end of the line you want to rerun and hit return. If you want to change what you've run a little bit, you can edit the line before rerunning it.

Setting Your Bot Free

We are almost done. All we need to do is replace the USB cable going from your host to your bot with a wireless one. If you've configured your XBees, this is pretty simple.

• Remove the USB cable that runs from your Bot to your host

• Make sure the bot's battery is turned off

• Put back the battery jumper on the motor shield (the VIN or EXT jumper we took off)

• Test your battery power by turning the battery on (your Arduino should turn on)

• Turn your battery power off

• Plug your XBee Shield into your motor shield. If your motor shield doesn't have stackable headers, you are going to have to sandwich the XBee between your Arduino and the motor shield. Note: if you sandwich your XBee between your Arduino and motor shield, your wireless range will suffer.

• Plug your XBee Explorer into your host's USB port

• Do the ls -lrt /dev experiment you did before to learn the Explorer's USB port name

• Turn on your battery

• Run your bot's startup Script substituting the Explorer's USB port as the bot_port

You are wireless!

Put your bot on the floor and let 'er rip!

Problems

Script failed to run?

• Read the error message for clues
  
• Make sure you have Restarted your system before running the startup Script
• Restart your system and rerun your startup Script with the bot and Explorer just a few feet appart (minimize radio interference)
  

No Power

• Check your your battery connections
• Make sure your motor shield's battery jumper is installed

Works, But Occasionally Wanders Off Out of Control

• We've seen this when our batteries get old. Try replacing them.

Further Study

Want to learn more? Your bot is controlled by a Ruby program on your host. You can change the way it functions. To learn more about programming, go to the Programming your Bot section.

Both your bot's Arduino and your joystick's Arduino have a bevy of I/O pins suitable for sensing and control. You can add bot sensors, a second joystick, bot lights, pretty much anything you can think of. Go to the Adding New Hardware section for ideas and suggestions.