Using Energia with EZ430-F2013 LaunchPad on Linux

About this post

This pulls together various other posts and links.  Audience is someone who is new to embedded microprocessors (MCU) but otherwise  familiar with software development.

Context

Energia is an IDE.  It is a port of the Arduino IDE (swapping out Atmel AVR mcu for the TI MSP430 mcu.)  In other words, it is the Wiring development platform, but specialized for a different embedded mcu.

The IDE lets you edit programs and write them (flash them) to a target board.  This particular IDE does not have integrated debugging.

MSP430 is a family of ultra low power microprocessors from TI.  See the FAQ.

The EZ430-F2013  is one model of development kit for the MSP430.  It includes:

• an FET (flash emulation tool) hardware
• a detachable target board (detachable is unusual, most have pluggable IC’s)
• other IDE software tools on a CD

A FET is an adaptor from your development PC to the target board.  Adaptor: it has a USB connector on one end, and a connector to the target board on the other end.   It adapts from USB serial to Spy Bi Wire serial.  This particular FET and connected target board are in a USB stick form factor or package.  With the IDE, it lets you:

• flash the memory of the target board
• debug the target board using a version of gdb talking JTAG/SBW to the target

The target board is a small PCB having:

• the MSP430F2013 model mcu
• one LED
• two rows of breakout pins for you to add circuitry
• a four-pin connector to the FET.

You can also buy a  EZ430-F2012 (part number), which is a package of three compatible target boards, except they have the MSP430F2012 (model number) mcu.

Why this combination?

Pros of all TI’s other development kits:

• cheap, TI seems to be subsidizing
• target mcu is ultra low power, TI seems to be emphasizing low power for the IOT, and has many other low power chips
• target mcu is small in area

Pros of this development kit:

• the target mcu is VERY small (a few tens of mm squared)
• you could use the detachable target board as a component (although it has an odd half-moon shape).  It’s the size of your thumbnail.

Pros of Energia:

• it has an approachable language (a simple subset of C++)
• it has many built-in libraries
• you can also program in C++

Cons:

• its basic, low-end, and older
• the target mcu has too small 2K flash memory for large programs
• the target mcu has few IO pins
• the target mcu has few modules (peripherals): only an ADC, and a few timers
• its not very popular, most professionals use other development kits, other IDE’s, and other programming languages (assembler or C)
• several IDE functions use the command line (debugging)
• it flashes using SBW, which is slower than a full JTAG programmer
• it doesn’t interface the serial port of the target board (to let you print)

For learning, its great.  But consider whether the target board will meet the needs of your application.

Install Energia

Download Energia   On Linux, expect a .tgz file to download.

Unarchive it.  Expect it to create a directory “energia….” in your home directory.

Follow the instructions for installation on that page (except for the udev.)

Setting up the udev

On Linux you must set up a UDEV.  If not, you may later see an error message:

ti3410: warning: can't detach kernel driver: Operation not permitted

which means, in Linux, you don’t have permission to write to the USB device.

However, the given instructions don’t work. ( The USB stick has ID  0451:f430  which is different from any listed in the downloadable udev rules.)

Instead use an editor to create a file named 46-TI_launchpad.rules in this directory location:

/etc/udev/rules.d/46-TI_launchpad.rules

having this contents:

ATTRS{idVendor}=="0451", ATTRS{idProduct}=="f430", MODE="0660", GROUP="foo"

where ‘foo’ is the group that you belong to.  You need to be superuser, so use >sudo nano or >sudo vi to create the file.  What this does: at boot time, the OS gives permission for anyone in the group to read and write the OS device file (/dev/tty?).

Restart your computer.

Patch Energia for the MSP430F2012 or 2013

Energia doesn’t properly support this development kit (there are patches waiting to be approved and merged on GitHub.) But you can fix that by:

Edit ~/ener*/hardware/msp430/boards.txt.

Copy and paste the first block of text.

In the copy, change:

