| Step | Description | Points |
|---|---|---|
| 1 | Place the development board on a breadboard | |
| 2 | Install the development software | |
| 3 | Download the Standard Peripheral Library | |
| 4 | Configure SystemWorkbench | |
| 5 | Create a project in SystemWorkbench | |
| 6 | Edit and debug a project | |
| 6.6 | Debug a C program | 40 |
| 6.7 | Debug an assembly program | 40 |
| 7 | Wire a device and try it | 20 |
| Total: | 100 |
When you are ready for your lab evaluation, review this checklist.
Open your ECE 362 lab kit and find the STM32F091RC microcontroller development board. It should look like Figure 1, below. It is a 60-pin board with double-ended pins so that the board can be used in a breadboard as well as used with header connectors that plug in on top. On one end of the development board, there is a 10-pin programming header.
Your ECE Master Lab Kit has a four-panel solderless breadboard similar to this one. Read the user manual to learn how to insert the development board into the breadboard. It should be placed so that the programming header overhangs the side of the board opposite the power connectors. Place it in the second to the bottom panel as shown in Figure 2. The pins labeled "5V" should be in the rightmost columns. Make sure there are two usable breadboard holes on either side of the rows of pins on the board. I.e., center the board within the breadboard panel. We will use this configuration for all labs in the course.
When you insert the board, you may wish to pre-widen the holes into which you will place the development board. Be careful to press down only on the push buttons rather than the more delicate components on the board.
Consult the user manual to determine how to connect the USB programmer to the development board. If you have a programmer with the wrong pin configuration, you will need to connect four wires between the programmer and the development board in the required locations.
As long as the USB programmer pins are connected only to the development board programming header pins, there is little chance of damaging the board. Do not connect the programmer directly to any of the long rows of 30 pins on either side of the development board. That could cause damage. Once the programmer is connected to the programming header, plug the USB programmer into your computer. Use the 3-foot-long USB extension cable if you do not have a USB port near your development board. You should see the red and green LEDs in the corner of the development board illuminate. If you do not see these LEDs, unplug the USB programmer immediately and check your wiring.
For embedded software development within ECE362, the open-source Eclipse IDE will be used, alongside the “System Workbench for STM32” Eclipse plugin (supported by STMicroelectronics). Full instructions for the installation of of this software is OpenSTM32 installation instructions, available on_the OpenSTM32 web site, however you will need to register for the site and log in to see it. While it is possible to install components individually, the lab staff finds that the environment works easiest and best if a pre-integrated system is installed. The following platform-specific instructions will allow you to do that.
Various applications for the lab computers are already installed.
Nevertheless, you must invoke a command to configure your account
to use them. Open a terminal window by right-clicking anywhere
on the desktop. When the terminal window opens type the following:
~ece362/bin/setup
You should see new icons on your desktop. One of them
reruns the "setup" program. You can use this to update your
configuration if any new applications are needed. Another icon is
created for System Workbench, the main application you will use.
The specific version of Linux supported is Ubuntu LTS, and this is the most reliable platform for SystemWorkbench. Other distributions may work, but they may involve additional steps not detailed here. Download the latest version of System Workbench from:
http://www.ac6-tools.com/downloads/SW4STM32/install_sw4stm32_linux_64bits-latest.run
Or use the locally-cached version:
https://engineering.purdue.edu/ece362/f22/lab/install_sw4stm32_linux_64bits-latest.run
Then invoke the installation script with the following command:
bash install_sw4stm32_linux_64bits-latest.run
You will be prompted for installation locations as well as the system password to install the STlink driver configuration. Keep track of the location in the file system that SystemWorkbench and Ac6 are installed. You will refer to them later. Depending on your particular computer, you may need to issue an additional command for the software to work properly:
sudo apt install lib32ncurses5 make
sudo apt install libpython2.7:i386 libncurses5:i386 make
MacOS is the least reliable platform for SystemWorkbench, and many students who try to use it are unable to get it to install or cannot use it once it is installed. Please consult with other students on the Piazza forum to find solutions. A common solution for the installation problem is to install a virtual machine running Linux or Windows and only use SystemWorkbench in the VM.
Download the latest version of System Workbench from:
http://www.ac6-tools.com/downloads/SW4STM32/install_sw4stm32_macos_64bits-latest.run
Or use the locally-cached version:
https://engineering.purdue.edu/ece362/f22/lab/install_sw4stm32_macos_64bits-latest.run
Then invoke the installation script with the following command (in a terminal shell):
bash install_sw4stm32_macos_64bits-latest.run
You will be prompted for installation locations as well as the system password to install the STlink driver configuration. Keep track of the location in the file system that SystemWorkbench and Ac6 are installed. You will refer to them later. The installation script should set up a link on your desktop by which you can invoke System Workbench. If not, invoke it with [the path to the installation directory]/eclipse.
Windows is a reliable platform on which to use SystemWorkbench, but you you should avoid using project names with spaces in them. (e.g., do not create a project with the name "Project 1".)
Download the latest version of System Workbench from:
http://www.ac6-tools.com/downloads/SW4STM32/install_sw4stm32_win_64bits-latest.exe
Or the locally-cached version:
https://engineering.purdue.edu/ece362/f22/lab/install_sw4stm32_win_64bits-latest.exe
Then invoke the installer. You will be prompted for installation locations as well as the system password to install the STlink driver configuration. Keep track of the location in the file system that SystemWorkbench and Ac6 are installed. You will refer to them later.
In the past, the installation for Windows has required an additional ST-Link driver to interact with the USB programmer module. This may or may not still be true. (You can help us decide this.) If you need it, acquire the driver from STMicroelectronics, extract the resulting zip file, and install the driver.
We will use the OpenSTM32 Standard Peripheral Library for most projects in the class. You may not be able to download it from the host site in the next step. If not, download a locally-cached version:
https://engineering.purdue.edu/ece362/f22/lab/stm32f0_stdperiph_lib_v150.zip
You must save the downloaded ZIP file into a particular subdirectory of the "Ac6" installed. The subdirectory is "[The Ac6 installation location]/SW4STM32/firmwares/".
The zip file must be saved with the file name "stm32f0_stdperiph_lib_v150.zip". Unzip the file in that subdirectory to create a new subdirectory named "STM32F0xx_StdPeriph_Lib_V1.5.0". SystemWorkbench will look for both the ZIP file as well as the unzipped version. Both must have exact names.
Now that all software tools needed for the STM32F0 have been installed, the Eclipse environment should be configured for student use. The workspace preferences configuration instructions are heavily based on a set of instructions from the GNU ARM Eclipse community. To access the Eclipse Preferences menu, select Window >> Preferences from the Eclipse main menu.
The first destination is Workspace Preferences, located at General >> Workspace in the Preferences menu. Uncheck the box which says “Build automatically” (in these experiments, the build process will be initiated via a command). Additionally, check the box titled “Save automatically before build”. This is probably the most important setting you can change. Without it, you will be confused why the program you just modified does not act as you expect.
Text encoding and newline delimiters can vary from operating system to operating system, and should be standardized for the purposes of this course. At the bottom of the Workspace preferences pane, there are two fields with radio buttons: “Text file encoding” and “New text file line delimiter”. Ensure that the Text file encoding field is specified as UTF-8, while the New text file line delimiter is specified to use Unix-style endings. (You should not use the "Default (Windows)" even if you are using Windows. Once all of these changes have been made, click Apply. All of these settings are summarized in Figure 4.
Occasionally, source code will have to be printed. When this is done, it is helpful to know where the edge of a page would be, that lines of code can be written of appropriate lengths. Under the preferences hierarchy, navigate to General >> Editors >> Text Editors. In the Text Editors preferences pane, click the box labeled "Show print margin" and ensure that the "Print margin column" field is set to 80. Once these preferences have been made, click Apply.
Certain IDEs, including Eclipse, feature a software tool called an Indexer. An indexer parses source code on the fly, providing hints, auto-completion suggestions, and error reporting to the developer during the process of editing, without having to initiate the build process. In order for the indexer to provide accurate and relevant hints, the indexer must be in sync with the compiler.
In the Preferences menu, navigate to C/C++ >> Indexer. In the field titled "Build Configuration for the Indexer", select the field titled "Use active build configuration". Click Apply.
Eclipse features a powerful integrated code formatter, which is capable of automatically formatting source code files to conform to a particular coding style of choice. Eclipse will automatically adhere to the settings of the code formatter when working on new source files. Alternatively, a file open in Eclipse can be automatically formatted using Source >> Format from the Eclipse main menu.
To modify the formatter settings, navigate to C/C++ >> Code Style >> Formatter. In the resulting pane, a drop down box will appear showing different code formatting styles, as well as a preview of what source code might look like in the resulting style. Select your style of choice, then click the Edit… button. A new window will appear, showcasing code formatter style configuration settings.
The built-in code formatter styles cannot be modified, so press New and a dialog window will open with a field labeled “Profile Name”. Provide a name for the new code formatting style (for the purposes of this exercise, the profile name “ECE362” was used). Choose "K&R C" as a template. To ensure uniformity of code across development environments, set the field labeled Tab Policy to “Spaces Only”, then click OK. You will be returned to the Eclipse Preferences menu. Click Apply.
The build console is a portion of the Eclipse UI which is displayed during the build process. Build console settings can be found under C/C++ >> Build >> Console in the Eclipse Preferences menu.
To ease the build process, check the boxes in the Build Console Preferences pane stating "Bring console to top when building (if present)" and "Wrap lines on the console". Additionally, increase the field "Limit console output (number of lines):" to a higher value, such as 5000. Click Apply.
Now that the software toolchain is configured, it's time to create a simple project for the STM32F0. Connect the STM32F091 development board to the USB programmer, and start SystemWorkbench. A Welcome Screen will appear, which can be closed. Creation of a project is a six-step incremental process of making selections in dialogs to configure the computer language used for a project, the type of microcontroller (target) to be used, and the support software to be used (firmware).
In the top level Eclipse menu, select File >> New >> C Project.
Next, you will arrive at the "Select a wizard" dialog. For the first half of the semester, we will be writing files in assembly language, but we show you how to adapt a C environment to that. Select "C Project" and press Next.
The next dialog is the "C Project" dialog. Specify "Ac6 STM32 MCU Project", specify a Project name ("project1" was used, but you can pick something meaningful such as "lab0") and click Next>.
The next dialog is the "Select Configurations" dialog which allows you to select the build configurations to be used for the project. By default, it shows "Debug" and "Release". We will never use anything other than these, and we will only rarely use "Release". Just press Next to move on.
The next dialog is the "Target Configuration" dialog. It selects the type of microcontroller to use. The microcontroller we will use for the class is the STM32F091RCT6. You should mentally split that up into four parts: STM32F0 91 RC T6. To find that with the dialog, first choose the "Mcu" tab at the top of the dialog. The "Series" is STM32F0 (the default), and the "Mcu" will be found near the bottom of the drop-down list. There is no specific entry for "STM32F091RCT6". Instead, you should use the slightly more generic "STM32F091RCTx". You might temporarily select other microcontrollers on the list and see how it affects the parameters in the box in the center. Make sure you set it back to "STM32F091RCT6" and then press Next.
This is a tedious step, and we'll try to find a way to make this just a little easier to select.
Next, the "Project Firmware configuration" dialog appears to ask you what type of firmware you should use for the project you are creating. For all projects in this course, we will use either "No Firmware" or the "Standard Peripheral Library (StdPeriph)" firmware. For this experiment, choose "Standard Peripheral Library (StdPeriph)". Since this is the first time you have used this firmware type, the dialog will appear as it does on the left of the figure below. It will warn you that the firmware is not installed and prompt you to download it. Press the "Download target firmware" button, accept the license agreement, and wait a few seconds for it to complete. If System Workbench fails to download the StdPeriph firmware, download the locally-cached version as detailed in Step 4.
You only need to download the firmware the first time you use it. Once the firmware is downloaded, the dialog will always appear as it does on the right. Then press Finish.
Eventually, all of these steps necessary to create a project will become automatic for you. You won't even think about it.
Finally we arrive at the main project workspace where we can start manipulating files related to the software project we wish to build. Eventually, you will become accustomed to going through the steps of creating a new project and it will become an automatic action for you. (You will usually create one new project for every prelab, lab, and homework that you write.)
If you click open the "lab0" element in the Project Explorer on the left, you will see the followinga number of top-level folders. Not all of these folders will exist at this point. Some of them will be created after you edit and compile your code.
Double-click on the src folder to open it, then double-click on the main.c file to edit it. The editor window should look similar to the following figure:
System Workbench automatically created this "main.c" file for you. It includes a comment at the top of the window that looks like "* @file main.c" that is folded. If you click on the plus icon near the line number, it will unfold the comment, allowing you to view it.
If you press the hammer icon you will see many messages go by explaining that it is building firmware files and compiling the main.c file to produce an executable. You can run and debug the execution of this simple program on you development board. Before you do so, you must configure the debugger as well as the programming interface.
Select the Run >> Debug configurations… menu item. A dialog will appear. Double-click on the "Ac6 STM32 Debugging" item on the left side of the screen to create a New_configuration entry. Notice that the selection for "C/C++ Application" is empty in your dialog window. Press the "Search Project..." button and select the "lab0.elf" entry that appears. (This is the executable that you just built in the previous step.) The result should look similar to the following picture:
Next, you must configure the programmer interface. While still in the Run >> Debug configurations..., select the "Debugger" tab. Change the button that normally says "Show generator options..." to "Hide generator options..." and, in the information shown below it, change the option that says "Connect under reset" to "Software system reset". Then press Apply and Close.
Why do we need to do this? We're using an inexpensive "clone" ST-LINK programmer that does not have as many features of more sophisticated (and expensive) programmers. This USB programmer does not use the "reset" signal. Instead, it asserts a signal on the SWDIO and SWCLK lines to reset the system it is programming and debugging. We need to change this configuration each time we create a new project. Thereafter, it is remembered for the project, and the settings will be reinstated when the project is reopened.
Note: When you try to program the microcontroller without switching to "Software system reset" SystemWorkbench will respond with one of many error dialogs. When you start the debugger, it may tell you something like "Error erasing flash with vFlashErase packet". When you press the "Run" button, it may show a message on the console at the bottom that says "** Unable to reset target **", wait a minute, and then display a dialog window that says that the microcontroller is not responding. Learn to recognize any of these problems, change the debugger configuration, and continue.
At this point, you will be able to use the programmer and debugger. Before doing so, change the main() function to look like this:
#include "stm32f0xx.h"
int main(void) {
int x = 0;
int y = 0;
for(;;) {
x += 1;
y -= 1;
}
}
When you press the debug icon (the blue bug) below the menu bar, your project code should be rebuilt, the debugger will be invoked, and System Workbench will prompt you to change to a different perspective. Click Yes on the perspective change dialog and accept it as default action. The new perspective for the debugger should look like the following image:
If you do not see the debugger perspective, it could be because the programmer was not wired properly. Check your wiring and compare it carefully to the user manual.
The editor is now reduced to a smaller portion of the screen (highlighted in red). There is now a series of buttons below the menu bar to control the debugger operation (highlighted in green). An information window (highlighted in orange) shows variable values, breakpoints, register contents, and I/O registers. Finally, a perspective selection buttons (highlighted in blue) can be used to switch back to the main editor perspective.
Hover over the debugger control buttons under the menu bar (highlighted in green in Figure 19) to learn their functions before doing the following steps. The controls are as follows:
Note: If you try to start a debug session when the debugger is already running, it will fail with a message that says something like "Error launching debugger". Look for the red square that indicates the debugger is already running. Use that button to "Terminate the debugger" before trying to restart it.
Press the "Terminate debugger (Ctrl+F2)" button, and go back to the "C/C++" Workspace Perspective by clicking on the icon in the upper right corner with a "C" on it. It is next to the "Debug" button (another blue bug icon) in the upper right corner. The view should be restored to it was in Figure 15. On the right is the list of folders, and the src folder contains main.c. Right click (or command-click) on the main.c to bring up a context menu. Select "Resource Configurations" and "Exclude from Build..."
A dialog will appear. Press "Select all" and "OK". Now main.c is grayed out. It is no longer compiled into your program. If you attemted to compile and run the program, an error would appear in the message console that says "undefined reference to 'main'". (Try it.)
Add a new source file by right clicking on the src folder and selecting New >> Source File. When the dialog appears, type the name for "Source file:" as "lab0.s" and choose "<None>" as the template as shown in the figure below. This will be understood by SystemWorkbench to be an assembly language file.
When the (completely empty) lab0.s appears in the editor window, enter the following text into it:
.cpu cortex-m0
.thumb
.syntax unified
.fpu softvfp
.global main
main:
movs r0, #0
movs r1, #0
loop:
adds r0, #1
subs r1, #1
b loop
Invoke the debugger to see how the system works with assembly language instead of C. Now the "Step Into (F5)" or "Step Over (F6)" advance one line at a time. Each line that does not start with a dot is a single machine instruction. Although you have not learned how assembly language works yet, you may recognize that "adds r0, #1" will add one to the R0 register. Click on the "Registers" tab in the information window (the orange highlighted region in Figure 19). As you step through one instruction at a time, notice how the values for general registers R0 and R1 change.
Once you get your program running, ask a TA to check your work. He or she will ask you to exclude the assembly language file and reselect the main.c file. You will then demonstrate that you know how to set breakpoints and step through execution of a C program.
You will then select the main.s file and exclude the main.c file to run the assembly language section. Step through the execution of each instruction and see how the registers are updated by each instruction.
Many times throughout the course for lab experiments and homework assignments, you will be provided with a compiled module that can be used to automatically test the code that you write. Sometimes, it will provide some kind of functionality that we expect you to learn how to do yourself. We don't want to just give you the source code for it.
Download the object file autotest.o and save it into the src folder of your lab0 project. To do this, you will need to learn where the subdirectories exist in your Eclipse/SystemWorkbench workspace. Depending on the computer platform you use, you may be able to copy and paste it.
Next, follow the instructions for integrating the compiled module into your project. For lab 0, the compiled module will act as a device driver that will make the serial port work, collect information about your work, and provide an indication that you completed it.
Change your "lab0.s" module to the following contents:
.cpu cortex-m0
.thumb
.syntax unified
.fpu softvfp
.global main
main:
movs r0,#4
movs r1,#6
movs r2,#5
movs r3,#9
adds r0,r3,r2
subs r1,r3,r1
bl autotest
bkpt
.global login
login:
.asciz "xyz"
.align 2
Change the letters xyz to your ECN login (the username you
use to access the ECE 362 web page). The bl instruction
invokes a subroutine call to a function in the compiled module
named autotest(). This function never
returns, and you will not be able to examine its source code. The
function looks at the login symbol to find out
what your login is, and it will print it on the serial port, along
with other information.
You may try to use the debugger to step through the program to see what each instruction does. Once it reaches the bl autotest instruction, it will no longer show the source code. This is because the autotest.o module is not compiled to provide debug information. You can still see the instructions that it executes.
You will use this serial port wiring on all subsequent labs. Ensure that your breadboard is clear of other wiring. You will incrementally add things as the semester goes on.
Consult the documentation on the FTDI USB-to-serial adapter page. Be sure to set the adapter for 3V operation. Then wire the serial port as follows:
Let your TA check your wiring before you plug in the USB cable to ensure that you will not damage anything. He or she will check that the adapter is set for 3.3 V operation and that the Rx and Tx pins are connected to the proper microcontroller pins. Connect a USB cable between the adapter and your computer so that you can interact with the serial port system.
On the lab computer, there is an icon labeled "Serial Port". When you click on it, a terminal window opens and attaches to the USB-to-serial adapter port. The terminal window will show the serial port output. Typing on the keyboard sends input to the serial port.
If you are using your own computer, follow the USB-to-serial adapter page instructions for setting up a terminal program and watching the output. Set the terminal for a baud rate of 115200 and an 8-bit word with no parity.
Invoke the assembly language program on the microcontroller to call the autotest subroutine. It will produce output on the serial port.
Here are the things you need to get checked for this lab: