Writing custom libraries for Energia (Arduino)

This is just about the pragmatics of: where do I put source files so that they are a shared library?

Custom: one you write yourself.

Library: a set of C++ source files (.h and .cpp) that you want to share among projects.

The simplified Energia/Arduino view

Outside the simplified Energia/Arduino world, libraries would be in a separate, shared directory and they would be pre-compiled into an object and separately linked into your projects.  In the Energia/Arduino world, that is all hidden.

Also, in the Energia world, a library seems to be a zipped directory of source files that follow some conventions that identify the version and documentation of the library.   So you can share the library.  I don’t know what the conventions are.  But if you are going to share your custom library, you should follow the conventions, and zip it up.  Then others can use the simplified user interface for installing zipped libraries.  Here, I don’t bother with the zipping.

Creating a custom library

Briefly, you just need to create your source files in the place that Energia looks.

Find where your sketchbook directory is:  In Energia choose “Sketch>Show Sketch Folder.”  Expect a file browser dialog (the Finder on the Mac) to show you the directory.

You will see a sub directory named “libraries”, and it will probably be empty.  (I don’t know where Energia keeps all the other pre-installed libraries.)

In that directory, create a directory with the name of your library e.g. “PWM”.

In the “PWM” directory, create your .h (and maybe .cpp) files, e.g. “pwm.h”

Now switch back to Energia and select “Sketch>Include Library>”   Expect a hierarchal menu to appear.  Expect to see “PWM” in the “Contributed libraries” section of the menu.

You can also choose “Sketch>Include Library>Manage Libraries”.  Expect a browser kind of window to open.  You should be able to browse to a line saying “PWM version unknown INSTALLED”.  (In my opinion, this should not be called “Manage Libraries” because it seems all you can do is view a list of the libraries.)

(Note that Energia expects at least one source file in your library directory.  Until then, Energia may give an error “Invalid library found in….”)

Referencing the library

In your main sketch “#include <pwm.h>”

Then define an instance of the PWM class and call its methods.

Developing and managing your library

You can just edit the files in place, using another editor.   When you use Energia to “verify” the main sketch that uses the library, it will recompile your changed library.

By managing I mean: copy the files out of the sketchbook folder to a safer, more shared place.  The sketchbook is in /Users/foo/Documents/sketchbook (on a Mac).  I prefer to put them under source control in a “git” folder, or in the “Dropbox” folder, so when I am done developing, I copy the library folder somewhere else.

I suppose you could use git in that directory, and when you are done, commit and push that repository to a your shared (master) repository on github.

Brief Summary

A library is just a named directory in the directory “sketchbook/libraries”.  You can create a library yourself using a file browser and editor.


Setting Up a Linux Development System for Embedded Wireless using TI LaunchpadXL-CC2650 EVM


A record of my learning experience.  Discusses general, high-level considerations. Gathers many links that I followed.


For advanced, C programmers who are new to TI’s tool chain for programming embedded devices.

Similar documents

CC26xx Family SW Quickstart Guide also covers this material.

This blog shows a similar process for an older EVM (SensorTag), but using Windows OS and CCS Desktop.

The Narrow Subject

Here I assume the CC2650 target (an mcu and radio system on a chip) but only discuss:

  • Bluetooth (the chip allows other protocol choices i.e. WiFi or Zigbee)
  • TI-RTOS (other RTOS choices might be various free OS’s)

This might apply to other TI chips such as CC13xx, CC2640, and other earlier chips.

The Broader Subject

Wireless networks, not necessarily IoT development.  My use case is not serious IoT: I don’t want to connect to the Internet and I don’t even want to talk to standard Bluetooth devices, just between two of my own.  I don’t even want Bluetooth protocol, it just happens to be what I studied first.


I could be wrong.  You should follow links to original sources.

Other target, IoT, and wireless network ecosystem choices

ARM mBed ecosystem also offers an online IDE, desktop development tools, an RTOS, and bluetooth stack.

The CC26xx target uses the ARM ISA.  You might be able to use the ARM ecosystem, but I think the bluetooth stack in the ARM ecosystem might not work on the CC26xx?  The CC26xx has two processors, a host (ARM M3) and a network (ARM M0) processor.  A Bluetooth stack should have an interface at the HAL layer between the upper layers of the BT stack and a network processor’s implementation of the lower layers.  I don’t know whether either the ARM bluetooth stack upper layers, or the TI network processor lower layers (in firmware on the M0), conform to any HAL interface standard.

(Note that TI also has much documentation on implementing “network processors”.  There, they are treating the CC26xx as a server for yet another processor, the application processor, say a powerful cpu of a desktop PC.)

