Reading Time: 10-15 minutes
Most Firmware tasks (with the exception of some infra related tasks) need to be tested on PCBs (Printed Circuit Boards).
We write code in C that is meant to run on an MCU (Micro Controller Unit) and utilize its computing power to do various tasks. This document provides generally useful flows and tips related to testing your Firmware on a board. Specific instructions like how to build, how to flash, and how to use PuTTy are in more detailed guides - many are linked on this document.
Please note some useful terms below:
NOTE: You do not need to look into these in depth, but you should know what these terms generally mean in order to understand the nuances of testing with hardware; versus a very local software environment. Additionally, terms that are more custom to our team will be marked with (!)
| Term | Meaning |
|---|---|
| Cross Compiling | The process of compiling code on a host device (e.g. your laptop) that is meant to be executed on a target device (microcontroller). In our case, we cross compile using CMake, and are left with an OBC-firmware.out file. This is in contrast to regular compiling, as we are not compiling code on the same device architecture that we are planning to run the code on (e.g. Python and C labs in programming courses). |
| Flashing | The process of “loading” your executable file into the microcontroller’s flash memory. This follows compiling, and must be done so that your code can be accessed and run by the microcontroller |
| Development Board | These are PCBs that are ideal for testing firmware, as they are stocked by market vendors. This is in contrast to our custom PCBs, which are made in-house by Orbital, as more people have tested and verified market boards. |
| OBC (!) | On Board Computer. This refers to the board hosting our microcontroller. Variations include the Launchpad (development board that contains an RM46), and the various OBC Rev boards (e.g. OBC Rev 1, OBC Rev 2) which are made by the team. Though OBC boards all have the RM46, they may have different peripherals on the board. |
| FreeRTOS | This is the RTOS we use to manage resources and code execution on our microcontroller. All firmware (except for the Bootloader) is run on top of the RTOS. You should be somewhat familiar with FreeRTOS through the onboarding (please revisit the FreeRTOS guides whenever you feel like it would benefit you) |
We will now look into the general process for testing.
How do you get your code to run on the board and see output to confirm that it’s working?
To unit test functions, and to test drivers, you can set up an example RTOS file. See examples of these at:
https://github.com/UWOrbital/OBC-firmware/tree/main/obc/examples
If you can’t access the link, visit the repository and navigate to obc/examples.
What these files do is make an isolated RTOS task, which can then be built and flashed on the board (as opposed to the regular firmware). These files are solely for testing and are not a part of the main firmware. This is easier for testing opposed to having multiple tasks competing to run (which can make testing messy).
A lot of these files have the same template, so I recommend copy pasting from one (e.g. test_app_adc/main.c) and adjusting it for your purposes. You will have to change the includes, and some config based on your task; but the overall format is the same.
To see how to build an isolated RTOS example file, refer to the final section of this document
The main way we view output is by sending messages through SCI/UART to the host device and seeing them through PuTTy (see how we call sciPrintf() in multiple example files). Essentially think of it as equivalent to doing print() to a console when testing a Python program, but with extra hardware steps (e.g. we call a function we wrote to get a reading from a sensor in the FreeRTOS task, then we can retrieve it, and write the value over SCI/UART and then view it from PuTTy on the host device to confirm that we are interfacing with the sensor correctly).
Finally, for certain tasks you will need to test with the overall system. This is more complicated, but it can be tackled by reasoning about what your code should change and figuring out some way to visualize/observe that the change is occurring.