‘r2500’ to ‘uif’ after the word ‘protocol’.

‘msp430g2331’ to ‘msp430f2012’ or ‘msp430f2013’ everywhere in the copied block only

If you omit this step, when uploading you may see the error message:

usbutil: unable to find a device matching 0451:f432

Start Energia

Open a terminal.

>cd ~/energ*
>./energ*

Expect a GUI application to start.  Stuff will still scroll in your terminal window, but the same stuff appears in the bottom pane of the GUI.

Swapping target boards

You can pry the plastic USB case apart with a small blade or screwdriver.   It is split down the middle.  It has friction fit, plastic pins.  Pry one half straight up.   Then the target board pulls off the end.  You probably should saw the end off the plastic case so you can handle the unit but more easily change the target board (if you intend to flash more than one target board.)

If you intend to use the ADC of the F2012 mcu, swap the target board out first thing.  The F2013 has a different ADC (a SMA_16 16-bit) versus the F2012’s ADC10 (10-bit).  The ADC registers are at different addresses.  The MSP430 architecture (ISA) does NOT generate exceptions (trap) for all illegal addresses or illegal opcodes!  Instead, it quietly lets you read and write some addresses (device registers) for which there is no device.  In other words, if your program that uses the ADC doesn’t work as expected, maybe you are including the .h file for a different target and addressing the wrong ADC.  The ISA is subject to change between models, read the datasheets carefully.

Plugin your EZ430-F2013 USB stick

Plugin your EZ430 USB stick.  Expect it’s LED to start blinking.  (When powered up, it resets, and the factory programmed “blink” program starts running.)  The LED may never blink again, depending on your programming skills.

Test the Blink program

Choose File>Examples>Basics>Blink.  Expect a new program to load into the IDE.  This program is compatible with the target board (which has one green LED on Port1.Bit0).

Choose Tools>Board.  Expect to see a list of boards.  Select ‘LaunchPad w/ msp430f2012 (1MHz)’.  (Or …f2013)  Expect the item becomes selected, but nothing else.

Choose File>Upload.  Expect output from the compiler and an upload result message.

If it fails, try again.  Inexplicably, sometimes it fails to upload, with this:

fet: FET returned error code 4 (Could not find device or device not supported)
fet: identify failed

When it works, expect:

ti3410: warning: can't detach kernel driver: No data available
Device: MSP430F20x2
fet: FET returned NAK
warning: device does not support power profiling
Erasing...
Programming...
Done, 788 bytes total

Note that here I have already swapped out the F2013 target board for a F2012.

Expect your USB stick blinking again.

Now you can go on to write other programs.

Using the serial port

The menu Tools>Serial Port remains greyed out (disabled) and will remain so.   The FET has two pins toward the target board that are not connected to the target board.  Thus the FET can not read the serial port of the target board, and your program will not be able to print to the serial port and expect it to appear on the IDE.

The target board does have breakout holes for the TXD and RXD pins of the target mcu.  You might be able to jumper them to the FET.

Probably the designers of the target board decided that since memory on the target board is limited, it would not hold a library implementing serial IO (in addition to other program code.)

Debugging

You can use gdb on a command line to debug the target device remotely (the target supports JTAG so this is possible) as described by an Energia dev.

Energia invokes the mspgcc compiler with optimization.  You might need to alter you program (remove inlining) to insure that functions appear as symbols.

From an obscure post by Ingo:

mspdebug does not use debug symbols (the ones you enable with the -g compiler switch), just the plain symbol names that are also used for linking. However, in the ELF format, each symbol has a type field, and mspdebug only uses symbols of certain types (object, function, etc.). You can display the symbol table of an ELF object with “readelf –syms file.o”. Symbols whose type is listed as NOTYPE will be ignored by mspdebug.

An example of what you can do (see gdb for more):

• set breakpoints (>break foo)
• print object (variable) values (>print foo),
• ctl-C interrupt the target and show the backtrace (>bt)

Programming in C++

