Copyright © 2008 BEST Robotics, Inc. All rights reserved. 1 BEST Robotics Advanced Instruction Node Team Training Really Using Your BRAIN (Advanced Applications)

Copyright © 2008 BEST Robotics, Inc. All rights reserved. 1

BBEST EST RRobotics obotics AAdvanced dvanced IInstruction nstruction NNodeode

Team TrainingTeam Training

Really Using Your BRAIN

(Advanced Applications)


Content of this ClassContent of this Class Hardware Architecture Overview The Programming Environment BRAIN Application Programming Interface (API) Coding Examples Simple Program Debugging BRAIN Support



Advanced BRAIN TrainingAdvanced BRAIN Training

Section 1 - Hardware Architecture


BRAIN OverviewBRAIN Overview

Electronics protected by removable cover

Replaceable connectors

Dual 16-bit microcontroller architecture (TI MSP430)

Easy program download via USB interface


BRAIN FeaturesBRAIN Features Interface with standard Futaba radio

PWM input from receiver Dedicated “trainer” cable interface for tethered

operation 4 proportional motor control outputs 6 servo motor outputs 8 discrete digital inputs USB port for program download Onboard power switch and replaceable fuse Powered by a single 7.2 volt RC hobby

battery


Block DiagramBlock Diagram

CONTROLMSP430F149

USERMSP430F149

POWERREGULATION

USB TO

RS232

BATTERY POWER

3.3V

BATTERYINPUT

7.2V

5V R/C & SERVO

SERIALCOMM.

H-BRIDGECONTROL

J TAG J TAG

SERVO OUT

USBPORT

RADIOINPUT (6)

DIGITALINPUT (8)

9.6V TRANSMITTER

BSL

SPI

1

1

2

3

4

23456

GPIO

GPIO TIMER B

TIMER B& A1


BRAIN Hardware ConnectionsBRAIN Hardware Connections

G = Ground for digital input and battery powerB = Battery power (passed through fuse)


Out of the Box ConfigurationOut of the Box Configuration All channels active as both servo output and

proportional speed control motor output.

Motor Limits

Transmitter

Channel

Servo Output

Motor Output

Positive Direction

Negative Direction

Channel 1 Servo 1 Motor 1 Digital 1 Digital 2

Channel 2 Servo 2 Motor 2 Digital 3 Digital 4

Channel 3 Servo 3, 5 Motor 3 Digital 5 Digital 6

Channel 4 Servo 4, 6 Motor 4 Digital 7 Digital 8


Out of the Box ConfigurationOut of the Box Configuration

Allows a team to hook up the BRAIN any way they wish and have it work without ever having to program the BRAIN.

Referred to as the “default” project – described later. This is NOT the only configuration for the BRAIN! Good for initial checkout, but we want teams to load a

unique configuration.




Section 2 - Programming Environment


What’s Included?What’s Included?

BRAIN Support Software includes: IAR Workbench – A FREE C-programming environment for

MSP430 Wizard, Libraries, USB drivers & download utilities All software installed to PC via BRAIN installer program Configures IAR Workbench for use with the BRAIN

Create programs via the BRAIN Wizard Create your own user programs using BRAIN

Applications Programming Interface (API)


C Programming Environment OptionsC Programming Environment Options

IAR Workbench – Kickstart Edition Loaded via BRAIN installer BEST will only support this environment Code size limitation of 4K bytes

user program + BRAIN libraries

Code Composer Essentials (CCE) Free MSP430 programming environment from TI 8K byte code size limit

GNU C++ Compiler (GCC) suitable for the MSP430 No IDE; use “make” to automate. Not “student friendly.”

BEST may support CCE or GCC in the future.


IAR WorkbenchIAR Workbench

Start by creating a “BRAIN Project” Automatically includes the BRAIN API library, include paths

and other needed settings. Creates a functioning program that can be used as a

framework for code customization.

Modify the framework C program using functions in the BRAIN API library or functions that you create.

Compile, link and download using menu system within the IAR Workbench Make or Rebuild All Bootload via USB


Creating a new BRAIN projectCreating a new BRAIN projectPick a location and save; don’t forget to save the workspace too.




Section 3 – BRAIN API

(Application Programming Interface)


BRAIN APIBRAIN API

Currently, four groups of functions:1. Initialization – set up timers, input/output, etc –

single call to initialize everything. First call to make.

2. Input – read status of digital input channels and transmitter signals. Do this within a loop to provide real-time input

3. Output – allows LED, motor channels and servo channels to be set. Do this within a loop to provide real-time control

4. Serial output – allows feedback stream to PC to monitor BRAIN status.


Details …Details … Not many during this short class. The BRAIN Software document has details on the API,

software installation and solving some common problems.

Important items: Indexing starts at 0, i.e., the first channel

is channel 0 Integer math is purposely used in the

library routines for size and speed reasons, so order of operations can be important.

Be careful of wrap around with unsigned integers, e.g., 10-11 ≠-1 (10-11=65535)

0512

1024

IDLE

FULLREV

FULLFWD

Stick Scaling(side view)


