Eclipse + STM Nucleo Board Setup

This document describes how to create a project in Eclipse that targets the STM Nucleo Boards, specifically the Nucleo-L433RC-P. The documentation for this is all over the place, so I figured I would attempt to help where possible. I'll walk through installing everything, modifying templates, and everything up to compiling the source and debugging on the chip.

Installing Everything

In this section, we are going to install a ton of software that will get us able to compile things. This might be easier if you're willing to pay for proprietary software, but this is all completely open source. I will install the following, in order:

Step 0: Prepping some Folders for Install

When you initially install Eclipse it will be just a boring C/C++ IDE. It can compile that code but has absolutely no way of pushing it to our microcontroller, so we will be placing a handful of tools in these folders for configuration. I went ahead and created a folder in my Home directory called Workspace and within that, I have four folders named CubeMX_Projects, EclipseWorkspace, Packages, and Software_Toolchain.

Step 1: Installing Eclipse

I will be installing Eclipse Oxygen (4.7). The Eclipse Organization releases a new major version the last week of June every year, so feel free to get the newest version at that time. You can find the downloads here. From the link, we want the IDE for C/C++ Developers. It should detect your platform, on Linux it comes compressed as a .tar.gz, so uncompress that either in the CLI or a GUI, then move it to where you want it to be installed. For me, I usually install applications like this in /opt/ so just sudo cp -r ~/Downloads/eclipse /opt/. Before launching it, make sure to check the SHA sum. If it looks good, create a launcher for it and it should be ready to be used for basic C/C++ development, so now onto the Embedded Programming specific toolchains.

Step 2: Cross-Toolchain for ARM Cortex Processor

