Discovery: Documentation

This week on the Embedded Wednesdays Discovery series, I will introduce the documentation set that covers the STM32F407G-DISC1 development board. I will also provide links to the ST support forums and some websites of other people that are working with this board.

DSA - What Can Be Done?

Many people suffer from DSA - Data Sheet Anxiety. This is the feeling that “I don’t know how to read data sheets”.

DSA is understandable, there is a lot of information in the data sheets, but fear not, you’re not expected to read the whole thing. Some data sheets are huge, the reference manual for our ARM processor weighs in at 1,744 pages. You are not expected to memorize the whole thing. If you do, the processor will either become obsolete or your next project will use something completely different, and a chunk of your life will have been wasted.

In embedded systems, starting out on a new processor is the worst. You end up doing bottom-up programming where you have to set up the registers for the peripherals to form the basis for your application. Unfortunately you end up working with the most complicated and unfamiliar portion of the system first. You have to dig through the description of each peripheral, looking for the register settings. Then you find out that the documentation can’t be printed out because the paper pile would be too thick to sit on your desk.

What do you do?

Don’t panic. You need to find all of the documentation, figure out what is in them, then determine which parts are going to be useful.

(For convenience I have provided links to the document set for our board, below.)

Data Sheets

ST has a variety of names for their documents; data brief, user manual, reference manual, technical note, errata, and application note.

To get yourself oriented to the board and processor, you would start by looking in the product specification section of the product web page for each piece for the data brief or data sheet. The data sheet has a simplified overview of the part that stays away from the horrible details. If you don’t understand an acronym, or want to see what facilities a part has, this is the place to look.

The DISC1 board’s data sheet is very straightforward for someone who has used other single board computers like the Arduino.

However, DSA might start to kick in when you read the processor data sheet. There is a whole bunch of good information in the processor data sheet, but there is also a bunch of stuff that you should ignore. Let’s go through it in a little more detail.

The ST family processor data sheets will have a cover sheet that has the selling features of the processor listed, how fast it runs, how much flash and RAM, how many pins, power consumption, and a list of the special peripherals. This is a good read if you are comparing processors to see which would be best for your project.

Following the cover sheet, you have the typical table of contents and then the introduction. If you’ve never used a particular processor before, it would be useful to familiarize yourself by going through the introduction. I like to print out a copy of the processor block diagram and attack it with highlighters so that I can see that X timer is connected to Y device.

Following the introduction is a long, simplified, overview of the processor and the peripherals. Not much scary content here and once you’ve worked with one of the processor family, you thumb through this section looking for the new stuff.

For the software people, the electrical characteristics section looks like electrical engineering talk, you can mostly ignore it. Knowing the intricacies of the bypass capacitors and power sequencing may be beyond what you need to know. The interesting bits in the electrical specs are:

  • The “endurance” of the flash memory. This is how many times you can erase and reprogram your processor. On our processor this is 10,000 erase/program cycles. So while you are developing your code, you can try 10 versions a day for 3 to 5 years.
  • The supply voltage range of the processor (known in the sheet as Vdd). Our processor has a range of 1.8 to 3.6 volts, so if you want to connect to a 5 volt device like an Arduino shield or a Neopixel, you have to use some sort of voltage shifter. It’s best to check the voltage, just to make sure.
  • The maximum current per pin (Iio). On our processor this is 25mA which is barely enough to illuminate an LED using a current limiting resistor. Hooking an LED up without a current limiting resistor will blow up the pin. Some processors supply far lower current than this and absolutely require some sort of external drive transistor.
  • The temperature range can be useful to know if you are building a project that is going to go outside here in The Great White North, or under the hood of a vehicle where temperatures can reach 125C (250F). It’s a bit disturbing that the minimum operating temperature on automotive grade processors is -40 degrees since I’ve seen that temperature quite a few times (not recommended). Our processor is rated for -40 to +85 C.

That’s about it for the electrical section until you get into stuff like running off of a battery for months. Your EE friend can sift through the rest.

The documentation gets updated regularly, so I don’t recommend printing it out or even saving copies. I have included links to the product web pages for the board and processor, these pages don’t tend to move, but the links to the documentation change when the documents get updated. Always use the latest data sheets and check back often.

The Board Documentation

The Product web page for the board is the landing page for all of the documentation pertaining to the DISC1 circuit board itself. The product page also includes links to application notes which are in-depth how-to documents on various aspects of using the board. The documentation for the processor and the extra peripheral chips are not on this page, so I have included them in the next section, there are a few more board documents to consider first.

The Data Brief document gives you an overview of the DISC1 device at a high level, just introducing the product without much in the way of technical detail. This would be a good document to compare two different boards to see which is a better fit for your project.

The User Manual gives a more in-depth description of the board. It includes the schematics, jumper settings, options set by solder bridges, a description of the on-board peripheral chips, and a description of the functions available on each header pin. This would be a good document to read completely.

Application Notes are a great way for the manufacturers to answer frequently asked questions in an example format. They can also provide ideas for projects if you don’t have something in mind.

The Processor Documentation

The processor has its own Product web page. This page holds links to the documentation and application notes for the processor.

Data sheet - the 200 page overview. As described above, read this but ignore the electrical characteristics section.

Reference Manual - the 1700 page detailed manual for the peripherals internal to the processor. Don’t read this, use it as a reference. Print out sections if you like to make notes. Completely ignore the sections dealing with peripherals that you are not using. The processor has all unused peripherals disabled, so you don’t need to worry about configuring them.

Errata sheet - this (usually short) file documents all of the known bugs in the silicon and gives workarounds when possible. This is a very important document that even experienced engineers often overlook. Read this to see if there are any bugs in systems you plan to use. Then read it again when the hardware is behaving in ways you can’t explain.

Programmer’s Manual - this file documents all of the assembly language instructions. If you are programming in C, you shouldn’t need to read this.

On-board Peripheral Documentation

ST Support Forums

Other Web Sites

  • - Carmine was the person who figured out how to get ST’s processor configuration software running on a Mac. He is writing a book on working with the STM32 using Eclipse and GCC on Mac, Linux, and Windows.
  • - A web site that I keep getting directed to by Google search when I’m trying to find information.

Feel free to suggest other websites in the comments.

Going Forward

You will quickly find out that the data sheets are full of a lot of information, but very little that tells you how to do what you want. Next week we will look at the tools available and where to get sample code. Until then, explore the websites and read the data sheets.

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