Lab 1: FreeRTOS Stopwatch

Prerequisites

Complete Lab 0 Make sure you finished Lab 0 before starting.

Back to Lab Summary Return to the list of all labs.

---

Overview

In Lab 0, you built a stopwatch using a bare-metal while(1) loop. It worked — but what happens when you need to add more features? What if updateDisplay() takes longer than expected? What if you need precise 10 ms timing that never drifts?

In this lab, you will solve these problems by integrating FreeRTOS into your project from scratch. You will not receive a starter template. Instead, you will:

1. Manually set up the FreeRTOS kernel in Code Composer Studio
2. Understand what each kernel file does and why it’s needed
3. Convert your bare-metal stopwatch into a multitasking application
4. Design inter-task communication using queues

This is the most important lab of the course — every future lab builds on the FreeRTOS foundation you create here.

---

Learning Objectives

After completing this lab, you will be able to:

• Explain the role of each FreeRTOS kernel source file and why it’s needed
• Create a CCS project with FreeRTOS integrated manually (not from a template)
• Identify why a bare-metal super-loop breaks down as complexity grows
• Create tasks with appropriate priorities, stack sizes, and periodic scheduling
• Use vTaskDelay and vTaskDelayUntil for non-blocking timing
• Implement queue-based inter-task communication
• Convert a single-threaded application into a task-based architecture

---

Required Materials

• TI EK-TM4C1294XL LaunchPad
• BOOSTXL-EDUMKII BoosterPack
• Micro USB cable for programming and power
• FreeRTOS kernel source code (downloaded in Part 1)

---

Grading Rubric

Step	Task	Description	Points
1	FreeRTOS Integration	Manually set up FreeRTOS in CCS; explain kernel files	10
2	Scheduler Verification	Two-LED blink test proving multitasking works	10
3	Timekeeping Task	Stable ≤10 ms base period using vTaskDelayUntil	15
4	Button Task	Debounced S1 (Start/Pause) and S2 (Reset) via task	15
5	Display Task	Non-blocking UI rendering: HH:MM:SS:MS and state text	15
6	Buzzer Task with Queue	Design and implement a buzzer task that receives commands through a queue	10
	Lab Report	Written report with analysis questions (see below)	25
	Total		100

---

Part 1 — Understanding and Setting Up FreeRTOS

1.1 Read the FreeRTOS Fundamentals Guide

Before writing any code, read the FreeRTOS Fundamentals guide completely. This is not optional — you need to understand why an RTOS exists before you can use one effectively.

FreeRTOS Fundamentals Guide Core concepts: tasks, scheduling, timing, communication. Read this first.

Checkpoint

After reading, you should be able to answer: What problem does an RTOS solve that your Lab 0 super-loop cannot? If you cannot answer this clearly, re-read Section 1 of the guide.

1.2 Download the FreeRTOS Kernel

Download the FreeRTOS kernel source code. Do not use a pre-built library — you will add the source files manually so you understand what each one does.

Download FreeRTOS Kernel Source Download the FreeRTOS kernel to integrate into your project.

1.3 Understand the Kernel File Structure

After extracting the ZIP, examine the contents. You should see a structure like this:

• FreeRTOS.h
• FreeRTOSConfig.h
• startup_ccs.c
• DirectoryFreeRTOS/

  • Directoryinclude/

    • FreeRTOS.h
    • task.h
    • queue.h
    • semphr.h
    • …
  • Directoryportable/

    • DirectoryCCS/

      • DirectoryARM_CM4F/

        • port.c
        • portasm.asm
    • DirectoryMemMang/

      • heap_4.c
  • tasks.c
  • queue.c
  • list.c
  • timers.c
  • …

Know Your Files

Before proceeding, make sure you understand the purpose of each group of files:

• tasks.c, queue.c, list.c — The kernel core. These implement task management, queues, and the internal linked-list data structure.
• portable/CCS/ARM_CM4F/ — The hardware-specific port layer. port.c and portasm.asm handle context switching for the ARM Cortex-M4F.
• portable/MemMang/heap_4.c — The memory allocator. FreeRTOS needs a heap for dynamic allocation of task stacks and kernel objects.
• FreeRTOSConfig.h — Your project’s configuration. This file controls tick rate, stack sizes, which features are enabled, and more.
• startup_ccs.c — The vector table. This file maps FreeRTOS handlers (like vPortSVCHandler and xPortPendSVHandler) to the correct interrupt vectors.

