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. 2 Content of this Class  Hardware Architecture Overview  The Programming Environment  BRAIN Application Programming Interface (API)  Coding Examples  Simple Program Debugging  BRAIN Support

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

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

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

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

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)

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

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.

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

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)

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.

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

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.

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

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.

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

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.

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

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

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.

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 Gnd Digital Inputs Connector example switch connection

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

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

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.

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

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

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

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

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

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

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; }

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);

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.

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; }

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…

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; }

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.

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

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

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.

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

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

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.

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, …   Official Q&A “BRAIN” Category  Use “Official Q&A” page during contest for “rules specific” questions  Is this legal?

Copyright © 2008 BEST Robotics, Inc. All rights reserved. 46 Online Documentation Online Documentation Public Information  Official Documents  BRAIN Description & Rules  BRAIN Quickstart Docs  Hardware  Software  2008 BRAIN Team Training  BRAIN Software API  Software Download Package

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