STM32F0Discovery Under Linux Tutorial Part 2 – Using a Minimalist Integrated Development Environment From the Command Line

 In this blog entry we will examine using a development environment based on command line tools which will include using the VIM (VImproved) text editor, the GDBTUI debugger along with the Texane’s stlink  and OpenOCD GDBserver / programmer utilities. It is assumed that the reader has completed Part 1 of the tutorial.

So why use these tools when you have sophisticated tools such as Eclipse ? Command line tools run faster, are usually less buggy than their GUI counterparts and require significantly less memory and processing power. They also allow for a high degree of automation. They can turn your old PC into a development power house!

Using A Command Line Based Code Editor

Vim (or VI improved) is a powerful command line code/text editor that supports syntax highlighting, tabbed windows, horizontal/vertical split windows, advanced copying & pasting functionality, advanced search (and incremental search) functionality to name a few! Vim is a bit unconventional when compared with other text editors. But those patient and brave enough to use it will reap its benefits. A list of Vim tutorials is provided below:

Figure 1. Using VIM as a code editor.

Figure 1. Using VIM as a code editor.

I recently started using Vim and I’m having a blast! I highly recommend it to others. Other popular command line code / text editors include the incredibly powerful GNU Emacs and GNU Nano.

Using GNU GDB in TUI mode (GDBTUI)

The arm toolchain discussed in this and the previous tutorial comes with a GDB client utility. With the GDBServer (stlink’s st-util or OpenOCD) is connected to the microcontroller, the GDB client connects to the GDBServer to access the on chip debug capabilities of the microcontroller. GDB is primarily  text based, but it also has a mode called GDB Text User Interface (GDBTUI) which is a bit more graphical as it shows you the execution path in your source code as well as provides full GDB functionality. With GDB/GDBTUI one can view disassembly code,  set/toggle/disable/enable/delete breakpoints & watchpoints, perform step into and step over, run (continue), halt, watch variables,  set variables & monitor CPU/memory registers. You can even download the binary file from GDB/GDBTUI using the load command.

Figure 2. Using st-util GDBserver (left) and GDBtui (right) to debug project from command line

Figure 2. Using st-util GDBserver (left) and GDBtui (right) to debug project from command line

A list of good tutorials on GDB and GDBTUI are provided below:

Building Two Simple (template) Projects for the STM32F0 Microcontroller

In this section two simple projects for the STM32F0 microcontroller will be built using the toolchain installed in the previous tutorial. The first project “iotogglem0_wspl” is compiled against the STM32F0 standard peripheral library, while the second “iotogglem0” is not. Both programs perform the same function of toggling the two LEDs on the STM32F0Discovery board.

  • Create a “workspace” directory inside the “EmbeddedArm” directory (“mkdir ~/EmbeddedArm/workspace“) and navigate to it (“cd ~/EmbeddedArm/workspace“).
  • Clone the following ready to go project template based on the STM32F0Discovery standard peripheral library  with the following command: “git clone git://github.com/halherta/iotogglem0_wspl.git“.
  • This project expects  the firmware library folder “STM32F0-Discovery_FW_V1.0.0” to exist in  the “~/EmbeddedArm/STM32F0-Discovery_FW_V1.0.0” directory and the project files must exist at “~/EmbeddedArm/workspace/iotogglem0_wspl”. So be mindful of the directory structures involved.
  • Navigate into the “iotogglem0_wspl” and type “make“. This should build the project as shown in Figure 3a. The number under the word “text” is the size of the binary. In our case this is 2568 bytes out of the 65535 available bytes of program memory or 3.9% memory usage.
  • Type “make clean” to clean the build.
Figure 3a Project (with standard peripheral library)Built Successfully!

Figure 3a Project (with standard peripheral library)Built Successfully!

  • Clone the following ready to go self-contained project template NOT based on the STM32F0Discovery standard peripheral library  with the following command:”git clone git://github.com/halherta/iotogglem0.git.
  • Navigate into the “iotogglem0” and type “make“. This should build the project as shown in Figure 3b. The number under the word “text” is the size of the binary. In our case this is 860 bytes out of the 65535 available bytes of program memory or 1.3% memory usage.
    • Notice how not using the standard peripheral library can help us reduce our memory usage significantly!!!!
  • Type “make clean” to clean the build.