Report Question 1: In your report, explain in your own words what port.c and portasm.asm do. Why does FreeRTOS need processor-specific code?

1.4 Create Your CCS Project and Integrate FreeRTOS

Follow the FreeRTOS Project Setup guide step by step. You will create a new empty CCS project and manually add the kernel files.

FreeRTOS Project Setup Guide Step-by-step checklist to add FreeRTOS to your CCS project.

Common Mistakes

• Do not copy the FreeRTOS kernel folder into your project — link it instead. This avoids duplicating source files.
• Replace the default tm4c1294ncpdt_startup_ccs.c with the provided startup_ccs.c. The default one does not have FreeRTOS interrupt handlers.
• Set the C system stack size to at least 2048 in Linker settings. FreeRTOS needs this for the initial startup before the scheduler takes over.

FreeRTOSConfig.h — Your Project's Control Panel

Open FreeRTOSConfig.h and examine its contents. Key settings you should understand:

Setting	Purpose
configCPU_CLOCK_HZ	Must match your system clock (120 MHz)
configTICK_RATE_HZ	Scheduler tick frequency — how often the OS checks for ready tasks
configMINIMAL_STACK_SIZE	Default minimum stack size in words (not bytes)
configTOTAL_HEAP_SIZE	Total RAM available for FreeRTOS dynamic allocations

Report Question 2: What is configTICK_RATE_HZ set to in your project? If you call vTaskDelay(pdMS_TO_TICKS(10)), how many ticks is that? What happens if you set configTICK_RATE_HZ too low (e.g., 10 Hz)?

---

Part 2 — Verify the Scheduler (Two-LED Test)

Before building the stopwatch, you need to confirm FreeRTOS is actually running. Create a simple test with two tasks that blink two different LEDs at different rates.

2.1 What to Implement

If you are not familiar with how to use the on-board LEDs (GPIO configuration, GPIOPinWrite, etc.), review the Blink Example first:

Blink Example Example project showing how to configure GPIO and toggle LEDs on the TM4C1294XL.

Create a main.cpp file with:

1. Standard system initialization (disable interrupts, enable FPU, configure 120 MHz clock)
2. Enable GPIO Port N for the on-board LEDs (D1 = PN0, D2 = PN1)
3. Two FreeRTOS tasks: one toggles D1 every 2 seconds, the other toggles D2 every 200 ms
4. Start the scheduler

Include FreeRTOS headers in C++

If your file is .cpp, wrap FreeRTOS includes in extern "C" to prevent C++ name mangling:

extern "C" {
#include "FreeRTOS.h"
#include "task.h"
}

2.2 Task Structure Pattern

Every FreeRTOS task follows the same pattern. Study this structure — you will use it for every task in this lab and all future labs:

void MyTask(void *pvParameters) {
    // === One-time setup (runs once when task starts) ===

    // === Periodic loop ===
    for (;;) {
        // Do work here

        vTaskDelay(pdMS_TO_TICKS(period_ms));
    }
}

Use xTaskCreate() to register each task with the scheduler. You need to specify: the task function, a name string, stack size (in words), parameters, priority, and an optional handle.

Hints

• Use GPIOPinWrite() to toggle LEDs
• pdMS_TO_TICKS() converts milliseconds to scheduler ticks
• Both tasks can have the same priority for this test
• Stack size of 128 words is sufficient for simple LED tasks

2.3 Verification

Flash and run. You should see:

• D1 (PN0): Toggling every 2 seconds (slow blink)
• D2 (PN1): Toggling every 200 ms (fast blink)

If both LEDs blink at their respective rates, FreeRTOS is running and scheduling multiple tasks. This is a fundamental difference from bare-metal — in your Lab 0 approach, you couldn’t have two independent timing loops without managing them manually.

Troubleshooting

If the LEDs don’t blink:

