Working with the BrainStem micro-controller

Both projects in this course will be based on the BrainStem micro-controller by Acroname. This document will describe how to get the BrainStem up and running.

Parts

The parts that I'll supply for the SumoBot project, most of which you'll need for both projects, are as follows:

Powering the BrainStem

The BrainStem has separate power inputs for the micro-controller's logic and the servos. There are a number of good reasons for this arrangement, as described in this article. You'll use the 9V battery for logic, and the 4 AA batteries for the servos.

In the picture of the BrainStem below, the two pins on the bottom right of the board are for logic power. The lower of the two pins is ground (negative, typically the black wire from the battery). The upper of the two pins is power (positive, typically the red wire from the battery). It is crucial that you get power and ground to the right pins. Otherwise, you may irreparably damage the board. The two pins on the upper right side of the board are for servo power. Note which one is labeled ground.

The connectors on either end of the power cable will fit on either of the sets of power pins. Cut the two wires of the power cable midway between the connectors. Strip about one half inch of insulation off the ends of the wires that you just cut (four in all). For one of the connector, twist the bare part of the red wire with the bare part of the red wire on the 6V battery pack. Do the same with the black wires. Now cover the exposed bare wire with electrical tape. Turn the switch on the battery pack off and put batteries into the battery pack. Slide the connector onto the servo power pins ensuring that the black wire is on the pin labeled GND.