API - InitializationAPI - Initialization void InitBrain()

provides a one-call initialization of the system by calling InitCpu(), then calling InitRc(), and finally enabling interrupts.

This should be the first step in every BRAIN program. void InitCpu()

initializes the state of the MSP430 controller sets up various timers and interrupts. Call prior to InitRc(). Not normally called directly from the

user program. void InitRc()

initializes the state of the inputs used to capture the radio control signals from the receiver and tether system.

Call after InitCpu(). Not normally called directly from the user program.


API - InputAPI - Input short getRcValue(short chan, unsigned short deadband, unsigned short gainval)

returns input values between 0 and 1024 from either tether or RC.

chan: 0 to 3

deadband: differential value from IDLE (center position) that must be exceeded to generate a value other than IDLE.

gainval: scales output according to:output=IDLE+(inputvalue-IDLE)*gainval/100


API – Input (getRCValue)API – Input (getRCValue)

Transmitter Channel Numbers(indices for getRcValue)

(0)

(1)(2)

(3)

0512

1024

IDLE

FULLREV

FULLFWD

Deadband


Non-linear input scalingNon-linear input scaling unsigned short parabolic_scale(unsigned short inval, unsigned short gainval)

0

128

256

384

512

640

768

896

1024

0 128 256 384 512 640 768 896 1024

Input Value

Ou

tpu

t V

alu

e

Gain=110

Gain=100

This allows increased stick sensitivity at low speed while still providing full speed.

22 Copyright © 2008 BEST Robotics, Inc. All rights reserved.

API - InputAPI - Input int getSwitch(unsigned char sw)

returns 0 or 1 indicating input contact is open or grounded, respectively.

sw is between 0 and 7

+B

at1 2 3 4 5 6 7 8

Gn

d

Digital Inputs Connector

example switch connection

1 2 3 4 5 6 70


Not really an input function, Not really an input function, but…but… unsigned int getClock(unsigned int offset)

returns clock ticks relative to offset, each tick is 0.02 seconds (50 hz)

wraps around after 65535*0.02/60 min=21.8 min

allows time stamping and time-based controls


API - OutputAPI - Output int setServo(short channel, short value)

sets the servo position for the specified channel

channel: between 0 and 5value: between 0 and 1024, 512 is the center position

int setMotor(short channel, short value)

sets the motor speed for the specified channel

channel: between 0 and 3value: between 0 and 1024, 512 is idle, 0 is full reverse, 1024 is full forward


API - OutputAPI - Output void setAutoLED(unsigned char flag)

set flag to 1 to enable diagnostic LED functions for D42.

Set flag to 0 allow user LED macros (below) to work.

LEDON & LEDOFF macros

Turn user LED D42 on or off.

New functions or macros will be available for the LEDs added to the 2008 BRAIN hardware.


API - Serial OutputAPI - Serial Output void outHostsz(char* pch)

sends the null terminated string at pch out the BRAIN USB port. Communications settings for the port are 9600 baud, No Parity, 8 data bits, 1 stop bit.

String utilities: itoa, utoa, strcat, strlen Part of the BRAIN API to help with formatting output – convert

numbers to strings and provide concatenation.

Other utility functions are being developed.