• Check that you replaced the default startup file with startup_ccs.c
• Verify the linker stack size is at least 2048
• Check for unresolved symbols like vPortSVCHandler — this means the startup file is wrong
• Make sure vTaskStartScheduler() is called after creating tasks

Demonstrate this working to a TA before moving on.

---

Part 3 — Build the Stopwatch Task by Task

Now you will convert your Lab 0 stopwatch into a FreeRTOS application. Instead of one while(1) loop doing everything, you will split the work into four independent tasks.

Architecture Overview

Think about what your Lab 0 stopwatch did in its main loop:

1. Track elapsed time (every ~10 ms)
2. Scan buttons and handle debouncing (every ~20 ms)
3. Update the display (every ~50 ms)

In FreeRTOS, each of these becomes a separate task with its own priority and timing. You will also add a fourth task for buzzer feedback.

┌─────────────────────────────────────────────────────────┐
│                    FreeRTOS Scheduler                    │
├──────────┬──────────┬───────────┬───────────────────────┤
│ Time     │ Display  │ Buttons   │ Buzzer                │
│ Task     │ Task     │ Task      │ Task                  │
│ (high)   │ (medium) │ (low)     │ (low)                 │
│          │          │           │                       │
│ Updates  │ Reads    │ Scans HW  │ Receives queue        │
│ counters │ globals  │ buttons,  │ commands,             │
│ every    │ and      │ updates   │ drives PWM            │
│ ≤10ms    │ redraws  │ state     │ for duration          │
│          │ LCD      │           │                       │
└──────────┴──────────┴───────────┴───────────────────────┘
         Shared state: volatile globals
         Communication: FreeRTOS queue (buttons → buzzer)

Important — Add Libraries First

You need the button, joystick, and display libraries from Lab 0. Download them and add them to your project.

No more elapsedMillis or Timer

In Lab 0, you used the Timer and elapsedMillis classes to manage periodic timing in your main loop. You will no longer need these. FreeRTOS replaces all of that functionality:

• Instead of elapsedMillis checks → use vTaskDelay() or vTaskDelayUntil() inside each task
• Instead of hardware Timer for time base → FreeRTOS uses SysTick automatically (configured via configTICK_RATE_HZ)
• Instead of polling in a super-loop → each task has its own periodic loop managed by the scheduler

Do not include timerLib.h or elapsedTime.h in this project. All timing is now handled by FreeRTOS primitives.

Download Libraries Download libraries needed for the lab.

Importing External Libraries Instructions for importing external libraries into your project.

Overflow Issues

If your previous stopwatch had overflow issues (e.g., only counting up to 35 seconds), check this guide for a solution using hierarchical accumulators.

Fixing the Stopwatch Overflow Using hierarchical accumulators to prevent overflow in stopwatch timing.

3.1 Shared State and Priorities

Before writing tasks, plan your shared data. Globals that are read and written by multiple tasks (or tasks and ISRs) must be declared volatile so the compiler doesn’t optimize away accesses.

/* Shared stopwatch state */
volatile bool     gRunning = false;
volatile uint16_t g_ms  = 0;
volatile uint8_t  g_sec = 0;
volatile uint8_t  g_min = 0;
volatile uint8_t  g_hr  = 0;

Why volatile?

Without volatile, the compiler may cache a variable in a register and never re-read it from memory. If another task changes that variable, the first task would never see the update. Later in the course, you’ll learn more robust approaches (mutexes, queues), but volatile is sufficient for this lab’s simple shared state.

Priority Assignment: Think about which task is most timing-critical and assign priorities accordingly. The timekeeping task must never miss a tick — it should have the highest priority. The display task should be responsive but can tolerate small delays. Button scanning and buzzer feedback are less time-critical.

You decide the exact priority values. Use tskIDLE_PRIORITY + N where higher N means higher priority.

Report Question 3: Explain your priority assignment. What would happen if the display task had the highest priority and took 40 ms to render a frame? How would this affect timekeeping accuracy?

3.2 Timekeeping Task (Step 3)

This task replaces the if (stopwatchTick >= 10) check from your Lab 0 main loop. It should:

• Run periodically at 10 ms or less
• Increment milliseconds, rolling over into seconds, minutes, and hours
• Only count when gRunning is true