Repeat this process with the other half of the power cable and the 9V battery connector. However, rather than attaching the red wires directly to each other, attach them to the two contacts on the rocker switch. This may require soldering to get a good connection. Ask me if you want help with this (e.g., you don't have a soldering iron). It'll only take a minute. You'll also probably want to use electrical tape to ensure that the wires don't make contact with each other if they get bent. Turn the switch to the off position, snap in a 9V battery, and slide the connector onto the logic power pins ensuring that the black wire is on the pin labeled GND.

Once you get the BrainStem powered the right way, use the power switches. Don't remove the power cable connectors. That will prevent polarity errors that can lead to burned out boards, servos, and professors. If you turn on the 9V switch the red LED on the board should glow continuously. The green LED will flicker and go out.

Communicating with the BrainStem

You'll need to connect the BrainStem to a computer so that you can, among other things, download programs to control your SumoBot. The software for doing this (which will be described in a moment) expects your machine to have a serial port. If your machine does have a serial port, then you'll need the Acroname serial interface connector.

Plug the connector into the 4 pins labeled SERIAL just below the servo power pins on the board. Then connect the board to your machine with a serial cable.

If you don't have a serial port on your machine, which is probably the case, you'll need the Acroname USB serial interface connector.

Plug the connector into the SERIAL pins on the board, and connect the board to your machine with a USB cable. However, the software that communicates with the board still expects a serial port, so you'll need to download drivers from the Acroname web site that make the USB port look like a serial port. There are drivers for Windows and Power PC Macs.

If you don't have a serial port and you don't have either a Windows or PPC Mac machine, you'll need to use the Acroname serial interface controller and buy a third party USB-to-serial converter with a driver for your machine. That's what I did (I have an Intel Mac). I bought one made by Keyspan that has drivers for lots of different machines.

Downloading Software for the BrainStem

Go to the Acroname web site and click on the downloads link. Enter your name and email address and click login. You don't need to have an existing account. Then click the "Software Downloads" button.

First, get the BrainStem Reference, which will make a local copy of the HTML documentation for the BrainStem. It's small, and might be nice to have on your machine in cases when you don't have easy internet access (have you ever wanted to read micro-controller docs on your laptop while riding the DC metro?). Browse this for a while to see what's there.

Now get the BrainStem GP 1.0 utilities and demo application. After you unzip, untar, and un-whatever else is required, you'll have a folder named GP. Inside is a readme file you should read. Now navigate to GP/brainstem/aBinary where you'll find the GP binary, a readme, and maybe some installation instructions. Read these last two files and do what they say.

The only thing left to do is create a file named gp.config in the aBinary directory with the following line: 

portname = YOUR_PORT_NAME
Replace YOUR_PORT_NAME with the name of the serial port on which you'll be communicating. On a Windows machine, this may be: 
portname = COM1
On my Mac, the Keyspan driver creates a entry in /dev named tty.USA19H1d1P1.1, so my gp.config says: 
portname = tty.USA19H1d1P1.1
You'll know when you get the config file right because when you do the GP application will not say "Serial Port Not Found" when you run it. So, try running the GP application. Ensure that the serial/USB cable and the power cables are connected. Turn on the 9V battery switch. Then run the GP application. The greed LED should start to pulse when the application runs, this is the "heartbeat", and there will be a heartbeat in the application window.

Testing the servos

Now that the GP application is communicating with the BrainStem, let's test out the servos. Find the 4 sets of 3 pins labeled SERVO on the board. Note that the set of pins on one end is labeled 0, and the set at the other end is labeled 3. Plug one of the servos into one of the sets of three pins. The black servo wire should be closest to the board, with the red wire on the middle pin and the white wire on top. See the picture below:

Turn on both power supplies, run the GP application, and click on the Servo tab. Move the slider associated with the servo (0 - 3) you plugged in and it should rotate. More details on the GP 1.0 application can be found here.

Writing Programs for the BrainStem

Now download the BrainStem Console for your hardware platform. Doing so creates a directory named console with exactly the same structure as the GP tree. Copy gp.config to console.config in the console's aBinary directory. Then run the Console application. The response (various blinking lights) should be the same as when running the GP application.

Rather than having the same directory structure in the GP and console directories, I merged them together as follows. I downloaded GP and console to my Desktop, and then moved to the location where I wanted to put the BrainStem software. Then I did the following: 

  mkdir brainstem
  cd brainstem
  cp -r ~/Desktop/GP/brainstem/ .
  cp -r ~/Desktop/console/brainstem/ .
  ls aBinary
The last command should show executables for GP and console in the aBinary directory. Then I removed the GP and console directory trees from my Desktop. Be sure to put gp.config and console.config files in the aBinary directory as described above.

You'll want to look at a few different resources before you get started writing code. They include:

Write your code with a text editor, give it a .tea extension, and put the file in the aUser subdirectory of the brainstem directory. Below is an example TEA program I wrote that might be useful for a SumoBot gait. 

/* An example SumoBot gait written in TEA
 *
 * Servo 0 lifts the SumoBot so the wheels can swing free
 * Servos 1 and 2 are attached to wheels
 * The gait goes like this:
 *   - Lift the SumoBot so the wheels can swing free
 *   - Rotate the wheels back
 *   - Lower the SumoBot
 *   - Rotate the wheels forward while in contact with ground plane
 *   - Repeat
 *
 */


#define NUM_STEPS 5   /* The number of steps the robot should take */
#define SECOND 10000  /* One second delay when passed to aCore_Sleep */

#include < aCore.tea >
#include < aServo.tea >


void main() {

  int i;

  /* Ensure servos have full range of motion */
  aServo_SetLimits(0, 0x0046);
  aServo_SetLimits(1, 0x0046);
  aServo_SetLimits(2, 0x0046);

  /* Mandatory 3 second delay */
  aCore_Sleep(3*SECOND);

  for (i = 0; i < NUM_STEPS; i++) {

    /* Lift the SumoBot and wait for servo to move.  Note cast on second
     * parameter, which is the position (0 - 255).  The compiler compains
     * if the case is not there.
     */
    aServo_SetAbsolute(0, (unsigned char)128);  
    aCore_Sleep(SECOND);

    /*Rotate the wheels back and wait for servos to move */
    aServo_SetAbsolute(1, (unsigned char)0);  
    aServo_SetAbsolute(2, (unsigned char)0);
    aCore_Sleep(SECOND);

    /* Lower the SumoBot and wait for servo to move */
    aServo_SetAbsolute(0, (unsigned char)0);
    aCore_Sleep(SECOND);

    /*Rotate the wheels forward and wait for servos to move */
    aServo_SetAbsolute(1, (unsigned char)255);
    aServo_SetAbsolute(2, (unsigned char)255);
    aCore_Sleep(SECOND);
  }

}
Note that because I make calls that start with aServo I include aServo.tea, and likewise with aCore.tea.

With this file in the aUser directory, run the console application. It'll look something like this:

On my machine I have to resize the console window to make the text in it show up. Now, to compile the Gait program, run the steep compiler in the console as shown below:

After steep has run, the window will look something like this:

Though the details may vary, such as the number of bytes, depending on which version of my code I compiled when I made the screen shot. There should now be a file named Gait.cup in aObject. The next step is to load the object file onto the BrainStem. To do that you need to know about modules and slots.

Your BrainStem GP 1.0 is a module. Acroname makes other modules, and multiple modules can be chained together and can communicate with one another and the console application. You have to tell the console the number of the module you want to load the program onto. For reasons that are unclear to me, your single GP 1.0 module is probably number 2.

Each module has number of program slots. The GP 1.0 module has 11 slots numbered 0 through 10. To download the Gait program to slot 0 on the BrainStem you issue this command in the console: 

load "Gait" 2 0
That is, "load" the program named "Gait" into slot "0" of module "2". Finally, to run the program in slot 0 you issue this command in the console: 
launch 2 0
Note that when you load a program onto the BrainStem it resides in the module's EEPROM. If you turn the unit off, turn it back on, and just issue the launch command above, the Gait program will begin running.

The last thing to note is that when the control code for your SumoBot is fully debugged, you will probably want it to run when you switch on the BrainStem. See this article for information on how to make TEA programs run in this manner.

Note that it is possible to do a hardware reset of the BrainStem. Sometimes micro-controllers get confused, either due to bugs or erroneous commands sent to them. If your BrainStem starts to act "weird", try a hardware reset.