Discovery: Sample Code

This week, we are going to locate some sample code for the STMicroelectronics STM32F407G-DISC1 development board.

Sample Code

When you are getting started with a processor or peripheral, sample code is an indispensable tool. Once you start reading the data sheets, you’ll find that the descriptions aren’t quite written in an understandable way. Even seasoned old greybeards will read the manuals and say “I recognize these words, I even use them in polite conversation, but I’ve never seen them used quite like that.”  A lot of the manuals are technically correct, but quite confusing. This is where sample code comes in.

Each manufacturer will have a repository of sample code. The field application engineers (FAEs) will write sample code for their customers and make them available for everybody to use. Some manufacturers will put them on a web page. ST decided to distribute their sample code with their CubeMX processor configuration tool and Hardware Abstraction Layer (HAL) firmware library.

Why would you want to use sample code rather than read the documentation? The documentation has information about every single flag bit in the processor, but they don’t say which ones are necessary to configure for a particular task. With a few lines of code, the FAEs will set up the peripherals to show some concept. They don’t tend to use the nice-but-unnecessary options.

One common complaint is that the examples are too simple. Well yes, the FAEs aren’t going to do your job for you, but you can typically find an example that is basically what you need, then you need to read the documentation to figure out the necessary changes.

Getting Down To It

Since the sample code is distributed with CubeMX and the HAL, it is time to get a copy and install it. CubeMX+HAL is a multi-platform system, written in Java, and usable on MacOS, Windows, and multiple Linux variants. It generates startup and configuration code for all of ST’s STM32 processors and has board descriptions for all of ST’s various development boards, so you don’t have to configure where the buttons, LEDs, and extra chips are connected. The code can be compiled with a variety of C compilers, such as GCC, Keil, and IAR.

The home page for CubeMX has links for the documentation, the program, and a plug-in for Eclipse.

To download the installer, you have to create an account with ST. Creating accounts is quite common when dealing with large corporations. They send you occasional emails, but with the ID you get the installer, the source code for the HAL, and an ID to post questions on the support forums.

The CubeMX download is currently 168 megabytes, so we in the Great White North, with our steam powered network connections, have time to go shovel the sidewalks while the download happens.

Both the installer and CubeMX use Java, so you’ll have to have that installed beforehand.

The CubeMX application is ready to go. On a Mac it is stored in your Applications folder in a folder called STMicroelectronics.

You still don’t have the sample code though. So far, we have only put CubeMX in place, and since the sample code is adjusted for the particular processor family you are using, it is bundled with the HAL. The HAL is downloaded when you generate your first batch of code for your processor. First, fire up CubeMX:

  • Click <File> <New Project ...>
  • Click on the Board Selector tab
  • Under Type of Board, choose Discovery
  • Under MCU Series, choose STM32F4
  • In the Boards List, choose STM32F407G-DISC1
  • Click OK
  • Wait, wait, wait…
  • Click <Project><Settings …> and give your project a name (I used test)
  • Leave everything else as it is.
  • Click Ok  (take a look at the wikipedia page for okay, I can’t tell if it is a joke or for real)
  • Click Yes
  • 315 megabytes later...

The CubeMX installer will create a folder in your home directory called STM32Cube, with a subfolder called Repository containing two interesting folders; Documentation and Projects.

Read over the CubeF4 Getting Started guide in the Documents directory. I will be using Cube to generate the various examples in the coming weeks.

In the Projects directory, there is a bunch of sample code for the various STM32F4 development boards. Our board is basically identical to the F4Discovery board (only varying in the debugger module), so, if you want to look ahead, start with at the F4Discovery examples.

Each processor in the family will have a varying amount of program memory, RAM, and peripherals, but if two processors have the same peripheral (say a random number generator), the register set for that peripheral will be the same on the two processors. That means that since the F4Discovery doesn’t have a random number generator (RNG) example, but the ‘412G-Discovery board does, the RNG code can be applied to the F4Discovery board.

Is The HAL Ready For Prime Time?

The examples are written using the HAL to do the work of pushing values into device registers. Unfortunately, ST has not converted the examples to use the CubeMX models and program structure. I expect that this is coming.

CubeMX and the HAL have only been around since early 2014 and has gotten past the “work in progress” stage. I would definitely consider the startup and configuration code generated by CubeMX as being production quality, and I’m currently using it in customer code.

Next week we’ll look at the CubeMX screens more carefully. Until then, please download CubeMX and the Sample code.

The DISC1 board running canned sample code, lighting the 4 LEDs that surround the accelerometer.

The DISC1 board running canned sample code, lighting the 4 LEDs that surround the accelerometer.

This post is part of a series. Please see the other posts here.