Module 2: Hello World

Owned by Titus Chow
Last updated: Feb 08, 2022 by Jarvis Weng

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

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_xiv
# 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 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

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!

Running on STM32

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

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.