Figure 3b. Project (without standard peripheral library) built successfully!

Figure 3b. Project (without standard peripheral library) built successfully!

I highly recommend to those interested in using the ARM GCC toolchain regularly (with or without Eclipse) to invest some time in learning about the GNU Make and GCC tools Some good tutorials include:

Using Texane’s stlink utilities for Programming and Debugging From the Command Line

The Texane stlink utilities consists of two binaries; st-util is the GDB server, used for debugging and st-flash used for programming.

To start a Debug session (See Figure 2),

  • Connect the STM32F0Discovery board to the PC with a mini USB cable.
  • Open a new terminal and type : “st-util“. This should start the GDBserver at port 4242.
  • Open another new terminal window and navigate to the directory of the project that you want to debug; say “iotogglem0_wspl“.
  • In the second terminal type: “arm-none-eabi-gdbtui -eval-command=”target remote localhost:4242″ iotogglem0_wspl.elf “. This will start the debugging session using GDBTUI. At the GDB prompt  type”load” to program the binary onto the micro and initialize the debug session. You can then use the GDB commands to debug your program.
Figure 4. Programming the STM32F0Discovery Board from the command line using st-flash (texane's stlink)

Figure 4. Programming the STM32F0Discovery Board from the command line using st-flash (texane’s stlink)

To flash a binary file onto the microcontroller using the st-flash utility (see Figure 4):

  • Open a new terminal window and navigate to the directory of the project that you want to program; say “iotogglem0_wspl“.
  • Type the following command: “st-flash write iotogglem0_wspl.bin 0x8000000“. This command writes the contents of the binary file iotoggle_wspl.bin to the microcontroller’s program memory starting at address 0x8000000 (the first location of program/flash memory)
  • The st-flash utility can also be used to erase the program memory with the command “st-flash erase“. Unfortunately there’s a bug that prevents this command from working most of the time. Luckily when using the “st-flash write …” command described above, Program / Flash Memory is completely erased properly, then programmed and then verified. So the lack of a functional erase command is not strictly a major problem.
  • The makefiles that come with the two projects are able to automate the programming and debugging processes described above. This ability to automate  via makefiles and in some cases bash scripts, is probably one of the major advantages of using command line tools. In the appropriate project directory, simply type:
    • make flash_stlink” to program a binary file onto the micro.
    • make debug_stlink” to start a debugging session
    • make erase_stlink” to erase the micro’s program memory… As described above, this is currently not working.

Using OpenOCD for Programming and Debugging From the Command Line

OpenOCD is a GDB server utility that can be used for debugging and programming, very much like stlink’s st-util and st-flash. OpenOCD supports a wide range of programming/JTAG adapters(dongles) a wide range of  target CPUs and a wide range of development boards.

To start an OpenOCD debug session:

  • Connect the STM32F0Discovery board to the PC with a mini USB cable.
  • Open a new terminal and type the following command: “openocd -s ~/EmbeddedArm/openocd-bin/share/openocd/scripts/ -f interface/stlink-v2.cfg -f target/stm32f0x_stlink.cfg -c “init” -c “halt” -c “reset halt”   “. The -s flag establish a search directory for configuration files, The -f flag  includes specific configuration files from within that directory. In our case we are including the stlink-v2.cfg configuration file for the STLINKV/2 interface and the stm32fox_stlink.cfg file for the STM32F0 target. Finally the -c flag passes commands to the GDBserver so basically whenever a connection is made to the GDBserver by a GDB/ GDBTUI client, the chip will be put in reset first.
  • Open another new terminal window and navigate to the directory of the project that you want to debug; say “iotogglem0_wspl“.
  • In the second terminal type: “arm-none-eabi-gdbtui –eval-command=”target remote localhost:3333″ iotogglem0_wspl.elf“. This will start the debugging session using GDBTUI.  You can then use GDB commands to debug your program.

To flash a binary onto the microcontroller with openOCD:

  • Open a new terminal window and navigate to the directory of the project that you want to program; say “iotogglem0_wspl“.
  • Type the following command: incredibly long command: “openocd -s ~/EmbeddedArm/openocd-bin/share/openocd/scripts/ -f interface/stlink-v2.cfg -f target/stm32f0x_stlink.cfg -c “init” -c “reset halt” -c “sleep 100″ -c “wait_halt 2″ -c “flash write_image erase iotogglem0_wspl.bin 0x08000000″ -c “sleep 100″ -c “verify_image iotogglem0_wspl.bin 0x08000000″ -c “sleep 100″ -c “reset run” -c shutdown“. Again the -c flag is used to pass a sequence of commands that reset the target, erase its memory, flash it with the new binary, verify the memory and then exit.
  • Alternatively we could  navigate to the directory of the project and type: “openocd -s ~/EmbeddedArm/openocd-bin/share/openocd/scripts/ -f interface/stlink-v2.cfg -f target/stm32f0x_stlink.cfg
  • Then open a new terminal window and telnet to localhost port 4444 (to install telnet, type: “sudo apt-get install telnet“.) with :”telnet localhost 4444“. This will enable you to telnet into the OpenOCD GDBserver and interact with it.
  • In the telnet window (Figure 5) type the following commands to program the microcontroller: “reset halt“, “sleep 100“, “wait_halt 2“, “flash write_image erase iotogglem0_wspl.bin 0x08000000” & “sleep 100″.
Figure 5. Telnetting into the openOCD GDBserver (port 4444) to flash/erase the microcntroller memory

Figure 5. Telnetting into the openOCD GDBserver (port 4444) to flash/erase the microcntroller memory

  • To verify type: “verify_image iotogglem0_wspl.bin 0x08000000”  and “sleep 100”.
  • To have the debugger put the micro in run mode type: “reset run
  • If OpenOCD hangs, try either pressing the “RESET” button on the STM32F0Discovery board and/or remove the JP2 jumper and put it back on again to cycle power to the board.
  • You could probably omit the “wait_halt 2″ command mentioned for programming.
  • Also verifying flash might not be necessary for most cases. If you look at Figure 5 you will see that the number of bytes written in the program step is larger than the the number of bytes verified. This maybe due to the debug information being embedded in the .bin file that does not need to be verified. But I’m really not sure. Either way the new program should run on the chip with no problems.
  • I got the above commands from a script posted on Github by Mike Szczys.
  • Notice that the commands typed into the telnet window are exactly the same commands typed above are into the command line with the -c flags.
  • Finally note how we didn’t have to specify the directory that the .bin file to be programmed was in. This is because we started the GDB server in the project directory. When using OpenOCD  to program, it is very important to START THE OPENOCD SERVER IN THE PROJECT DIRECTORY!!!!
  • Mike Szczys’s stm32f0-discovery-basic-template enables programming and erasing the microcontroller with openOCD using two modules in a script that are callable from the command line/makefile. This is another very elegant solutionTo flash a binary onto the microcontroller with openOCD:

To erase the microcontrollers program memory with openOCD:

  • Open a new terminal
  • Type: ” openocd -s ~/EmbeddedArm/openocd-bin/share/openocd/scripts/ -f interface/stlink-v2.cfg -f target/stm32f0x_stlink.cfg –    c “init” -c “reset halt” -c “sleep 100″ -c “stm32f1x mass_erase 0″ -c “sleep 100″ -c shutdown “.
  • Again you can telnet into the openOCD GDB server (port 4444) and type in commands shown above ( “reset halt”, “sleep 100″, “stm32f1x mass_erase 0″ & “sleep 100″ ) to erase the chips memory.

The makefiles that come with the two projects are able to automate the programming and debugging processes described above. In the appropriate project directory, simply type:

  • make flash_openocd” to program a binary file onto the micro.
  • make debug_openocd” to start a debugging session
  • make erase_openocd” to erase the micro’s program memory.
This entry was posted in Free STM32F0 Development Environment. Bookmark the permalink.