måndag 10 augusti 2015

Clock setup for Olimex E407 using STM32CubeMX

Recently I got a reason to dig up my old Olimex E407 board and the RS232 shield I made for it (see earlier posts on this blog). This time though, I'm using Keil in Windows together with a ST Link V2. Getting the clocks and pll's right isn't an easy task, and certainly not a fun one, so I decided to give CubeMX and ST's HAL libraries a try.

The STM32CubeMX program (download it from ST.com) is a fairly new invention, and the libraries leave a lot to whish for still, so you should be careful with it. The libraries are still ful of bugs, but they are also getting a lot better rapidly.

Ok, first of course, download and install STM32CubeMX. If you want to launch it from Keil uVision, add the path to CubeMX to the system path environment variable. The start uVision5 and create a project for an STM407ZG.

Start CubeMX by clicking the "play" button right of the STM32Cube Framework (API).

Now, the Olimex E407 board is equipped with a 12 MHz external crystal clock and a 32.768 kHz external RTC crystal, so we have to enable those pins first.

Switch to the "Clock Configuration" tab and input 12 MHz as HSE input frequency and then make the following selections:
  1. Select HSE as PLL Soure Mux
  2. Set the /M divider to /7
  3. Set the *N multiplier to x196
  4. Set the /P divider to /2
  5. Select PLLSLK as System Clock Mux
  6. Set APB1 Prescaler to /4
  7. Set APB2 Prescaler to /2

Save it and select "Generate Code" from the Project menu.

When done, choose to close the CubeMX project and update the settings in uVision5.

A main.c file is generated for you that uses these new settings , ready to be filled in with your applicaiton source.

Good Luck

fredag 24 april 2015

A Comment on Comments

During recent years I have worked with many very tech savvy people worthy of a lot of respect for their insight in embedded development. However, the discussion regarding comments seems to never die. The more tech oriented the developers, the less they seem to like comments in source and the more they seem to believe self commenting code exist. It doesn't. What exist is self commenting thoughts in your head. I have no chance whatsoever to get a good grasp of your ideas without reading them, or asking you.

I have always taken a more customer focused approach, hoping that I won't have to explain myself too many times when I hand over the result of my efforts. Here are some things I would like to point out to all of you that doubt the usefulness code comments:

  • Code in itself can only describe what it does. Everything else are left out. All the experience you gained through experiments, fixing bugs and working with the environment is lost if you don't document it.
  • Code can't explain what it doesn't do. All the alternatives to the approach you have taken. All the quirkyness of the libraries you are using. That takes a long time to get your head around as a new employee or contractor.
  • Code doesn't explain its purpose. In best case, you can read out something from the function name or similar, but most of the time names like openAuxChannel leave you wandering WHY you would like to open an auxiliary channel.
There are lots of other reasons to write and maintain the comments in the source. But there is also the question of the cost for commenting code. If you comment your code you spend time that not feel very productive. In one sense that's correct, you don't write code, so you're not moving towards the goal of the project. But quality has to be considered too, and maintainability and tracability are such parameters. Without them, the quality of your code is poor. It eventually boils down to the cost of developing a feature vs. the cost of owning it. Over time, the cost of owning poor code is MUCH higher than the gain of developing poor code.

So, in the trade-off of commenting source and writing new features, I would like to promote some techniques that I practice:
  • Use doxygen! You might not like browse the source in rendered HTML or PDF documents, but it gives others a great overview and a starting point that lets them get get up to speed with the source quickly.
  • Write commenting scripts that puts skeletons of comments in your files, classes, members and functions. The cost of developing such a script is a lot less than the effort it saves. It takes away a lot of boring work as well! Often the IDE has some functionality for this, but I often get more fields into my doxygen comments with a script.
  • Don't comment getters and setters. Programmers are not stupid, they will understand anyway. Though, if you have a script putting doxygen comment on them, they will become browsable when the documentation is rendered, and that's very convenient.
  • Make sure you add comments to algorithmic code in the functions. These sections of comments are the most valuable. The not only explain your algorithm, it will affect your design too. If you notice that you have to explain flags and states set in objects or structures in other modules etc. it shows that your approach to the problem is probably not coherent enought, or easy enough. If you can't explain what you have done, you should refactor it.