At a Glance

Goal

In this module you'll be making a simple hello world application. You can either run this application on your virtual machine, or on a micro-controller. Running in a micro0controller requires hardware.

Prerequisites

• Our development environment
• some basic knowledge of git

Hello World

With our development environment set up, let's make a basic project! First we need to ssh into our virtual machine!

# Double check - make sure you're in vagrant
vagrant ssh

To check if we're in the virtual machine, run whoami.

# Should say "vagrant"
$ whoami
vagrant

Now we navigate to the firmware repository and create a new branch for our getting_started project.

cd ~/shared/firmware
# Create a new branch off of master
git checkout master
git checkout -b wip_getting_started

Our first step is creating a new branch, wip_getting_started. Normally, in our development workflow, we create new feature branches for each JIRA issue with the naming convention of elec_[ticket number]_[shortname]. In this case, we'll be using wip_ as a prefix instead of elec_[ticket number]_.

By convention, we use lower snake case for most of our naming schemes. For example, these documents were created under elec_281_add_basic_docs. This lets us keep our work organized. See our Git Workflow for more information.

Creating a New Project

While being at the firmware directory, run the following command: 

# Initialize the directory structure for a new project named "hello_world"
# See projects/README.md for more information on how our projects work
make new PROJECT=hello_world

With our branch created, we initialize our new project hello_world. You should see a new folder at projects/hello_world.

In your favorite editor, create a new file main.c in hello_world/src. We advise opening the firmware folder as a project or workspace in your editor supports that.

#include "log.h"

int main(void) {
  LOG_DEBUG("Hello World!\n");

  return 0;
}

You should have the following directory structure:

projects/hello_world/
├── inc
├── rules.mk
├── src
│   └── main.c
└── test


3 directories, 2 files

You'll notice that make new also created a rules.mk. This file is what identifies the folder hello_world as a project to our build system. Please refer to the projects readme for more information.

Running Code - Hello World

Now, it's time to build and run the project!

# Build and run the project on x86
make run PROJECT=hello_world PLATFORM=x86

Neat! Hopefully, you saw "Hello World" appear in your terminal. Now, if you have the hardware set up, let's try it on STM32!

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