ARM does not make chips (only the design IP for them).  You might consider whether using TI tools locks you into their chips, and whether using the ARM ecosystem would give you a choice of chips.

TI’s IDE Choices

CCS Cloud – “online IDE” or “online compiler”: browser and cloud based: few files stored or installed on your development system (host)

CCS Desktop – installed on your host computer, based on Eclipse IDE

Energia – (Arduino clone) does not support the CC26xx family target.

Dev System OS Choices

For CCS Cloud, shouldn’t matter, but it does: to burn to the EVM requires setting up communication via USB to the EVM, which is host OS dependent (drivers and permissions.)  CCS Cloud requires installation of TI Cloud Agent on your desktop.  All three major OS’s are supported.

For CCS Desktop, all three major OS’s are supported, but Windows seems to be favored.  E.g. installing the Bluetooth stack is biased: requires Wine on Linux.

TI’s instructions  for Building BLE Projects on Linux.  It acknowledges that TI does not officially support their BT stack on a Linux dev system (but they do support their IDE and RTOS.)


To develop, you need three components:

  • IDE (CCS Desktop or Cloud)
  • Bluetooth stack (or another wireless stack, i.e. library)

Using CCS Cloud, all three components come easy, automatically.

Using CCS Desktop, you must know the steps.

Installing CCS Cloud

Installation is minimal.  Search for “CCS Cloud Tools”.  Click on “CCS Cloud>Click to Start Developing”.  It will open in your browser.  When you first try to “Run” your target app, it will give you further instructions for installing:

  • a browser plugin
  • TICloudAgent

You must install TICloudAgent, and on Linux it depends on installing certain 32-bit libraries.  It’s web page seems out of date, it doesn’t show support for Ubuntu 16.4 or for this EVM (Launchpad.)

CCS Cloud is intended for starting programmers or small trials, i.e. for education and evangelism.  I don’t think the user base is large, yet.

I want to use it ( I have used Energia for small projects.)  But so far, I have had a fitful experience.  In other words, it seems somewhat fragile: requires refresh or restarting things.  Maybe slow.  But at least you can quickly experiment and learn the scope of your project (what might work, what else you need to learn.)

For example, at first ‘Run’ (burning to target) didn’t work for me, and after rebooting my dev system the next morning and plugging in the EVM after CCS Cloud was started, it did work.

For example, at first a project built successfully.  Then subsequent builds failed even though I had not changed a line of code.  The fix may be to delete a project and redownload it (using TI Resource Explorer.)  Maybe it is a consequence of changing between my two host computers.

Sometimes it fails to login (“too many logins”).  I guess there are limits on their servers?

The browser connection times out at inconvenient times (say every 30 minutes.)

Run (download to target)

“Failed to connect to target” : you don’t have the target plugged into a USB port on your desktop.

“Firmware update required” : the debugging interface half of the EVM board requires flashing.  This seems to be a warning, as download to the target seemed to proceed.

Installing CCS Desktop

Linux instructions.

A training video.

Additional notes

CCS Desktop is based on Eclipse IDE.  It is not a plugin that you can download from within Eclipse, but is downloaded and installed(?) separately (thats weird.)  If you are an Eclipse user, the overall look-and-feel is familiar, but specifics might not be.

The installer is 32-bit, but TI  says to use 64-bit Linux (that’s weird.)  You MUST follow the instructions for installing 32-bit library dependencies. (a 64-bit host will run 32-bit apps if the needed 32-bit libraries are also installed.)

The installer won’t run by double clicking it (because “>file *.run” shows it is 32-bit ELF?) but will run from the command line.  The installer is a .run instead of a .bin (thats weird?) but see this explanation of what a .run file is (essentially, an installation tool outside the approved Debian process.)

If you the installer starts but shows an error dialog “Failed to locate …libgcrypt…” you didn’t follow the instructions for installing that component.  You follow the link and click on “32-bit” (which points to ftp for a .deb file)  and expect to continue to install libgcrypt using “Ubuntu Software” installer app.

When the CCS Desktop installer runs, expect a wizard to run, that downloads and installs.

CCS Desktop: Installing TI-RTOS

You install TI-RTOS (development libraries) from within CCS.  Navigate to the TI App Center and choose “TI-RTOS for CC13xx and CC26xx”.

CCS Desktop: Installing Bluetooth Stack

TI’s instructions  for Building BLE Projects on Linux gives specifics for installing the BT stack on Linux using Wine (Windows emulator.)  Those instructions seem to be out-of-date.  I needed these changed instructions:

sudo apt-get install wine
sudo apt-get install winbind
(Download the Windows .exe installer.)
cd ~/Downloads
wine ble_cc26xx_setupwin32_2_01_00_44423.exe  (expect installer dialog)
cd ~/ti
cp -r ../.wine/drive_c/ti/simplelink/ . 

