The STM32F429I-DISCO Tutorial Series, Part 3: The Build Environment

Before we can program the STM32F429, we need a development environment.

To ensure that what worked for me will also work for you, I'm going to start with a brand-new virtual machine and do all my work in the VM. This ensures that I don't have any pre-existing dependencies installed on my machine that you don't have on yours.

In many ways, this series of posts will be the reviews of STM32CubeMX and System Workbench for STM32 that I promised to write a few years ago but never did.

So... let's get started!

Step 1 (Optional): Create a new Virtual Machine

You probably shouldn't do this step. You should probably install System Workbench on your everyday hobby computer. I'm only doing this step to ensure that I don't skip any steps, and to allow me to go back and start over repeatedly as I develop my process and document it for you. But if you'd prefer to run your STM32 build environment in an isolated VM, feel free to follow along. Otherwise, skip to Step 2 below.

My hypervisor is Oracle VirtualBox 5.2.4 running on a Windows 7 host machine. Feel free to use any virtualization platform you'd like. I chose to use Lubuntu as my guest operating system. I chose Lubuntu because it is an Ubuntu variant that doesn't include all of the bloatware (LibreOffice, music players, etc.) that I don't need or want for my dedicated STM32 build VM.

1. 1. Launch Oracle VM VirtualBox Manager.
   2. In the main toolbar, click the "New" button.
   3. On the "Name and operating system" page of the Create Virtual Machine wizard, enter a name for your VM (STM32GUITutorial, in my case). Choose "Linux" as the Type and "Unbuntu (64-bit)" as the Version. Click Next.
   4. On the "Memory size" page of the wizard, allocate RAM to your VM. I used 2048MB (2GB). More is probably better, up to a point. Keep in mind that this amount of physical RAM will be unusable by your host OS while the VM is running. You can't allocate more RAM to the VM than is physically present in your host machine. Click Next.

1. On the "Hard disk" page of the wizard, select "create a virtual hard disk now" and click Create.
2. On the "Hard disk file type" page of the wizard, select "VDI" as the hard disk file type and click Next.
3. On the "Storage on physical hard disk" page of the wizard, select "Dynamically allocated" and click Next.
4. On the "File location and size" page of the wizard, type "120GB" as the size of the hard disk and click Create. (You may of course choose a different size virtual drive for your VM.)
5. Right-click on the newly created VM in the left-hand pane of the Oracle VM VirtualBox Manager gui and select "Settings..."
6. Select System in the left-hand pane, and click the Processor tab. Ensure your VM has at least two virtual processors assigned to it.

