At a Glance

...

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

...

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

...

While being at the firmware directory, run make new 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

...

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:

...

Running on STM32

To run on STM32, you need the following pieces of hardware:

Image Added

Connect the Controller Board to you computer according to the picture above. Be sure to short the power lines on the SWD adapter, that ensures that your controller board is getting power from your computer.

Depending on your operating system, you'll need to do different things: 

• Mac OS: Before Catalina
• Windows & Mac OS: Catalina or newer

MacOS (Before Catalina)

Note: If your Mac's Operating System version is older than Catalina, you'll need to do this part. Otherwise, skip to the other section! If you don't know how to check your OS's version, google it! (come on really?) 

On older versions of MacOS for some reason our programmer doesn't get passed into the virtualbox image. To solve that problem, we wrote a script that installs the toolchain on your Mac and SSH's into your Mac every time you want to program a Micro-Controller.  

• Run the macos.sh script on your Mac.

cd ~/box # If box is not in your home directory, delete it and run through module 1 again.
./macos.sh # This installs a whole bunch of stuff

Now let's test to see if you can program the controller board with your laptop. Go on vagrant and flash the example project: 

# ssh into your virtual machine
cd ~/box
vagrant ssh
# go to the firmware repo
cd shared/firmware_xiv/
# program the controller board with the "example" project
make program PROJECT=example

Now the LEDs on the controller board must blink, cute right? If they don't or if you have problems, ask other firmware people or Arshan Khanifar.

Now let's run the hello world program that you just wrote: 

make program PROJECT=hello_world

Nothing happens, right? You'll notice that even the LED's aren't blinking anymore. This is because LOG_DEBUG by default prints to the screen for Linux, but for STM32 we have to tell it where to go, since STM32's don't really have a display on them. We've designed our system so that the output of printf is redirected to the UART interface on our boards. To be able to read the printf message, open another terminal window on your Mac terminal, and list out the devices, and filter them by usb. 

~ ls /dev | grep usbcu.usbmodem143102
tty.usbmodem143102

You can see two devices cu.usbmodem143102 and tty.usbmodem143102. That's because in Unix operating systems serial devices appear on two different names: cu and tty. The reason is beyond this tutorial's scope but you can read here for more info. The exact numbers also may be different on your computer. To listen on the serial port, use minicom: 

minicom -D /dev/tty.usbmodem143102
# trick: type the following, hit tab, then enter
minicom /dev/serial/by-id/

You should see something like this: 

Welcome to minicom 2.7.1

OPTIONS: 
Compiled on Sep 18 2017, 15:01:35.
Port /dev/tty.usbmodem143102, 19:59:33

Press Meta-Z for help on special keys

You're now listening on that port! You don't see "Hello World!" just yet because when you programmed your hello_world program, it simply printed "Hello World!" and exited. So you need to run it again to see it on this window. Now go back to your first terminal window that was in vagrant and run make program again: 

make program PROJECT=hello_world

Now you should see "Hello World!" appear on your minicom window! Yay!

Windows or MacOS (Catalina or newer)

Get in vagrant:

vagrant ssh

Now let's test to see if you can program the controller board with your laptop. Go ahead and flash the example project: 

cd shared/firmware_xiv/
# program the controller board with the "example" project
make program PROJECT=example

Now the LEDs on the controller board must blink, cute right? If they don't or if you have problems, ask other firmware people or Arshan Khanifar.

Now open another Git bash Window and ssh into the box, then list out the devices to see what the device name for the programmer is: 

~ ls /dev | grep CMSIS
tty.CMSIS-DAP

It should return tty.CMSIS-DAP or something like that. Now run minicom  with that device path to listen on the UART interface: 

minicom -D /dev/tty.CMSIS-DAP # --> this should be what the last command showed you!!!!

So now, you should see something like so:

Welcome to minicom 2.7.1

OPTIONS: 
Compiled on Sep 18 2017, 15:01:35.
Port /dev/tty.usbmodem143102, 19:59:33

Press Meta-Z for help on special keys

Now your computer is listening on the UART port for all of the messages that get out of your Microcontroller Board! YAY! Now open another Git bash window, ssh into vagrant, cd into the firmware directory, and then run the application you just created: hello_world 

make program PROJECT=hello_world

YEET! now you should see "Hello World!" on the first terminal window. Talk to other firmware people or Arshan Khanifar if this doesn't work.