At a Glance

Prerequisites

• Same as Module 2

Blinking LED

Now, let's modify the getting_started project to toggle an LED once a second. First, we'll use our Hardware Abstraction Library (HAL). As a refresher, the key purpose of a HAL is to abstract platform details into a common, portable API to allow developers to write high-level application code independently of the underlying hardware.

At this point, you should be familiar with the basics of our build system and flashed your first project. You should also be aware of our Git Workflow and Coding Standards.

# Move to the firmware folder (if you weren't already there)
cd ~/shared/firmware
# Checkout the wip_getting_started branch (just in case)
git checkout wip_getting_started
# Check what branch we're on and if we have any changes
# This should say something along the lines of "nothing to commit, working directory clean"
git status

Controlling an LED - HAL

Let's update getting_started for basic General Purpose Input/Output (GPIO) pin control. We'll assume that our LED is an active-low (turns on when output is 0) and connected to PC9 (port C, pin 9).

// Turns the LED on and sits forever
#include <stdbool.h>
#include "gpio.h"
#include "log.h"

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

  // Init GPIO module
  gpio_init();

  // Set up PC9 as an output, default to output 0 (GND)
  GPIOAddress led = {
    .port = GPIO_PORT_C,  //
    .pin = 9,             //
  };
  GPIOSettings gpio_settings = {
    .direction = GPIO_DIR_OUT,  //
    .state = GPIO_STATE_LOW,    //
  };
  gpio_init_pin(&led, &gpio_settings);

  // Add infinite loop so we don't exit
  while (true) {
  }

  return 0;
}

# Just make we're following the style guide :)
make format
make lint


# Build and flash to the Discovery board
make program PROJECT=getting_started PROBE=stlink-v2

Great! You should see a solid LED on the Discovery board. This is pretty simple.

Blinking an LED - HAL

Let's add a lot more code! Now, we'll use our soft timers to toggle the LED once a second.

// Blink an LED
#include <stdbool.h>
#include "gpio.h"
#include "interrupt.h"
#include "log.h"
#include "soft_timer.h"
#include "wait.h"

#define BLINK_LED_TIMEOUT_SECS 1

// Timeout callback
static void prv_blink_timeout(SoftTimerID timer_id, void *context) {
  GPIOAddress *led = context;
  gpio_toggle_state(led);

  LOG_DEBUG("Toggling LED\n");

  // Schedule another timer - this creates a periodic timer
  soft_timer_start_seconds(BLINK_LED_TIMEOUT_SECS, prv_blink_timeout, &led, NULL);
}

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

  // Initialize our modules
  gpio_init();
  interrupt_init();
  soft_timer_init();

  // Set up the pin
  GPIOAddress led = {
    .port = GPIO_PORT_C,  //
    .pin = 9,             //
  };
  GPIOSettings gpio_settings = {
    .direction = GPIO_DIR_OUT,  //
    .state = GPIO_STATE_LOW,    //
  };
  gpio_init_pin(&led, &gpio_settings);

  // Begin a timer
  soft_timer_start_seconds(BLINK_LED_TIMEOUT_SECS, prv_blink_timeout, &led, NULL);

  // Infinite loop
  while (true) {
    // Wait for interrupts
    wait();
  }

  return 0;
}

# Just make we're following the style guide :)
make format
make lint


# Build and flash to the Discovery board
make program PROJECT=getting_started PROBE=stlink-v2

Woah, there's a lot going on here! Do you understand how everything works?

Code Breakdown - HAL

First, it really helps to have the firmware folder open in your editor so you can reference our source code.

If you look at the headers we've included and their corresponding source files, things will make a lot more sense. We highly recommend looking at each module in-depth.

• stdbool: Part of the C Standard Library. Defines bool, true and false.
• gpio: Used to initialize and read/write GPIO. The read/write functions in this module are digital (i.e. true/false).
• interrupt: Used to initialize interrupts across supported platforms. In this case, we need it for our soft timers.
• log: Defines useful log macros that are retargeted to UART and stdout on STM32 and x86 respectively.
• soft_timer: Software-based timers backed by a single hardware timer. Used to create arbitrary timeouts without consuming all of our hardware timers.
• wait: Attempts to put the CPU to sleep until an interrupt. No-op on x86.

The control flow is relatively simple.

1. Initialize all our modules
2. Initialize the GPIO pin attached to the LED (output)
3. Begin a timer with a callback to toggle the LED
4. Sit in an infinite loop, waiting for the soft timer to timeout
5. On timeout, toggle the LED and start a new soft timer to toggle the LED

A few things to note:

• Most of our digital inputs and outputs are active-low. This means that GND (0V) is true/on and Vcc (3.3V) is false/off.
• Did you notice the //'s and trailing commas in led and gpio_settings? To find out why, look at our Coding Standards. (Hint: It's related to clang-format)
• On a similar note: prv_ as prefix for static functions, snake_case for variables, etc.

Try playing with the code - adjust the timeout, replace wait(), change the LED, add another LED at a different interval, etc.

Cleanup and Commit - HAL

You should know the drill:

# Format and lint!
make format
make lint


# Add all of our changes and commit
# Note that adding main.c would also work.
git add .
git commit -m "WIP: Added blinking LED"

In all honesty, we should've committed our code when we first got a solid LED. The jump from a solid LED to blinking LED is definitely worth a commit.

Blinking LED - Registers

Just for fun, let's take a look at what something like this might look like when accessing registers directly. For this, the STM32F0 reference manual is indespensible. It will tell you everything you'll ever need to know about working with the STM32F0.

This time, we'll dedicate a hardware timer entirely to toggling the LED and forego the ability to run on x86.

#include "stm32f0xx.h"


int main(void) {
  // TODO
  return 0;
}