You can either set up the PPA as described here (I can't verify this will remain up to date) or download it here. You'll want to uncompress this .tar.gz file. Move this folder gcc-arm-none-eabi to the folder we created earlier Software_Toolchain. We're done here for now.

Step 3: GNU ARM Eclipse Plugin

Go ahead and open up Eclipse for the first time. Choose a workspace folder somewhere like ~/Workspace/EclipseWorkspace/STM32_demo. which we already prepped above. Once Eclipse loads, simply go to Help->Install New Software. In this tool window, hit add, and copy and paste in this link http://gnu-mcu-eclipse.netlify.com/v4-neon-updates/, which was taken from the GNU MCU Eclipse GitHub page. It will find there are some packages at the link, which we want to install. In this case, I only wanted to install 7 of the packages: ARM Cross Compiler, Generic Cortex-M Project Template, J-Link debugging, OpenOCD Debugging, Packs, QEMU debugging, and the STM322Fx Project Templates. Once you have selected those, hit Next, and Finish. It will download the software, and a dialog should pop up telling you are downloading unsigned content, just hit ‘Install Anyway’, and finally it will tell you to Restart Eclipse so do that as well.

Step 4: OpenOCD

The OpenOCD binary can be found under the same Github Organization as the GNU MCU Eclipse plugins we just installed. Here's a link. Head to the releases tab, and download the latest binary for your system. Obviously on Windows and OSX, .exe and .pkg installers will be the most helpful. On Linux, just download the raw binary, and extract to the Software_Toolchain folder we set up in step 0.

Step 5: CMSIS

The raw source files can be found here. Simply extract that to the Software_Toolchain folder from before. For now, we won't do anything with this, as it will be configured with we set up the project.

Step 6: Device HAL

As stated above, this device HAL is now provided alongside numerous other standard components in the STM32CubeMX package, which can be found here. A quick google of ‘stm32cubexx’ (where the xx is your series number like L4 or F4) will bring you to your specific board. To download the package, you must register with STMicroelectronics and log in. Once you are, clicking ‘Download’ at the bottom of the page will work. You should get the GIST by now, unpack, install for your system, done.

Project Setup

We finally got the tools setup, so let's just run something already! To do that, open up Eclipse and load the workspace we set up. Go to File->New->Project and Select ‘C Project’. Hit next. Select ‘Hello World ARM Cortex-M C/C++ Project’. Hit next. Now we have to input important details about our board itself. Again, I'm running the STM32 Nucleo-L433RC-P, which is designed to be a low powered board. So let's take note of some specs for your board, as they will be required in certain files to compile properly.

Updating HAL and CMSIS in Project

So the code compiles, but we now need to update both the CMSIS and HAL files to deal with our specific board. Open the STMCubeMX application and create a new project. For now, we will just leave the default peripherals enabled, so head to Project->Settings. In the first tab, name the project, select a path, and change the toolchain to SW4STM32 in the drop-down menu. Next tab, under ‘Code Generator’ you can simply leave everything the same. Hit ‘Ok’. It may tell you that it needs to download drivers for your board, so let it do that if needed. Then hit Project->Generate Code. Open the folder when alerted to ensure everything is there.

Now we have to place all of these files into our Eclipse project. First, let's handle the HAL. Head to Drivers/STM32L4xx_HAL_Driver/Inc, copy all the files by highlighting them and hitting Ctrl+C, head over to your Eclipse Project, in the left navigation bar open system->include->stm32l4xx. With the last stm32l4xx folder highlighted hit Ctrl+V to paste the files into that directory.

In your file browser, back up a few directories to Drivers/STM32L4xx_HAL_Driver/Src. Copy these files, head over to Eclipse, and paste them in system->src->stm32l4xx.

Next up are the CMSIS files. Even though we downloaded CMSIS 5 from ARM, we will use the ones given to us by ST for the moment. Head to Drivers/CMSIS/Include. Copy all the files here, and paste them into your project under system->include->cmsis.

Head back to the file browser to Drivers/CMSIS/Device/ST/STM32L4xx/Include. There should be 3 files here, copy them all and paste into the project at the same location as above, system->include->cmsis.

Head over to Inc at the root of your CubeMX project and copy just ‘stm32l4xx_hal_conf.h’. Paste this into the project at system->include->stm32l4xx. While we're here, also open this config file and remove the main.h include on line 43. As you can see, the IDE doesn't know where that is.

Head to startup in your project directory and copy this .s file. Paste this into system->src->cmsis. Also, delete vectors_stm32l4xx.c in this folder. Not sure if this still a bug, but best to do it anyways, you'll want to change the extension from ‘.s’ to ‘.S’ (upper case) as this is what Eclipse expects to find.

Finally, open up system->include->cmsis->stm32l4xx.h. After the main clauses, you'll notice a huge block of comments with define statements. You need to uncomment the line that corresponds to your board, in my case #define STM32L433xx. Try cleaning the project and compiling. If it throws no errors, then you've been successful up to this point.

Pushing Code to the Board + OpenOCD

Whew. That was a lot of setup, let's get the code to the board. Go to Run->External Tools->External Tool Configuration in Eclipse. Click on Program, and then hit the button just above it for ‘New’. Give it a name like ‘OpenOCD_conf’. Under location, navigate to where you stored the downloaded binary earlier in Step 4, for me this is in Workspace/Software_Toolchains/gnu-mcu-eclipse/openocd/[version]/bin/openocd. Next up select the Working Directory. This is found two levels up from the last path in Workspace/Software_Toolchains/gnu-mcu-eclipse/openocd/[version]/scripts. Finally under arguments put -f board/st_nucleo_l476rg.cfg. Under Build unselect ‘Build before launch’. Finally, under the Common tab, select the checkbox for ‘Display in favorites menu’. Hit Apply and Close.

Now we need to set up a debug build configuration. So go to Run->Debug Configurations. In the left column there is a section of GDB OpenOCD Debug, click on it, and then select the ‘New’ button above. Under the Debugger tab uncheck ‘Start OpenOCD Locally’. Under the Common tab, also add ‘Debug’ to the Display in Favorites Menu. Hit ‘Apply’ and Close.

To verify that the OpenOCD configuration has gone ok, plug in your board with a USB Micro-B cable, click on the ‘External Tools’ button at the top of Eclipse (looks like a Play Button with Brick Wall), and select the OpenOCD conf that we set up. If everything goes well, the board larger LED on the programmer should be rapidly switching between red and green and the console should say it's listening on port 3333. Unfortunately, there a million pitfalls here so here's at least one that worked for me.

Linux USB Permissions

Linux can be a pain when working with USB drivers sometimes. This part took me about 6+ hours the first time because I never bothered restarting my PC, which was the key in the end. At first, I was getting the common error

Error: libusb_open() failed with LIBUSB_ERROR_ACCESS
Error: open failed
in procedure 'init'
in procedure 'ocd_bouncer'

So first I made sure I was a member of the group ‘plugdev’ which you can verify by simply typing groups in the command line. If you still need to add yourself to plugdev, then simply type sudo usermod -aG plugdev <username>.

In addition to this, you'll want to add some UDEV rules that allow access to the board. An example is included in the openocd folder we already downloaded, if you've followed my tutorial exactly then just run sudo cp ~/Workspace/Software_Toolchain/gnu-mcu-eclipse/openocd/<version>/contrib/60-openocd.rules /etc/udev/rules.d/. I also modified this file to be more specific, but it may not be necessary. For the STLink V2 services I added group information and tags to read

# STLink v2
ATTRS{idVendor}=="0483", ATTRS{idProduct}=="3748", MODE="666", GROUP="plugdev", TAG+="uaccess"

# STLink v2-1
ATTRS{idVendor}=="0483", ATTRS{idProduct}=="374b", MODE="666", GROUP="plugdev", TAG+="uaccess"

After running that restart the udev service with sudo service udev restart.

Try running the openocd service in Eclipse again. If restarting the service didn't work, try restarting, as this has fixed it for me several times.

Windows USB Permission Errors

I haven't tested this personally since I rarely use Windows, but I've heard that sometimes Windows users also encounter USB drivers problems with OpenOCD, but these are much easier to resolve since you can simply download and install the drivers from ST right here.

Wrapping Up

I'm going to stop here. There's much more I could touch on, but it's probably taken you at least a little bit getting this far. From here, you should be easily able to generate more HAL and CMSIS driver files from the CubeMX Software, incorporate those into Eclipse to add peripheral support, and get on with writing code. Thanks.