Please note as of Wednesday, August 15th, 2018 this wiki has been set to read only. If you are a TI Employee and require Edit ability please contact x0211426 from the company directory.
MSP430 LaunchPad Operator Interface for FIRST Robotics Competition
The TI MSP-EXP430F5529LP (F5529 LaunchPad) is capable of serving as a fully compliant USB device which means it can be used to make custom operator interfaces. Texas Instruments has developed a software example so that it will enumerate as a USB HID gamepad when the application is loaded into the MCU’s flash memory. With this example application, the LaunchPad looks and acts like any generic USB game controller or joystick. Without any special drivers or APIs, the FRC Driver Station is able to utilize the LaunchPad as if it were a game controller. Data from the LaunchPad is accessed by the robot just as any other joystick.
In addition to serving as a normal gamepad, TI has worked with NI to fully utilize the HID protocol, and add indicator outputs from the LaunchPad that are controlled by the Driver Station software. This allows custom driver feedback which could be as simple as a few LED indicators, or special patterns based on robot state.
The gamepad example applications have three different default configurations to enable a variety of potential control schemas. These define the number of digital inputs and indicator outputs: 11/11 inputs and outputs, 16/6 inputs and outputs, or 20/2 inputs and outputs. All three options include an additional eight analog inputs.
Note The Stellaris based LaunchPad introduced in the 2013-2014 season had similar functionality as described. The implementations are very similar, but not compatible. This guide only applies to the F5529 LaunchPad included in the 2015 Kit of Parts.
- 1 Overview
- 2 Getting Started
- 3 Using the Launchpad as an HID GamePad
- 4 Example OI Panels
- 5 Modifying the LaunchPad Firmware
- 6 FAQ & Troubleshooting
This section outlines how to setup your LaunchPad hardware as a gamepad for the first time.
Below is a list of the hardware components needed to get started.
- MSP430F5529 LaunchPad
- Analog and Digital inputs
- See Example OI Panels for ideas
- USB Micro-B to USB-A plug cable
- Included with the Launchpad
The National Instruments website provides two downloads for teams. One contains the LabVIEW development environment, for LabVIEW teams only. The second contains the FRC update, used for all teams and contains all the software needed to download the gamepad firmware including the necessary driver.
After installing the FRC Update you can find the Gamepad Tool by default in the following location: C:\Program Files (x86)\FRC Gamepad Tool\Gamepad Tool.exe. For LabVIEW teams you can also find a link to the tool on the Utilities tab of the LabVIEW Getting Started page.
To load the gamepad firmware, plug the LaunchPad device into a machine that has the FRC update installed and load the “FRC Gamepad Tool” that is packaged with the FRC update. This tool will automatically scan for a connected LaunchPad and display the COM port associated with it.
The FRC Gamepad Tool includes three firmware options. Browse different firmware options to view their properties, and select the one most appropriate for your application. Once you have the correct firmware option selected, click Program Device to program the LaunchPad.
Once you press the Program Device button, you should see the LEDs on the LaunchPad flash. The first time you update the firmware it may take up to two minutes. During this time the FRC Gamepad Tool is updating both the gamepad firmware and the firmware for the debugger chip on board. After that the tool will program the device much more quickly as it only needs to update the main MSP430 chip.
When the tool finishes updating the firmware, Windows will automatically detect the gamepad on your system. Your computer will now show both the gamepad and the COM port used to load the firmware.
The default gamepad firmware includes eight analog inputs, which need to be calibrated before use. Input calibration allows Windows to recognize the minimum, maximum and center values for your control board. It is recommended that you calibrate each input you plan to use based on your final control board configuration. By calibrating each input in the final configuration, Windows can detect if you are not using the full input range and translate inputs to the driver station properly.
To calibrate the analog inputs:
- First, connect your LaunchPad / Custom OI Pannel to an open USB port
- Go to Start and search for Set up USB game controllers in the search bar
- Select MSP430-USB Gamepad from the list and click Properties
- Go to the Settings tab and press Calibrate…
- Follow the instructions to calibrate your control board
- Open the USB Devices tab in the driver station and verify that all inputs are working correctly
CAUTION If you do not connect the spare analog inputs to a voltage during calibration (so called ‘floating’ inputs), the input will behave erratically. We recommend that you connect each unused analog input to ground and avoid using these in your code.
Connecting to the Driver Station
Once the MSP430F529 LaunchPad board has been programmed, it will automatically be detected by Windows as a joystick. When you load the driver station and go to the USB Devices tab you will see the device enumerate as MSP430-USB Gamepad. You can now access the data from the LaunchPad in your code as you would with any other joystick.
Using the Launchpad as an HID GamePad
Once the gamepad firmware is loaded on to the LaunchPad, you can connect a variety of switches, buttons, and analog sensors to the input headers.
CAUTION Before making any connections to the BoosterPack, make sure the LaunchPad is disconnected from the computer and is no longer powered.
The header pins on the Launchpad will map to different functions in the gamepad that it enumerates as on your PC. When you flash the Launchpad with the GamePad tool, you will see a full mapping of the inputs.
You will need the following materials to start creating a basic custom human interface:
- Various buttons, switches, or potentiometers
- Male jumper wires, or alternative method to connect to the LaunchPad headers
- Wiring tools such as strippers and soldering iron
Included in all three configurations are a number of Digital Button inputs. There are numbered in the mappings in how they will appear in the USB HID report, or the Drivers Station software. Each of these will use a General Purpose Input/Output (GPIO) pin on the LaunchPad Microcontroller. These GPIOs are set by the firmware as digital inputs with internal pull-down resistors enabled. A button is registered as "pressed" when the digital input goes High (3.3V). The pull-down resistors pull the inputs LOW (0V) internally, so by default the inputs will all be LOW (released) until pulled HIGH externally. Therefore, to add a switch or button that triggers a "pressed", all you need to do is wire the switch so that it completes the circuit between the input and VCC (3.3V). See the figure to the right for a schematic drawing.
Each input has eight analog axes that are accessible via the headers on the LaunchPad, and are labeled in the maps as AX-1, AY-2, AZ-3, AR-4, BX-5, BY-6, BZ-7, and BR-8. These inputs will accept an analog input from 0V to 3.3V, which will correlate to 0% to 100% on the input to the Drivers Station. This scale can also be calibrated to match your input range as described in “Calibrating Inputs.” There are many different types of analog signal generators available, but the easiest to use will be potentiometers. Since the system will have to comply with the 500mA limit of USB, it’s recommended to use pots valued from 5kOhm to 100kOhm in order to reduce system power consumption.
The ADC on the MCU is capable of measuring a 0 - +3.3V range at a resolution of 12 bits. The gamepad firmware takes the 12-bit measurements and sends them directly to the PC. The voltage resolution can easily be calculated:
Voltage Resolution = (ADC Voltage Range)/(2^(ADC Bits) - 1) Voltage Resolution = (3.3 V)/(2^12 - 1) = 805nV
Knowing the voltage resolution is useful if you are connecting a sensor that may not span the entire ADC input range, or if the sensors resolution is higher than the ADC. When using a linear taper pot that is wired the same as in the Potentiometer Schematic Drawing, you can simply determine the angular resolution by dividing the pot's degrees by the ADC resolution. For example, a pot with 300° of motion will have an angular resolution of:
Angular Resolution = (Total Degrees)/(2^(ADC Bits) - 1) Angular Resolution = (300°)/(2^12 - 1) = 0.073°
The gamepad firmware takes the 12 bit measurement and converts it into a signed number between 0 and 4095 before sending it through the gamepad data structure. The diagram to the right shows how the measured voltage and data values are mapped to the gamepad axes. Note that the Driver Station will convert the gamepad data into a signed number between -1.0 and +1.0.
Example OI Panels
To help kickstart some ideas for your team’s own control panel, we have built several examples to showcase ways to use the various inputs. Each of these will have a full bill of materials, including vendors that are typical for FRC. Each item is fairly standard, and it should be easy to find functional equivalents out of your own vendor list if need be.
Have a solution of your own that you would like to share? Email us some pictures and documentation at FRCSupport@list.ti.com and we'll include it in our showcase below.
Mixed Input Design
A typical addition to a normal driver input could combine various inputs as described above. To this end, we created an operator interface will 10 digital inputs, 10 digital indicators, and five analog axes. When designing an OI board, it’s important to make it easy to use for anyone, especially during the intensity of an FRC match. The hand pattern and discrete analog layout in this example lets the second driver use the panel easily without looking at it, keeping their eyes on the robot and match.
Our preferred method of connecting IO to the LaunchPad is by using 20 wire ribbon cable with a 2x10 header on one end. The cable is then split, and routed to each appropriate input. It’s important to note that the pinout of these connectors has alternates from row to row, as show in this IDE cable example. The same is true of the cable connecting the digital side car to the CRio in the pre 2014 control system.
The buttons used are Cherry MX style key switches that are found in many high end keyboards, and then color coded caps were added to help distinguish them. Since we are using VCC as a HIGH signal, a single conductor was routed between all of the switches, and then connected to VCC on the LaunchPad. The other side of each switch connects via its own conductor. The color coding of the ribbon cable helps simplify this immensely. Be sure to double check your conductor with the pinout map for the LaunchPad configuration.
The digital indicators are also active high, but as outputs. This means that the pin output will be 3.3V when set. We connect the indicator LEDs like any other LED to a system able to power one. For this setup, the LED anodes (+) were individually connected to the conductors on the ribbon cable, and the cathodes (-) to their driving resistor (more information on calculating LED resistors here). The drive resistors are on the ground side, so there were all connected together and then to ground to complete the circuit. Remember to use heat shrink to add additional mechanical support, and prevent potential shorts.
Each pin has been set to enable a drive strength of 15mA, but the total device current output is limited to 100mA. If this value is exceeded in your design, it could damage the LaunchPad. If this is the case, you can use an external transistor to drive the LED beyond the LaunchPad’s ability (example: MSP430_LaunchPad_Drive_LED).
The linear and rotary potentiometers are all three pin devices, as described in the analog input section. One side of the pot is connected to ground, and the other to VCC from the LaunchPad. This lets the input signal swing from gnd to vcc when the slider or knob is actuated.
The rotary encoder was also used as an analog input. By connecting all the encoder terminals together, we can essentially create a potentiometer with discrete steps, letting the encoder be used on a single input, rather than several discrete digital inputs.
- Laser Cutter Design Files - File:FRC MixedIO Pattern.pdf
- 3D Printed Knobs - File:FRC Knobs.zip
- BOM - File:FRC MixedIO BOM.pdf
High count digital input
Another valuable use case for a custom operator interface is to have many digital inputs for various robot functions. Using option three, we made a panel with 20 inputs, and zero outputs. We chose some lighted pushbuttons from NKK due to their high tactile feedback, and very bright LED. This makes sure that each button press is properly registered, and the user knows exactly when it occurs.
Much like the previous example, it’s useful to connect the VCC lines together to make wiring easier. Since these buttons have high power LEDs inside them, and we don’t want that power coming from or to the LaunchPad pins we also connected all the ground pins to provide a return current path.
The LED in each button has its own dedicated pins in addition to the switch. Since we are only using passive feedback from the button press and not driving the LED from the LaunchPad, a simple scheme was developed to connect the LED and the signal line to the same button press.
Since we didn't know what the game was going to be when we made this operator interface, we decided to just use a variety of button labels. The laser cutter files have these as text and can be modified in your preferred software if you choose to reuse this panel.
1:1 Analog Control
Being able to create custom interfaces lets you have more than just buttons and knobs. It takes a bit more design effort, but it’s possible to create small analogues of your robot, or its manipulator, in order to create a 1:1 interface. For this one, we made a small robotic arm with potentiometers at each joint that can be read as analog inputs.
[1:1 demo video]
Modifying the LaunchPad Firmware
All of the code for the gamepad firmware is available for free and is open source under the BSD license. The code is hosted on a Github page here.
If you wish to modify this firmware we recommend forking this repository on your team’s Github page. If your team does not have one, you can get a free private organization account. This will allow the community to see and fork your changes, though you can keep your repository private during build season if you so choose. We also want to see what types of things the community can do with the LaunchPad!
FAQ & Troubleshooting
We want to hear from you! If you have any questions or comments that are not addressed below, or if you want to show off your solution with the LaunchPad (we love to see these!), feel free to email FRCSupport@list.ti.com and we will provide support. Please note that the TI employees behind this email are all passionate FIRST mentors for our own local teams, which means we will try to provide useful feedback in a timely manner, but the closer to bag & tag or competition it is, the longer it may take to hear back from us. We also frequent the forums at Chief Delphi and can answer questions there as well.
Q. When I try to download a program I encounter an error: Error 5000 Gamepad Tool.vi <ERR> Programmer didn't succeed. Check log file for details. Where can I find this log file?
A. Anytime the programmer is run, a file is generated with a time stamp at [Gamepad Tool]\Tools\mspdebug\Logs\ where [Gamepad Tool] is the tool installation directory. For 64 bit Windows this is C:\Program Files (x86)\FRC Gamepad Tool. In some cases the log files are not generated due to file permission error, to fix this, rerun the tool as administrator and a log file will appear.
Q. The FRC Gamepad Tool does not detect my LaunchPad board
A. Verify that the driver is installed and that your system recognizes the device. To do this go to your Device Manager and you should see MSP Debug Interface under the Ports tab. If you do not you will need to install the LaunchPad Driver. The FRC update package from NI should automatically install the driver for the LaunchPad, but if this install failed you can download the driver package here. If this still does not work, try the next answer.
Q. Help! While trying to program my LaunchPad something went wrong and the tool no longer finds it!
A. To recover your LaunchPad, follow the instructions from this Chief Delphi post.
Q. When I try to use an analog input the driver station shows the scaling/analog range/etc is incorrect or not working
A. Try running the joystick calibration routine again and verify at this window that your analog input is working as expected.
Q. The analog input is noisy and jumps around a lot, even if I don’t change the voltage
A. The most likely cause for noise issues is loose cables or poor soldering. It is strongly recommended that you use a sturdy connection on the LaunchPad and all input devices.
Q. Can I use the LaunchPad as something other than a gamepad, say on the robot for LED control or data logging, or maybe for other demos?
A. Yes, the MSP430F5529 device is a generic microprocessor and can be used in many applications. The MSP430 also has a large community and sample code for things like LED control and others.
Q. Can I use something other than Code Composer Studio to code the LaunchPad?
A. Yes, there are several third party programs and compilers available. If you are more familiar with the Arduino environment, the LaunchPad has an equivalent environment called Energia, however the libraries in Energia do not currently have support for USB HID devices, so you cannot modify the Gamepad firmware in Energia.
Q. What is Energia, and what is the difference between Energia and the Arduino environment?
A. Energia is a fork of the open source Arduino environment for programming the LaunchPad and includes the following features:
- Energia supports the broadest portfolio of embedded processors, enabling code compatibility on many TI devices across multiple architectures including MSP, TM4C, CC3200 & more.
- Energia is open source & free
- Unlike Arduino, Energia is pre-packaged with built-in support for key cloud partners. No need to manually download & import libraries. Support for IBM’s IoT Foundation, Temboo, PubNub & more are baked right in.
- Energia offers integrated low power capabilities (unique VS Arduino), intelligently jumping into low power modes without the developer having to know in some cases
- CCSv6 now has the ability to import Energia projects/sketches. This provides a very unique migration path from rapid prototyping to development & ultimately productization. By importing into CCS, developers have access to debugging & other features of a full blown IDE.