Page Comparison

...

*One important thing: as you are working through your tasks, you will encounter errors. The leads are happy to answer questions about any of these issues, but most of the time it can be solved by a quick google. 90% of the errors you will encounter can usually be solved with answers from Stack Overflow, and a little bit of thinking.

FW 101 Tasks

There are several tasks that need to be completed as part of this module:

1. Get your environment set up by following the instructions listed at Setup

2. Learn about Git and the Command Line by watching/reading the following tutorials

   1. Git Tutorial Videos (part 1 and 2) and branching lesson

   2. Command Line Tutorials (Part 1 and 2)

...

1. Get your environment set up by following the instructions listed at Setup

2. Write your very own Hello World program!

1. Intro Videos

These videos give an introduction to two of the main tools we use on our team, Git and the shell command line. We suggest watching them if you aren’t very experienced in one or the other, since the rest of the onboarding content will rely heavily on these concepts. However, we also do explain it as we go, so feel free to continue on even if you still haven’t fully grasped the concepts, and use these resources when you get stuck.

2. Setup

Assuming you have followed the steps listed in the setup page, we can now try out your new repository.

Once you’ve got your box set up (you should be in the vagrant environment. If you type whoami in your console it should print vagrant below) and have pulled the fwxv repository, build the can_communication project, we can build and run it on the x86 platform.

We use SCons to compile and build our software. It is generally invoked with arguments which tells it how and what to build. You should now run the following command (fill in the blankin your command line; this will build and then run our “leds” program.

makescons runsim PROJECT=... PLATFORM=...

Once it’s started, take a screenshot and send it to the firmware lead. It should look something like this:

...

--project=leds --platform=x86

You will see a bunch of build output printed to your screen, and then a periodic printing of the word “blink”, something like below:

...

Don’t worry about what anything means, this is just to make sure you’ve got things up and running. We will talk more about scons and building software later.

3. Hello World

This section will cover writing a basic hello world program (using the C language), and running it in the environment we have just set up.

Let’s take a quick look at our fwxv repository before we get started. You can find other information on make commands here: https://github.com/uw-midsun/firmware_xiv#usageTip: press ctrl+C to exit.Type ls in your command line (at the fwxv directory) to list the directory contents. You should see something like the image below:

...

The two main things we care about right now are the projects and libraries items. These are directories, which hold the firmware we write.

Libraries contains the code that is standalone, to be included the main programs we write, using #include "library.h". Some of these libraries we write ourselves, some of them (such as the FreeRTOS source code) we get from other sources. Each library will generally consist of a header file (.h) and a C-file (.c). The header file holds any new data types which are used in library, and declarations for functions the library may provide, and other useful information. The .c file contains the definitions for these functions.

The projects directory is where we write and build our main software which will run. If you are familiar with C programs, you know that they have a “main” function which is where the program starts when it runs. This is in a main.c file for all our projects. The projects directory is where the main file and any other project-specific software lives.

We will start by creating a new project where we will write our hello world program. Luckily, we can run the following command to do it for us! Make sure you are in the fwxv directory, this is where all commands must be called from.

scons new --project=hello_world

This will create a new project with the name “hello_world”. We can view it by listing the projects directory with ls projects. It should look something like this

...

As you can see, there were already a few projects existing, including the leds one that we built and ran earlier. Each project is a directory as well, with the file structure shown below.

project/
├─ src/
│  ├─ main.c
├─ inc/
├─ test/
├─ config.json
├─ README.md

The main file and any other .c files go in the src/ directory, and any header files go in the inc/ directory. The readme is a text file where you can give a description of your project, and the config.json is needed for including external libraries, but we will get to that later.

We need to create a main.c file in our src directory. You can do this from the command-line, or you can open up the fwxv folder in your favourite text editor and do it there (If you don’t have one, VS Code is recommended, but it doesn’t really matter). We then need to open our main.c file for editing.

A C program is comprised of the following main components.

#include <stdio.h>
#include "mylibrary.h" // The library includes

#define BUF_SIZE 10 // Any defined constants or preprocessor directives
static int buf[BUF_SIZE]; // Any static/global declarations

static int prv_my_func(int *input) { // Function declarations/definitions
  *input++;
  return *input; // Increments the value passed and returns it 
}

int main(void) {
  int in = 0;
  int out;
  for(int i = 0; i < BUF_SIZE; i++) {
    out = prv_my_func(&in);
    buf[i] = out;
    printf("In %d, Out %d\n", in, out);
  }
  return 0;
}

As you can see, we have a simple program which increments an integer and stores its value in a buffer array. Using this template, we are now going to write our very own hello world program!

The Program

The goal of this next part is to write a program which increments an integer using a function, and prints it to the console every second along with “Hello world”.

You will need to use a few things from our code base for this project.

1. Include the “log.h” library. We have our own version of printf which allows us to safely print to the console. You can use it the exact same way as printf, just replacing it with LOG_DEBUG, ie:
   LOG_DEBUG("Hello World %d\n", my_int);

2. Include the “delay.h” library. This library allows us to halt the execution of a program for a specified amount of time. Once we have included this library, we can use the function
   delay_ms(uint32_t ms_to_delay) and pass it the number of milliseconds we want to delay for.

This program should run forever in a while true loop.

When you are done, take a screenshot of your output or bring your computer over and show it to a lead. You are officially done FW 101, Congrats!