In our last Stellaris how-to we got the board working and set some registers to turn on the LED. This time we’ll start using StellarisWare Driverlib, which provides drivers for the microcontroller’s peripherals including GPIOs, UARTs, ADCs, and so on. These libraries make it easier to control the peripherals. We’ll build the Driverlib project, create a project from scratch to use the library, and run a simple LED blinking example.
Build Driverlib:
First, we’ll add the Driverlib project to our Code Composer Studio Workspace:
- Project -> Import Existing CCS Eclipse Project
- Click browse and select the StellarisWare\driverlib folder
- Check driverlib-cm4f
- Click Finish
We’ll have to build the Driverlib project so we can include it as a library:
- Right click driverlib-cm4f project in project explorer
- Click Build Project
Creating a Project:
Next, we’ll need to create a project with the correct includes and library references. Create a new project with the correct settings:
- File -> New -> CCS Project
- Family: ARM
- Variant: Stellaris LM4F120H5QR
- Connection: Stellaris In-Circuit Debug Interface
- Select “Empty Project (with main.c)” under “Empty Projects”
- Click Finish
Start by adding the Driverlib library:
- Project -> Properties
- Build -> ARM Linker -> File Search Path
- Click add next to “Include library file or command file as input”
- Click Workspace…
- Choose driverlib-cm4f/Debug/driverlib-cm4f.lib
- Click OK
Now add StellarisWare to the include search path:
- Project -> Properties
- Build -> ARM Compiler -> Include Options
- Click add next to “Add dir to #include search path”
- Click File system…
- Choose StellarisWare install directory (ie, C:\ti\StellarisWare)
- Click OK
At this point, the project should be set up to use Driverlib. Lets try a simple example to make sure it’s working.
Using Driverlib:
This example will just blink two colors of the LED. This is similar to TI’s Project 0, except our project will be built from scratch. This main.c file will include the required libraries, initialize the peripherals, and blink the LED:
#include "inc/hw_gpio.h"
#include "inc/hw_memmap.h"
#include "inc/hw_sysctl.h"
#include "inc/hw_types.h"
#include "driverlib/gpio.h"
#include "driverlib/sysctl.h"
#define LED_RED GPIO_PIN_1
#define LED_BLUE GPIO_PIN_2
#define LED_GREEN GPIO_PIN_3
void main(void) {
// configure system clock to run at 50 MHz
// use external crystal (16 MHz) and PLL
SysCtlClockSet(SYSCTL_SYSDIV_4|SYSCTL_USE_PLL|SYSCTL_XTAL_16MHZ|
SYSCTL_OSC_MAIN);
// Enable PORT F GPIO
SysCtlPeripheralEnable(SYSCTL_PERIPH_GPIOF);
// set LED pins as outputs
GPIOPinTypeGPIOOutput(GPIO_PORTF_BASE, LED_RED|LED_BLUE|LED_GREEN);
// loop forever
for (;;) {
// set the red LED pin high, others low
GPIOPinWrite(GPIO_PORTF_BASE, LED_RED|LED_BLUE|LED_GREEN, LED_RED);
// delay
SysCtlDelay(2000000);
// set the green LED pin high, others low
GPIOPinWrite(GPIO_PORTF_BASE, LED_RED|LED_BLUE|LED_GREEN, LED_GREEN);
// delay
SysCtlDelay(2000000);
}
}
Let’s build and run the project:
- Click Run -> Debug
- Click Run -> Resume
Hopefully, the LED will be flashing red and green. Now that the library is working, you can access drivers for all of the peripherals. See the Stellaris Peripheral Driver Library User Guide for full documentation on Driverlib. You can also check out TI’s Stellaris Launchpad Workshop.
Yeah, but the licensing of driverlib is absolutely horrific though… not a fan!
What is the license?
The only thing that sucks with stellaris – is their license. For me it sucks thrice as much, since I just can’t integrate it with my GPLed buildsystem.
Care to elaborate? IANAL, but my reading is that
a) you’re only allowed to use StellarisWare with TI devices (it’s not very useful for anything else anyways),
b) you’re not allowed to redistribute or relicense StellarisWare source code under different terms than what TI says
Ok there’s a lot of lawyer-speak in the EULA. E.g. “You shall maintain the source code versions of the Licensed
Materials under password control protection” sounds pretty scary. But it basically means that you should not publish copies of StellarisWare in your public github repository.
Also the terms about public software sound scary. But they basically tell you to make sure to not distribute StellarisWare itself under another license model. Keep your open sourced code separate and don’t use tools with silly license terms (“all code that this tool touches shall be public domain from here on”) and you should be fine.
The export control language in section c is another can of worms, but don’t blame TI for that one. Technically that restriction applies to any piece of software and hardware originating in the US, whether license terms state it or not.
Okay, so what does it mean for an opensource project?
It states, that you can’t combine with viral opensource licences. You have a nice GPL library – rewrite it from scratch. Or rewrite stellarisware from scratch. Nuff said.
Second, is the stellarisware itself. If you need to have a few modifications to stellarisware itself, like a little bit of ld file magic to make your own stuff work, you’ll need to maintain a series of patches and a set of scripts to apply those. And more, if you distribute the source, you can’t just add a script that downloads stellarisware, since Ti’s retarted download procedure. So the end user will have to register to download the sourcecode manually at the Ti’s website.
In other words, if you pick stellaris for a cool opensource project, you just disrespect whoever will be using it and wasting their time.
Honestly, whoever decided on such a license for stellaris is mentally ill. It makes it pretty much a useless pile of crap. So my choice right now is STM32.
See comment further below, it’s actually a lot simpler for the StellarisWare libraries as they are under a BSD style license. So there should be no headaches with combining this code with GPL.
From what I can see on my installation, there are exceptions for a few of the examples and advanced libraries, e.g. basic USB support that’s part of the standard library is under BSD, the advanced implementation has the license above.
My experiences thus far with CCS have been pretty awful — the IDE crashed as soon as I programmed the device. I’m waiting to do anything with my Stellaris Launchpad until there’s a good third-party programmer tool, like mspdebug was for the MSP430 Launchpad.
AFAIK the more recent versions of the driverlibs have been licensed under BSD. Only the example code still has the nastygram at the top.
What’s confusing is that the StellarisWare installation includes an EULA.TXT as well as a TI-BSD-EULA.TXT. But you’re correct that the include and source files only include the briefer BSD license.
Yes, that’s right the source has only the BSD license content in it.
no one has a gcc-arm setup for this board yet?
hmm, posted too fast, seems that the work is underway…
I’m using gnu-arm with CoIDE (CooCox). Here you can get my workspace: http://hackaday.com/2012/10/11/getting-started-with-the-stellaris-launchpad/#comment-814809
The license even the non-BSD one isn’t actually that scary. Basically all it really intends if you read it right (that is what Ti would actually come after you for perhaps if you did) is taking the thing they spent a lot of effort and porting it to another brand of micro.
It is clear this is what the licenses were designed to stop. Because GPL is incompatible with such a restriction they have to band it. But LGPL would work as would anything that carries forward the microcontroller locked part of the code.
The simple thing to do is to write a modular program and just link the Ti part to the other bit that you write in an abstract microprocessor free way if your project is complex enough for that. Otherwise just carry the Ti license.
My little shop teho Labs, has had a series of boards based on the M3 line Ti got from Luminary Micro for some time and I published modified examples based on the driver library which I believe is fully consistent with the license.
I also provided tutorials for non-CSS toolchain, which I am sure could be used with the M4 stuff with some modification. Assuming the people on the openOCD project figure out the JTAG.
If they do this launchpad will become a rather inexpensive ARM JTAG, certainly the cheapest I know of.
Hack-a-Day, maybe it is time to put a Stellaris tag-link on the right side of the page.
A cool thing with stellaris ware is that it is included in a ROM portion of the IC. Prefix these commands with ROM_ and they will be reference from the ROM. Saving program flash space.
That is my understanding anyway.
There is a lot of fighting over the license, but doesn’t most of it deal with the stellarisware codebase itself? I mean, can’t you just have code that assumes the use of stellarisware, has the api calls, and just not have the actual stellarisware library in your distribution?
My order status still says “Processing” :(
Doesn’t look like I’m getting it anytime soon…
god damnit I’m pretty pissed I didn’t get my board in the mail yet. I ordered it the day OF the announcement or the next day in the am. It’s expected Nov 11. Are you fking kidding me TI?
Amazing – you have to do all that
just to start a new project.
Telling it each time about libraries and includes that one will use for most every project.
Too bad you can’t just tell it about them once
and be done with it. (As one can do easily with simpler tools.)
Thank you for the write-up, wish they included something like this in an obvious place in the
documentation.