11. In the General section, on the Advanced tab, if you want clipboard redirection (it's handy!), enable it here.
12. Download the Lubuntu bootable DVD image to your local (physical) hard drive. The default download method is through a torrent. (I'm using Lubuntu Desktop 18.04.)
13. Back in Oracle VM VirtualBox Manager, in the settings for our newly created VM, click the Storage icon in the left-hand pane.
14. In the right-hand pane, click on the "Empty" virtual CD-ROM drive.
15. Click on the icon of a DVD in the very right hand side of the settings dialog box. Select "Choose Virtual Optical Disk File."
16. Navigate to the Lubuntu DVD image that you downloaded and click Open.
17. Still in the Settings dialog for your new virtual machine, click on Network in the left-hand pane. Click on the Adapter 1 tab. Connect Adapter 1 to NAT.
18. Click OK to close the settings dialog.
19. Your virtual machine is now configured. It has a virtual hard drive large enough for our needs, it has two virtual processors, it has a virtual DVD ROM drive with the Lubuntu DVD inserted, and it has a network card. Right-click on the VM and select Start -> Normal Start.
20. A new window should open with the console of your VM. The VM should boot to Lubuntu and you should be presented with a Language selection list. Assuming you're a U.S. English speaker, you'd set up your VM's operating system like me:

20. Choose "English" as the language.
21. Use the down arrow to select "Install Lubuntu" and press Enter. It may take a few moments for the installer to switch to GUI mode and present the next dialog.
22. On the Welcome page, select your installation language and click Continue.
23. Choose your keyboard layout and click Continue.
24. On the Updates and other software page, select "Minimal installation" and leave the third-party software checkbox unchecked. Whether or not to download updates is up to you; I chose not to do that during installation and instead to do it post-installation. Click Continue.
25. On the Installation type page, select "Erase disk and install Lubuntu" and click Install Now.
26. On the "Write the changes to disk?" warning dialog box, click Continue.
27. Select your time zone and click Continue.
28. Enter a username and a computer name. Create a password for your user account. Tab over to the Continue button and press Enter.
29. Wait while Lubuntu is installed.
30. When the "Installation Complete" dialog appears, click "Restart now." When prompted to remove the installation medium, press ENTER.
31. Log in to your new VM with the username and password you created.
32. Congratulations! You now have a VM 'sandbox' in which you can play around with STM32 development. I recommend you start by updating your operating system. Do this by opening a terminal (click the 'start button' in the lower left hand corner of the screen, then choose System Tools -> LXTerminal) and running sudo apt-get update and sudo apt-get upgrade.
33. The reason I like Lubuntu as my dev OS is because it doesn't have a lot of extra software that I don't want. The flip side to that is, Lubunu doesn't have some of the software I do want. There are three packages in particular that need to be installed so that future steps will work:

• build-essential: This package contains tools such as the GCC compiler and its ecosystem. For STM32 development, we'll be installing a cross-compiler version of GCC that will compile for the ARM Cortex M4 core. However, even with that toolchain, we'll depend on make being installed on the operating system. Build-essential will install tools that the ARM cross compiler tools depend on. Also, we'll want to install the VirtualBox Guest Additions on our VM, and installing those will require the build-essential package.
• Building the Guest Additions tools will require that the proper Linux headers be installed.
• The gksu package will be needed for the System Workbench installer to gain superuser privileges from the GUI. (The gksu package has been removed as of Ubuntu 18.04. I'll have to find other solutions to this problem.)
• Lastly, there appears to be some 32-bit code in the System Workbench platform that relies on the 32-bit ncurses library. So we'll install that.
• You'll also want to install your favorite must-have utilities such as git.

34. Run sudo apt-get install build-essential linux-headers-$(uname -r) lib32ncurses5 git to install these software components.
35. Now you can insert the VirtualBox Guest Additions .iso from the Devices menu on the host's window for the guest machine and, from a command prompt, run sudo /media//VBox_GAs_/VBoxLinuxAdditions.run
36. Add yourself to the vboxsf group by running

    sudo usermod -aG vboxsf $USER

37. Reboot your VM so the Guest Additions are properly loaded and your user account's membership in the vboxsf group is properly applied. (If you'd like, now might be a good time to take a snapshot of the virtual hard drive.)

Okay, so that's it for creating a virtual machine for these exercises. Again, I don't recommend a VM for most users; you should really do this on your physical machine. Now let's install our build tools!

Step 2: Install System Workbench for STM32

ST has partnered with AC6 to develop a free build environment for STM32 microcontrollers. Don't confuse this with open source software-- it's not. This software is free-as-in-beer, not free-as-in-speech. AC6 System Workbench is a set of extensions to the popular Eclipse IDE that make it easy (well, easier, anyway) to develop on the STM32 family of microcontrollers. Eclipse, and System Workbench for STM32, are java programs and are thus cross-platform. The AC6 installer, however, has a built-in JRE (at least on Linux), so there is no need to preinstall a JRE. To install System Workbench for STM32, do the following:

1. Download and install System Workbench for STM32. Visit http://www.openstm32.org/HomePage. If you don't yet have an account, you'll need to create one. (Boo! Hiss! You should be ashamed, ST!) Log in to your account on the site.
2. On the homepage, after logging in, click on the "System Workbench for STM32 - Bare Metal Edition" link. (It's in the main page text; not in a navigation menu.)
3. Download the System Workbench for STM32 installer appropriate for your operating system. This page can be confusing; take the time to read what's on the page and follow instructions. As I wrote this tutorial, the installer for Linux is version v2.7 at 417MB.
4. If you're on a Linux-based system, you may need to change the permissions of the installer file that you downloaded and add the execute (x) permission. This can be done from the GUI or by running chmod +x from the command prompt.
5. Here we run into a problem: installing System Workbench for STM32 in GUI mode requires gksudo, and this package has been removed from Ubuntu in 18.04. Double-clicking on the installer will result in a frustrating do-nothingness. Running the installer from a terminal window will display a useful error message and allow you to continue in console mode. So, from a terminal, start the installer, and when prompted, choose to install in console mode. (Do not run the installer with sudo.)
6. Read the warning about Linux variants (if you're running on a Linux variant) and select 1 to continue.
7. Read the intro text, if you'd like, or press 'q' to skip the text, and press 1 to continue.
8. Read the license agreement from AC6, and press 1.
9. Read and accept the license agreement for the Oracle JRE, and press 1.
10. Unless there's a compelling reason not to, accept the default installation path by pressing Enter.
11. Type O at the warning that the target directory will be created.
12. Ensure that all three software components are selected, and select Y.
13. Wait for System Workbench for STM32 to be installed.
14. Enter an appropriate sudo password when prompted so that System Workbench can edit required udev rules so that the STLink debugger driver can talk to the target device over USB. Click Next.
15. I don't know what it does, but go ahead and create an automatic installation script.
16. Click Done.
17. You should now have a System Workbench for STM32 icon on your desktop.
18. You can delete the installation file, if you'd like.

System Workbench includes the Eclipse IDE (and the JRE on which it runs) and tools that automatically download and install the GCC build tools (compiler, assembler, linker, etc.) for STM32 microcontrollers. System Workbench will also automatically download firmware, such as the STM32 HAL, when required by the projects that you create. All in all, while it's got some annoying rough edges, it's a decent enough dev environment that does a reasonably good job of managing firmware dependencies.

Step 3: Install STM32CubeMX

STM32CubeMX is a tool that does a number of code-generating functions. It allows you to graphically select which microcontroller pins will be used for which functions, and will automatically write initialization code for the peripherals. Additionally, STM32CubeMX contains a wonderful clock configuration utility that will calculate the necessary settings for the many peripheral clocks in the STM32 microcontroller. STM32CubeMX is available both as a standalone Java app, and as an Eclipse plug-in. We will install both.

Now, if you'll recall, System Workbench for STM32 is written in Java. Java requires a Java Runtime Environment (JRE) to be installed on a computer in order to run programs written in Java. As it turns out, System Workbench installed a JRE when it was installed. So, you'd think that since your machine has a JRE installed, you'd be able to install STM32CubeMX, which is also written in Java, right?

Wrong.

For reasons that defy explanation, one of these tools installs its own private JRE, and the other depends on a system-wide JRE. So, in order to install STM32CubeMX, you need to have a JRE installed on your system. You can install Java from http://www.java.com, or in Lubuntu, you can run sudo apt-get install default-jre to install the default open source Java runtime. After you have a JRE installed, you can install STM32CubeMX.

Install the Standalone version of STM32CubeMX

1. Open a web browser and navigate to http://www.st.com/en/development-tools/stm32cubemx.html.
2. Scroll to the bottom of the page, to the "Get Software" section. Click the Get Software button.
3. Accept the license agreement.
4. Again, you will need a user account. Create one if you don't already have one, and log in to ST's website.
5. The download should start automatically. Save the .zip file to an appropriate location on your hard drive.
6. Open the downloaded .zip file and extract the contents to a convenient folder. (I recommend creating an empty folder to hold these files.)
7. If you are running the Lubuntu VM we created above, install the ld-linux-so.2 interpreter, which allows running 32 bit code on a 64 bit machine, by running: sudo apt-get install libc6-i386
8. Double-click the "SetupSTM32CubeMX-<version>.linux" file. (I used version 5.0.1)
9. On the welcome screen, click Next.
10. Read and accept the license terms from ST and click Next.
11. Unless you have a compelling reason to do otherwise, accept the default path and click Next.
12. Click OK on the warning dialog box that the target directory will be created. (And wonder why ST would think that this is worth a warning dialog box.)
13. Allow STM32CubeMX to install.
14. When the top progress bar reads "Finished," click Next.
15. Click Done.
16. You may delete the folder with the installation files.

Install the Eclipse Plugin version of STM32CubeMX

1. Open a web browser and navigate to http://www.st.com/en/development-tools/stsw-stm32095.html.
2. Scroll to the bottom of the page, to the "Get Software" section. Click the Get Software button.
3. Accept the license agreement.
4. Again, you will need a user account. Create one if you don't already have one, and log in to ST's website.
5. The download should start automatically. Save the .zip file to an appropriate location on your hard drive.
6. Unzip the contents of the downloaded .zip file to a convenient location on your hard drive.
7. Launch System Workbench for STM32. (There should be an icon on your desktop that was created when you installed it.)
8. Accept the default workspace location by clicking OK.
   
   Record the location of the default workspace used by System Workbench forSTM32. You'll need it for my later posts.
9. System Workbench will download and install various software components necessary to compile for STM32. Be patient.
10. From the Help menu, select "Install New Software..."
11. Click the "Add..." button next to the "Work with:" dropdown.
12. In the Add Repository dialog, click the "Local..." button.
13. Highlight the folder (but don't go into it) that contains the files you just extracted and click OK.
14. Back in the Add Repository dialog, click OK.
15. Check the "STM32CubeMX_Eclipse_Plugin" checkbox in the Install dialog.
16. Click Next.
17. On the review screen click Next.
18. Read and accept the license agreement and click Finish.
19. If you get a security warning about unsigned content, click OK.
20. Click Yes to restart Eclipse.

Step 4: Git Integration

Don't even think about writing code without source code version control. Just don't.

There are many version control platforms out there, but the current king of the hill, especially in the open source world, is git. Now, I don't intend do deliver a tutorial on the use of git, but if you're going to be doing any amount of development work at all, you really should take the time to learn how to properly use at least one of the source code version control packages out there. For me, that package is git. As it turns out, git integration is pre-installed with System Workbench. So hey, we got that for free!

Summary

There we go! You now have all the tools needed to build applications for the STM32 series of microcontrollers. Believe it or not, getting a build environment set up used to be a very painful, very laborious process. System Workbench, while not open source software, is a very useful tool for getting up and running quickly.

In the next installment of this tutorial series, we'll build the canonical "Hello world!" application of microcontrollers and will blink an LED.