vTaskDelay vs. vTaskDelayUntil

For the timekeeping task, timing accuracy matters. Consider the difference:

• vTaskDelay(period) — delays from the moment the call is made. If the task took 2 ms to execute, the total period is 2 + delay ms.
• vTaskDelayUntil(&lastWakeTime, period) — delays from the last wake time. The total period is exactly period ticks, regardless of execution time.

Which one should you use for timekeeping? Think about it, implement your choice, and justify it in your report.

Report Question 4: Which delay function did you use for the timekeeping task and why? What is the difference in timing behavior between the two?

3.3 Button Task (Step 4)

This task handles scanning physical buttons S1 and S2, debouncing them, and updating the stopwatch state.

Requirements:

• Scan buttons periodically (every ~20 ms is typical)
• Debounce both S1 and S2
• S1 toggles between Running and Stopped
• S2 resets all time counters to zero
• When a button event occurs, also notify the buzzer task (you’ll implement this in Step 6)

Design It Yourself

You already implemented button handling in Lab 0. Now adapt that logic to work inside a FreeRTOS task. Think about:

• Where does one-time button initialization go?
• Where does periodic scanning go?
• How do you structure the infinite loop?

Do not use blocking delays (SysCtlDelay, busy-wait loops) inside tasks. Only use vTaskDelay or vTaskDelayUntil.

3.4 Display Task (Step 5)

This task reads the shared stopwatch state and renders it on the LCD.

Requirements:

• Update the display periodically (target ~20 FPS, i.e., every ~50 ms)
• Show time in HH:MM:SS:MS format
• Show state text: Running or Stopped
• Must be non-blocking — use RTOS delays, never busy-wait

Avoiding Flicker

A common mistake is clearing the entire screen every frame. This causes visible flicker. Instead, only redraw the parts that changed, or redraw over the previous text with the background color first, then draw the new text.

Stack Size Consideration

Display tasks use more stack than simple LED tasks because of local buffers (e.g., char str[32] for snprintf), graphics library calls, and function nesting. A stack of 512 words (2048 bytes) is a reasonable starting point. If you get a hard fault, try increasing the stack size.

3.5 Buzzer Task with Queue (Step 6)

This is the most interesting task because it introduces inter-task communication. Instead of calling a buzzer function directly from the button task, you will send a command through a FreeRTOS queue, and a separate buzzer task will consume and execute it.

Why use a queue?

Think about these problems:

1. If the button ISR calls Buzzer_Start() directly, the ISR is blocked for the entire beep duration — other interrupts are delayed.
2. If the button task calls Buzzer_Start() and then vTaskDelay() for the beep duration, the button task can’t scan buttons during that time.
3. What if two button presses happen quickly? Without a queue, the second beep would be lost.

A queue solves all three problems. The sender (button task) posts a command and immediately continues. The receiver (buzzer task) processes commands one at a time, blocking only itself.

If you are not familiar with how to configure PWM for the buzzer hardware, review the Buzzer Example first. It shows how to initialize PWM0 on PF1 and generate tones at a given frequency:

Buzzer Example Example project showing PWM buzzer configuration and tone generation on the TM4C1294XL.

Adapt, Don't Copy

The buzzer example uses SysCtlDelay() (a blocking busy-wait) for the beep duration. You must not do this in a FreeRTOS task. Instead, use vTaskDelay() so other tasks can run while the buzzer is active. Extract the PWM initialization and start/stop logic, but replace the delay mechanism.

What you need to design:

1. A command structure — What information does the buzzer task need to produce a beep? At minimum: frequency and duration.

2. A queue — Created before the scheduler starts. How many items should it hold? What is the item size?

3. The buzzer task — An infinite loop that:

   • Blocks on xQueueReceive() waiting for a command
   • When a command arrives, starts PWM at the requested frequency
   • Delays for the requested duration using vTaskDelay() (not SysCtlDelay)
   • Stops PWM
   • Loops back to wait for the next command

4. A send function — Called from the button task (or anywhere else) to post a command to the queue without blocking.

FreeRTOS Queues Guide How queues work and when to use them.

