Hardware (Optional)

Requirements

• STM32F072B Discovery board + mini-USB cable
• UART to USB adapter

Hardware 

For now, we'll be using STM32 Discovery boards. If you've heard of an Arduino, the Discovery boards are very similar in intention. They're just plug-and-play, no setup required.

To use a Discovery board, just connect the mini-USB cable to the header marked "USB ST-LINK" on the Discovery board and plug the other end into your computer.

For the UART to USB adapter, plug each wire of the adapter into its corresponding pin on the Discovery board.

Running on STM32 - Hello World

In a new terminal (or tmux pane), open a serial terminal:

# If no device is found, try /dev/tty[tab] or /dev/serial/[tab] where [tab] represents pressing the tab key
minicom -D /dev/ttyUSB0

(Note that the minicom baud rate should be set to 115200)

Back to the old terminal:

# Build and run the project on STM32F0xx (discovery board)
# PLATFORM=stm32f0xx is implied
# PROBE=cmsis is normally implied, override for Discovery boards
make program PROJECT=hello_world PROBE=stlink-v2

If you look at minicom, you should see "Hello World" appear. Try changing the text!

Building for STM32 - Hello World

If you don't have access to hardware, no problem! You can still build the project for STM32. It should compile successfully.

# Just build the project for STM32
make build PROJECT=hello_world

As you can see, our build system and HAL (hardware abstraction layer) allow us to build applications that can run natively on mutliple platforms. In this case, LOG_DEBUG is targeted to stdout on x86 (standard output) and UART1 on STM32. This makes testing a lot easier, and allows us to develop application code even without access to the hardware.

Clean Code - Hello World

With your code workring, we want to make sure your code matches our Coding Standards. We use two tools for that:

• clang-format: Reformats code according to our specified style.
• cpplint and pylint: Parses code to find discrepancies between it and our style guide. We actually use our own fork.

Note that these are both just tools, and should not be relied on to be perfect. We have a few rules that would be very difficult to parse, so please try your best to follow our style guide.

# Runs clang-format
make format
# Runs lint.py (cpplint) and pylint
make lint

Committing Changes - Git

Now that your code (hopefully) meets our standards, let's save your work. You should commit your changes relatively often. The goal is to have each commit represent a cohesive chunk of work. Basically, if you hit a point where you think you might want to come back to your work later, you should probably commit.

# Stage all changes
git add .
# Commit staged changes to the local repo
git commit -m "WIP: Adds working hello world project"

This time, we've used the -m argument to add a message directly on the command line. Alternatively, you can use git commit (no -m). This should result in a temporary COMMIT_EDITMSG being opened in your editor of choice. This method is recommended for multiline commit messages.

Notice how the commit message followed the format "WIP: ...". Similarly to branch naming, we follow a convention of "ELEC-[ticket number]: ..." for our commit messages. For example, "ELEC-281: Added part 1 of getting started guides".

Using a version control system (VCS) such as git allows you to keep track of changes over time and revert back if necessary. Feature branches allow you to organize your work and keep different projects separate from each other.

Since git is a distributed VCS, you have a local copy of the repository that needs to be synced with the remote server (GitHub). This means you can commit and make branches without internet access. Normally, we recommend you push your changes to GitHub as often as possible (git push), but since this is a tutorial, we won't bother with that.

Troubleshooting/FAQ

Q: Why can't I see output from the STM32 Discovery board?

A: Make sure you have the FTDI cable connected properly! By default, printf does not do anything on the STM32 (After all, where would it go?). We've decided to redirect it to UART, so we need the FTDI cable to convert it to something your computer can understand. Note that both the Discovery board and FTDI cable need to be connected to your computer. PB6 should be connected to the yellow wire, and PB7 should be connected to the orange wire.

Summary

We covered:

• Basic Git workflow
• Creating a new project
• HAL support for x86 and STM32
• Code cleanliness