You don’t need to use Wiring.  You can program in C++, C, or even assembly language.  A short blog.

Not using Wiring saves much program memory. For example, the  Stepper library with a few other Wiring libraries would not fit into the 2k memory.  But recoding relevant parts in C++ did fit.

To code in C++/C you might need to understand:

• the gcc compiler variant that Energia invokes
• the intrinsics to assembler that the compiler supports (section 6.8 of the above)
• interrupt handling and the ‘vector’ pragma (section 6.7)
• the runtime environment (section 6.  It sets up the stack, etc.)
• the include file that defines target addresses, constants, and other language constructs (in this case “#include msp430f2012.h” or …f2013.h )  which are found at ~/ener*/hardware/tools/msp430/msp430/include/

Typical code flow

See TI’s Application Report MSP430 Software Coding Techniques.

But adjust to fit.  For low power, you will need to use interrupts, but you don’t need to use flags, you can have a state machine and enter low power mode from many states.

Development Kit User’s Guide

The development kit User’s Guide  :

• includes a schematic
• tells how to use the other IDE’s, but not Energia
• gives instructions for opening the case

Using the FET for other targets

You can design your production PCB with a matching four-pin connector, and program/debug it using the FET portion of the development kit.  The four pin connector has Vcc, Vss, and two SBW signal lines.

You might be able to use the FET with a different target.  I haven’t tried it yet.  I don’t know of any impediments.  My opinion is that TI is downplaying the ability of the FET.  The User’s Guide says it will work with other devices in the ‘MSP430F20xx’ family.  (I am hoping it works with devices in the MSP430FRxxxx family.)

Ultra Low Power Hardware and Coding

Ultra low means: less than about 1uA average current.  That gives tens of years on a coin cell battery.  Or lets you use energy harvesting.

The mcu when active draws tens or hundreds of uA.  Thus to achieve ultra low power, the mcu must be sleeping (in a low power mode) much of the time, and use interrupts to wake up.

If you have external interrupts, the lowest power mode is LPM4 (the mcu and peripherals off, but external interrupts will wake.)  Called ‘Off Mode with RAM Retention’.  Draws 0.1uA.

If you don’t have external interrupts, sleeping is low power mode LPM3 with a timer peripheral running in the mcu to interrupt and wake the cpu up.  In this mode (called standby), the MSP430F201x draws 0.5uA.

If you need accurate time, you can implement a 32-bit  RTC in software, as described by a TI Application Report, using an external clock crystal (loses 1 second per month) to the 16-bit timer (which wakes up the system every few seconds to tick the 32-bit software RTC.)

If you don’t need accurate time, you can use the VLO portion of the clock module as the clock source for your timer.  That is the lowest power standby mode.  See the datasheet for the MSP430201x.

If you need even lower average power, you can switch power Vcc to the mcu, using an external chip such as the TPL5010 Nano Timer which draws only 35nA (0.035uA.)  But then you might lose any data saved in volatile memory (RAM) such as the context of your application (and the application must restart.)

TI makes MSP430FRxxxx‘s having FRAM and using as little as 0.35uA current in standby mode.  Some models have a 32-bit RTC implemented in hardware.  Check the datasheets, its not clear to me for which applications this family saves power.   The smallest member/package for this family has 24 pins, compared to the 14 pins of the F2012, and is 16mm square, about the same area.  (These packages are near the limits of what you can solder at home.)

More about JTAG and Spy By Wire (SBW)

See JTAG and SBW. JTAG uses many signal wires, SBW only two.  SBW is slower.

Also see section 28 Embedded Emulation Module of the MSP430x2xx Family User’s Guide.

In short, it means that you can use a software debugger (similar to gdb) to remotely debug a program on an  embedded MCU while in-circuit (soldered to a prototype or production  PCB) using only two wires to connect from the development machine to the PCB.  That is, you don’t need to simulate, you can debug under actual hardware conditions.  If the hardware timing conditions are not so severe that you need a more powerful solution.