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

2. Copyright © 2008 BEST Robotics, Inc. All rights reserved. 2 Content of this Class  Hardware Architecture Overview  The Programming Environment  BRAIN Application Programming Interface (API)  Coding Examples  Simple Program Debugging  BRAIN Support

3. Copyright © 2008 BEST Robotics, Inc. All rights reserved. 3 BEST Robotics Advanced Instruction Node Advanced BRAIN Training Section 1 - Hardware Architecture

4. Copyright © 2008 BEST Robotics, Inc. All rights reserved. 4 BRAIN Overview  Electronics protected by removable cover  Replaceable connectors  Dual 16-bit microcontroller architecture (TI MSP430)  Easy program download via USB interface

5. Copyright © 2008 BEST Robotics, Inc. All rights reserved. 5 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

6. Copyright © 2008 BEST Robotics, Inc. All rights reserved. 6 Block Diagram

7. Copyright © 2008 BEST Robotics, Inc. All rights reserved. 7 BRAIN Hardware Connections G = Ground for digital input and battery power B = Battery power (passed through fuse)

8. Copyright © 2008 BEST Robotics, Inc. All rights reserved. 8 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 1Servo 1Motor 1Digital 1Digital 2 Channel 2Servo 2Motor 2Digital 3Digital 4 Channel 3Servo 3, 5Motor 3Digital 5Digital 6 Channel 4Servo 4, 6Motor 4Digital 7Digital 8

9. Copyright © 2008 BEST Robotics, Inc. All rights reserved. 9 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.

10. Copyright © 2008 BEST Robotics, Inc. All rights reserved. 10 BEST Robotics Advanced Instruction Node Advanced BRAIN Training Section 2 - Programming Environment

11. Copyright © 2008 BEST Robotics, Inc. All rights reserved. 11 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)

12. Copyright © 2008 BEST Robotics, Inc. All rights reserved. 12 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.

13. Copyright © 2008 BEST Robotics, Inc. All rights reserved. 13 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

14. Copyright © 2008 BEST Robotics, Inc. All rights reserved. 14 Creating a new BRAIN project Pick a location and save; don’t forget to save the workspace too.

15. Copyright © 2008 BEST Robotics, Inc. All rights reserved. 15 BEST Robotics Advanced Instruction Node Advanced BRAIN Training Section 3 – BRAIN API (Application Programming Interface)

16. Copyright © 2008 BEST Robotics, Inc. All rights reserved. 16 BRAIN 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.

17. Copyright © 2008 BEST Robotics, Inc. All rights reserved. 17 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) Stick Scaling (side view)

18. Copyright © 2008 BEST Robotics, Inc. All rights reserved. 18 API - 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.

19. Copyright © 2008 BEST Robotics, Inc. All rights reserved. 19 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

20. Copyright © 2008 BEST Robotics, Inc. All rights reserved. 20 API – Input (getRCValue) Transmitter Channel Numbers (indices for getRcValue) (0) (1)(2) (3) Deadband

21. Copyright © 2008 BEST Robotics, Inc. All rights reserved. 21 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.

22. Copyright © 2008 BEST Robotics, Inc. All rights reserved. 22 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 12345678 Gnd Digital Inputs Connector example switch connection 12345670

23. Copyright © 2008 BEST Robotics, Inc. All rights reserved. 23 Not really an input function, 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

24. Copyright © 2008 BEST Robotics, Inc. All rights reserved. 24 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

25. Copyright © 2008 BEST Robotics, Inc. All rights reserved. 25 API - 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.

26. Copyright © 2008 BEST Robotics, Inc. All rights reserved. 26 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 (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.

27. Copyright © 2008 BEST Robotics, Inc. All rights reserved. 27 BEST Robotics Advanced Instruction Node Advanced BRAIN Training Section 4 – Coding Examples

28. Copyright © 2008 BEST Robotics, Inc. All rights reserved. 28 BRAIN Program Structure Initialize Get Input Values Manipulate Values Set Outputs Repeat Example API Calls getSwitch getRcValue setMotor set Servo InitBrain

29. Copyright © 2008 BEST Robotics, Inc. All rights reserved. 29 Example program using API // header and initialization #include // include msp430 defs #include // include best api info int main( void ) { short chan; short inval; InitBrain(); // initialize the system

30. Copyright © 2008 BEST Robotics, Inc. All rights reserved. 30 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

31. Copyright © 2008 BEST Robotics, Inc. All rights reserved. 31 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

32. Copyright © 2008 BEST Robotics, Inc. All rights reserved. 32 Channel Mixing Function #include 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; }

33. Copyright © 2008 BEST Robotics, Inc. All rights reserved. 33 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,&left Motor); // now set the output motor values setMotor(0,rightMotor); setMotor(1,leftMotor);

34. Copyright © 2008 BEST Robotics, Inc. All rights reserved. 34 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.

35. Copyright © 2008 BEST Robotics, Inc. All rights reserved. 35 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; }

36. Copyright © 2008 BEST Robotics, Inc. All rights reserved. 36 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…

37. Copyright © 2008 BEST Robotics, Inc. All rights reserved. 37 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 break; case 2: setServo(5,RCIDLEVAL/2); // half negative rotation break; case 3: setServo(5,RCIDLEVAL); // back to idle break; }

38. Copyright © 2008 BEST Robotics, Inc. All rights reserved. 38 We Encourage Development…  We encourage development/sharing of new functions via the BRAIN message boards.  We encourage hub development of tools for BRAIN.

39. Copyright © 2008 BEST Robotics, Inc. All rights reserved. 39 BEST Robotics Advanced Instruction Node Advanced BRAIN Training Section 5 – Program Debugging

40. Copyright © 2008 BEST Robotics, Inc. All rights reserved. 40 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 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

41. Copyright © 2008 BEST Robotics, Inc. All rights reserved. 41 Monitor the output - RealTerm Select the port and initialize the settings. Clear DTR before opening the port, otherwise BRAIN user processor will freeze.

42. Copyright © 2008 BEST Robotics, Inc. All rights reserved. 42 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).

43. Copyright © 2008 BEST Robotics, Inc. All rights reserved. 43 BEST Robotics Advanced Instruction Node Advanced BRAIN Training Section 6 – BRAIN Support

44. Copyright © 2008 BEST Robotics, Inc. All rights reserved. 44 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.

45. Copyright © 2008 BEST Robotics, Inc. All rights reserved. 45 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?

46. Copyright © 2008 BEST Robotics, Inc. All rights reserved. 46 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

47. Copyright © 2008 BEST Robotics, Inc. All rights reserved. 47 BEST Robotics Advanced Instruction Node Advanced BRAIN Training THANK YOU!