1. Really Using Your BRAIN (Advanced Applications)‏
Teacher-Mentor Workshop
July 18-19, 2008
Auburn University

2. Introduction New programmable robot controller (BRAIN)‏
100% roll-out to all hubs in 2008
Current Cost: $100 per BRAIN (includes cables, software, etc)‏
Expected delivery in July time-frame.
Existing tether boxes can be used.
2007 BRAINS can be used.
Functionally equivalent to 2008 BRAINS
Improvements
Low Battery voltage impact enhancement
Tether noise suppression
Additional LED indicators installed

3. Objectives of this Class
Train Team personnel how to:
Setup their computers
Create their own C programs using the BRAIN API library
Compile, link & download user programs using the IAR Workbench programming environment
Explore a few of the capabilities of the BRAIN through some coding examples
Identify support material to be available to the Teams and where the current version may be located.

4. Who should take this Class?
Mentors and Teachers who will “Train the Trainers” in their respective Teams.
Should be limited to the individuals who have experience with the BRAIN from the 2007 game or have other previous experience.
Programming experience is desirable along with a reasonable knowledge of personal computers.
Attendees should have some knowledge of “C”

5. Content of this Class Hardware Architecture Overview
The Programming Environment
BRAIN Application Programming Interface (API)‏
Coding Examples
Simple Program Debugging
BRAIN Support & Feedback

6. Section 1 - Hardware Architecture
BEST Robotics Advanced Instruction Node Advanced BRAIN Training
Section 1 - Hardware Architecture

7. BRAIN Overview Dual 16-bit microcontroller architecture (TI MSP430)‏
Easy program download via USB interface
Electronics protected by removable cover
Replaceable connectors

8. BRAIN 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

9. Block Diagram

10. BRAIN Hardware Connections
G = Ground for digital input and battery power
B = Battery power (passed through fuse)‏

11. Out 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

12. Out 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.

13. BRAIN STEM Self-Test Enabling Mechanism (STEM)‏
Plug-in test fixture providing self-test of BRAIN functions.
Under development for use by hubs.
Out of the box configuration for BRAIN includes a self-test routine to work with STEM.
The STEM is automatically detected by the diagnostic program (loopback to digital input).
Simple wrap-around tests for all inputs/outputs.
Diagnostic output via USB port.

14. Section 2 - Programming Environment
BEST Robotics Advanced Instruction Node Advanced BRAIN Training
Section 2 - Programming Environment

15. 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)‏

16. C 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.

17. IAR 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

18. Pick a location and save; don’t forget to save the workspace too.
Creating a new BRAIN project
Pick a location and save; don’t forget to save the workspace too.

19. (Application Programming Interface)‏
BEST Robotics Advanced Instruction Node Advanced BRAIN Training
Section 3 – BRAIN API
(Application Programming Interface)‏

20. BRAIN API Currently, four groups of functions:
Initialization – set up timers, input/output, etc – single call to initialize everything. First call to make.
Input – read status of digital input channels and transmitter signals. Do this within a loop to provide real-time input
Output – allows LED, motor channels and servo channels to be set. Do this within a loop to provide real- time control
Serial output – allows feedback stream to PC to monitor BRAIN status.

21. Stick Scaling (side view)‏
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., ≠-1 (10-11=65535)‏
Stick Scaling (side view)‏

22. API - Initialization void InitBrain()‏ void InitCpu() void InitRc()
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.

23. API - 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

24. Transmitter Channel Numbers (indices for getRcValue)‏
API – Input (getRCValue)‏
Transmitter Channel Numbers (indices for getRcValue)‏
(0)‏
(1)‏
(2)‏
(3)‏
Deadband

25. Non-linear input scaling
unsigned short parabolic_scale(unsigned short inval, unsigned short gainval)‏
This allows increased stick sensitivity at low speed while still providing full speed.

26. API - Input int getSwitch(unsigned char sw)
returns 0 or 1 indicating input contact is open or grounded, respectively.
sw is between 0 and 7
+Bat 1 2 3 4 5 6 7 8
Gnd
Digital Inputs Connector
example switch connection

27. Not really an input function, but…
unsigned int getClock(unsigned int offset)‏
returns clock ticks relative to offset, each tick is seconds (50 hz)‏
wraps around after 65535*0.02/60 min=21.8 min
allows time stamping and time-based controls

28. API - Output int setServo(short channel, short value)
sets the servo position for the specified channel
channel: between 0 and 5 value: 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 3 value: between 0 and 1024, 512 is idle, 0 is full reverse, 1024 is full forward

29. API - Output void setAutoLED(unsigned char flag) LEDON & LEDOFF macros
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.

30. API - 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 (
can be used to monitor and capture the output.
A custom solution that will be easier to use is being developed.

31. Section 4 – Coding Examples
BEST Robotics Advanced Instruction Node Advanced BRAIN Training
Section 4 – Coding Examples

32. BRAIN Program Structure
Example API Calls
Initialize
InitBrain
Get Input Values
getSwitch
getRcValue
Repeat
Manipulate Values
Set Outputs
setMotor
set Servo

33. Example 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

34. Example 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

35. Channel 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

36. Channel 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;

37. Example code using the drive remapping 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);

38. Discrete 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.

39. Motor limit switch example
for (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; }

40. Digital 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… ☺

41. Digital 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
case 2:
setServo(5,RCIDLEVAL/2); // half negative rotation
case 3:
setServo(5,RCIDLEVAL); // back to idle }

42. We Encourage Development…
We encourage development/sharing of new functions via the BRAIN message boards.
We encourage hub development of tools for BRAIN.

43. Section 5 – Program Debugging
BEST Robotics Advanced Instruction Node Advanced BRAIN Training
Section 5 – Program Debugging

44. Debug 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 buf 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

45. Monitor the output - RealTerm
Select the port and initialize the settings.
Clear DTR before opening the port, otherwise BRAIN user processor will freeze.

46. RealTerm 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).

47. Section 6 – BRAIN Support & Feedback
BEST Robotics Advanced Instruction Node Advanced BRAIN Training
Section 6 – BRAIN Support & Feedback

48. Basic 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.

49. Where to find help? Online documentation (BRI Site)‏
Public Message Board (for anyone)‏
Must register for login account
Share ideas, resolve issues, …
Private Message Board (for hub personnel only)‏
Must register separate login account from BRI account
Must request access
Official Q&A “BRAIN” Category
Use “Official Q&A” page during contest for “rules specific” questions
Is this legal?

50. Online Documentation Public Information
Official Documents
BRAIN Description & Rules
BRAIN Quickstart Docs
Hardware
Software
2008 BRAIN Tutorial
BRAIN Software API
Software Download Package

51. BRAIN Feedback… Online survey to be made available For hubs or teams
Provide feedback on use or operation of BRAIN
Not mandatory, a mechanism for improvements
Weblink to be announced later and posted on BRI site

52. BEST Robotics Advanced Instruction Node Advanced BRAIN Training
THANK YOU!