FreeRTOS Queues API Reference Official API documentation for xQueueCreate, xQueueSend, xQueueReceive.

Implementation Hints

• Use xQueueCreate() to create the queue. Send data by value (the queue copies the struct).
• Use xQueueSend() with a timeout of 0 (don’t block) from the sender.
• Use xQueueReceive() with portMAX_DELAY (block forever) in the buzzer task.
• Use short beep durations (20–50 ms) and moderate frequencies (2–5 kHz) for crisp feedback.
• You can use different frequencies for S1 vs S2 to distinguish the sounds.

Report Question 5: Draw a diagram showing how data flows from a button press to the buzzer producing sound. Label each FreeRTOS primitive used (task, queue, etc.). What would happen if the queue is full when a new command is sent with timeout 0?

---

Part 4 — Integration and Testing

Once all four tasks are implemented:

1. Build and flash your project. Fix any compilation errors.
2. Test the scheduler — Do both LEDs from Part 2 still work? (You can remove the LED tasks or keep them for debugging.)
3. Test timekeeping — Let the stopwatch run for several minutes. Does it drift? Compare against a phone timer.
4. Test buttons — Press S1 rapidly. Does it always toggle correctly? Press S2 during running — does it reset cleanly?
5. Test the buzzer — Press S1 and S2. Do you hear distinct beeps? Press both quickly — are both beeps produced?
6. Test responsiveness — While the stopwatch is running, is the display smooth? Do buttons respond immediately?

---

Expected Results

By the end of this lab:

• The project builds and launches the FreeRTOS scheduler without faults
• Stopwatch displays time in HH:MM:SS:MS with smooth updates
• S1 toggles Start/Pause; S2 resets; UI reflects state text
• Button presses produce short audible feedback via the buzzer queue
• No blocking delays anywhere — all timing uses RTOS primitives
• Code is modular and organized: separate functions/files for each task

---

Lab Report (25 points)

Your lab report must be written in clear, professional English. It should include:

Required Sections

1. Introduction (2 pts) — Briefly describe the purpose of the lab and what you accomplished.

2. System Architecture (5 pts) — Include a diagram showing all tasks, their priorities, communication mechanisms (queues, shared variables), and timing relationships. Explain your design decisions.

3. Analysis Questions (13 pts) — Answer the following questions thoroughly:

   • Q1 (3 pts): Explain in your own words what port.c and portasm.asm do. Why does FreeRTOS need processor-specific code? What would need to change if you ported your project to a different processor?

   • Q2 (2 pts): What is configTICK_RATE_HZ set to in your project? If you call vTaskDelay(pdMS_TO_TICKS(10)), how many ticks is that? What happens if configTICK_RATE_HZ is set to 10 Hz — can you still achieve 10 ms timing?

   • Q3 (3 pts): Explain your priority assignment for all four tasks. What would happen if the display task had the highest priority and took 40 ms per frame? Describe the specific impact on timekeeping.

   • Q4 (2 pts): Which delay function (vTaskDelay vs vTaskDelayUntil) did you use for the timekeeping task? Explain the behavioral difference and justify your choice.

   • Q5 (3 pts): Draw a data-flow diagram showing how a button press results in a buzzer beep. Label every FreeRTOS primitive. What happens if the queue is full when a new command is sent with timeout 0?

4. Conclusion (2 pts) — What was the most challenging part of this lab? Compare the bare-metal approach (Lab 0) vs. the RTOS approach (Lab 1) — what are the trade-offs?

5. Code quality (3 pts) — Is your code well-organized, properly commented where necessary, and modular?

---

Submitting Source Code

Exporting project:

1. Make sure your project is named ece3849_lab1_<username>.
2. Right-click the project in CCS → Export... → General → Archive File.
3. Choose the output path and filename equal to the project name (ece3849_lab1_<username>.zip).
4. Upload the .zip file and your lab report PDF to Canvas.

---

Useful References

FreeRTOS API Reference Official index of all RTOS API functions.

Task Creation Guide How to create and manage tasks in FreeRTOS.

FreeRTOS Queues Guide Inter-task communication with queues.

Programming Style Guide Code organization and C/C++ best practices.