RealTerm (http://realterm.sourceforge.net) can be used to monitor and capture the output. A custom solution that will be easier to use is being developed.




Section 4 – Coding Examples

28 Copyright © 2008 BEST Robotics, Inc. All rights reserved.

BRAIN Program StructureBRAIN Program Structure

Initialize

Get Input Values

Manipulate Values

Set Outputs

Re

pea

t

Example API Calls

getSwitchgetRcValue

setMotorset Servo

InitBrain


Example program using APIExample program using API

// header and initialization#include <msp430x14x.h> // include msp430 defs#include <bestapi.h> // include best api info

int main( void ){ short chan; short inval;

InitBrain(); // initialize the system


Example program - continuedExample program - continued// main program loop – very simple while(1) // loop forever { // iterate over all the channels – retrieve input, create output for (chan=0;chan!=4;chan++) { inval=getRcValue(chan,8,100); // no gain, ok deadband

// insert other processing with the input values setServo(chan,inval); // set the servo position setMotor(chan,inval); // set the motor speed } // for loop } // while loop} // end of program


Channel Mixing ExampleChannel Mixing Example

Many machines are set up with two drive motors that provide both forward and reverse motion as well as steering.

Question: How can I set up my robot so that forward on the stick makes the robot move forward?

Answer: Use the BRAIN to mix two input channels to drive the two motors


Channel Mixing FunctionChannel Mixing Function#include <bestapi.h>void remapDrive(unsigned int steerValue, unsigned int speedValue,

unsigned int *rightMotor, unsigned int *leftMotor) {int xInput, yInput; // declare some signed integers int rightValue,leftValue; // grab the input values and make into delta xInput=steerValue-RCIDLEVAL; yInput=speedValue-RCIDLEVAL;// combine the input to create output delta values leftValue=yInput+xInput; rightValue=yInput-xInput; // bound the delta values (remember RCIDLEVAL is half RCMAXVAL) if (leftValue>RCIDLEVAL) leftValue=RCIDLEVAL; // becomes RCMAXVAL if (leftValue<-RCIDLEVAL) leftValue=-RCIDLEVAL; // becomes zero if (rightValue>RCIDLEVAL) rightValue=RCIDLEVAL; if (rightValue<-RCIDLEVAL) rightValue=-RCIDLEVAL; // output the values and include the idle offset *leftMotor=leftValue+RCIDLEVAL; *rightMotor=rightValue+RCIDLEVAL; }


Example code using the drive Example code using the drive remapping functionremapping function From within a loop, add the following code snippet:

// get input values – do some scaling too

steerValue=getRcValue(1,DEADBAND,125);

speedValue=getRcValue(0,DEADBAND,125);

// call the remap routine remapDrive(steerValue,speedValue,&rightMotor,&leftMotor);

// now set the output motor values

setMotor(0,rightMotor);

setMotor(1,leftMotor);


Discrete InputDiscrete Input Wire a normally open switch between input 1 and

ground. Use getSwitch to read the status; when the switch is

closed, the function will return 1.


Motor limit switch exampleMotor limit switch examplefor (chan=0;chan!=4;chan++)

{

inval=getRcValue(chan,DEADBAND,gain[chan]);

// check the limit switches and set the speed to idle when switched

if ((inval>RCIDLEVAL&&getSwitch(chan*2))||

(inval<RCIDLEVAL&&getSwitch(chan*2+1)))

{

inval=RCIDLEVAL;

}

}


Digital Input ExampleDigital Input Example Objective:

Cycle a servo-based gripper through a variety of positions each time the machine bumps into part of the field.

Solution:

Use a switch to sense the contact and a “state-machine” to track the servo/gripper position.

Note: a custom function designed to de-bounce the switch action was used in the code that follows. The development of that code is left as a student exercise…


Digital input – state machineDigital input – state machine// toggle the servo position based on the switch inval=getSwitch(0); // read digital input 1 (0 based numbering) if (switchpressed(inval,swstate)) // this is a non-API debounce function { sp++; //sp is the state variable sp%=4; // make it wrap around at 4 switch (sp) { case 0: setServo(5,RCMAXVAL); // full positive rotation break; case 1: setServo(5,RCIDLEVAL); // back to idle break; case 2: setServo(5,RCIDLEVAL/2); // half negative rotation break; case 3: setServo(5,RCIDLEVAL); // back to idle break; } }


We Encourage Development…We Encourage Development…

We encourage development/sharing of new functions via the BRAIN message boards.

We encourage hub development of tools for BRAIN.




Section 5 – Program Debugging


Debug output exampleDebug output example// define DEB to enable the debug output#ifdef DEB itoa(sp,outbuf); // convert sp to a string; outbuf strcat(outbuf," X "); // add a separator to outbuf itoa(inval,buf1); // convert inval to temporary string buf1

strcat(outbuf,buf1); // combine buf1 with outbuf for (ii=0;ii<2;ii++) // start a loop { strcat(outbuf," ST "); // add a separator to outbuf itoa(swstate[ii],buf1); // convert the array element to a string strcat(outbuf,buf1); // combine string with the outbuf } strcat(outbuf," END\r\n"); // add some termination to the buffer outHostsz(outbuf); // send it out the serial port#endif


Monitor the output - RealTermMonitor the output - RealTerm

Select the port and initialize the settings.

Clear DTR before opening the port, otherwise BRAIN user processor will freeze.


RealTerm tipsRealTerm tips Identifying the correct port can be troublesome;

different BRAINs will map to different port numbers. The initialization sequence is critical. RealTerm can also capture the output and write it to

a file. Captured data can be easily imported into Excel and

analyzed – assuming it’s written with acceptable separators (commas or tabs are good choices).




Section 6 – BRAIN Support


Basic SupportBasic Support Diagnostic LEDs (D41/D42) indicate status:

D41 – Control Processor; D42 – User Processor Slow blink (once per second) – normal operation Fast blink (five times per second) – absence of tether/receiver

signal, or absence of communication between processors. Solid on/off – something is hung up, cycle power first then

reprogram if power cycle doesn’t solve. Low Battery LED

Located near the battery connecter/ power switch. LED OFF indicates battery needs charging.

Internal fuse/breaker, self-resets with a few seconds. LED OFF by receiver indicates there is a short (5V) Find and fix the short.

Interference when using tether may require addition of ferrite to the cable.


Where to find help?Where to find help?

Online documentation (BRI Site) Public Message Board (for anyone)

Must register for Yahoo login account Share ideas, resolve issues, … http://tech.groups.yahoo.com/group/bestinc/

Official Q&A “BRAIN” Category Use “Official Q&A” page during contest for “rules

specific” questions Is this legal?


Online Documentation Online Documentation Public Information

http://www.bestinc.org - 2008 Official Documents BRAIN Description & Rules BRAIN Quickstart Docs

Hardware Software

2008 BRAIN Team Training BRAIN Software API Software Download Package




THANK YOU!