My changes to the instructions:

  1. Once you install the BLE SDK, I suppose it creates files in the proper place, and then you can uninstall Wine from your Linux computer?
  2. When I tried “>wine ble….exe”  it yielded errors about “ntlm” and needing package “winbind.”  And failed to create ~/<me>/.wine/drive_c/ti  (where it should be installing files.)  So I also installed package winbind.
  3. The installer did not seem to create .wine/drive_c/Program Files(x86\)/Texas Instruments/Boundary/  so I omitted the step of copying it.

(I haven’t successfully built a project yet.)

CCS Desktop: Importing Example Projects

I tried the TI Resource Explorer and did not have much luck finding

TI’s instructions  for Building BLE Projects on Linux also gives instructions for importing example projects.

CCS Desktop: Tweaking Example Projects

The instructions there for changing the linked resources (paths, capitalization of fileNames, and fileName wording) are slightly dated but generally accurate: you will need to use the principle and tweak the exact changes yourself.  For example, the filename “RF.c” seems to have changed in the latest release of BLE SDK.

If you get:

error: can't create session manager: can't find a JVM;
 the environment variable 'XDCTOOLS_JAVA_HOME' is set,
 but does not appear to be a directory containing a 64-bit
 Java Runtime Environment

Then see this post on TI Forum .


What are Images?

For the CC26xx, burning the target comprises two steps:

  • the app
  • the bluetooth stack

These are two different projects in the IDE.

TI calls them “images”.  I suppose that means they are loaded in different addresses of target ROM, and that the app on the target knows where to find the BT stack.  You only need to burn the BT stack once (unless it changes upstream, a new version.)

What are the symptoms of failing to burn both?  The app and not the BT stack:  does the app complain somehow?  The BT stack and not the app: nothing whatsoever happens, there is no app to boot?

Test Projects, CCS Cloud

How to use TI’s example projects to test your dev system.  These were written while I was using CCS Cloud; they might not apply to CCS Desktop.

Project Zero for CC2650

A demo app to burn onto your SimpleLink LaunchPad.   Essentially it sets up the Launchpad as a BT peripheral that a central device (a phone, etc.) can poll (see advertisements), connect to, and change attributes (to blink LED’s.)    This describes the demonstration, what a user sees.

As near as I can tell, this is NOT the app that is burned into a LaunchPadXL-CC2650 out of the box.  At that time, pushing the upper right button on the LaunchPad causes it to BT advertise, and for the green LED to blink.

This can be a test case for your development system.  If you successfully build and burn it, it should behave as described, talking to a BT scanner on another device.  Unfortunately, to see the results you need to use some of the free BT scanner apps, you need another BTLE enabled device, Android 4.3 or greater, or a recent iPhone or iPad that supports BT Low Energy.


This project prints “debug messages” once per second for a few seconds. It doesn’t use the radio.  It is intended to teach how to code semaphores etc.

CCS Cloud:  When you click the Debug icon, expect a dialog to open (the dialog that shows progress).  It should say, in order, paraphrased:

  • Building…
  • Loading…
  • Initializing…

The red/green led on the top half of the EVM should blink as the program is burned.

CCS Cloud: Then the dialog goes away and the debug panels of the IDE show new information, and a marker appears across from “main()” in the panel that shows the code.  The debugger is waiting for you to start the app.

Press the “Resume” icon in the debugger panel (looks like the standard “Play/Pause” icon on VCR’s).  Expect the program to run and print some messages into the Debug tab of the panel across the bottom of the IDE.  The final message should be “bigTime ended.”


This example project is configured for another EVM.  When you try to “Run” it on the LaunchpadXL-CC2650 EVM, you get the error “….Failed to connect….”.

To fix it, click right mouse button on the project in the Project Explorer Pane of CCS Cloud.  Expect a menu to pop up.  Choose “Project Properties”.   Expect a dialog to appear.  In the “General” section, in the “Connection” textbox, click.  Expect a pulldown menu to appear.  Choose “XDS110” (the type of interface on the upper half of this EVM.)  Choose OK and build again.

Repeat for the other half of the project, the …App… versus the ….Stack….

Other Notes

It seems like a few “Run” errors in red while burning, such as “Failed Device Reset”, are ~normal~ and that CCS Cloud retries and eventually succeeds.

Sometimes Ubuntu displays “You have just opened  a digital audo device” dialog meaning it has seen the Launchpad on the USB port somehow.  Choose “Do nothing” and “Do this always.”  Maybe it interferes with CCS Cloud if you don’t?

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.


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++


  • 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:

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*

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


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.