diff --git a/docs/course/appendix-1.md b/docs/course/appendix-1.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/course/component-implementation.md b/docs/course/component-implementation.md new file mode 100644 index 0000000..f7208de --- /dev/null +++ b/docs/course/component-implementation.md @@ -0,0 +1,43 @@ +# Component Implementation + +Now it is time to write code! F´ implements components using C++ and as we saw in the design section, this +implementation typically involves filling-in template files allowing us to focus on the specific challenges at-hand. + +## Setup + +Before proceeding with implementation, we should add our `Imu.cpp` file created in the design step to the +`CMakeLists.txt` file in the `Imu` directory. The new `CMakeList.txt` file should look like this: + +```cmake +set(SOURCE_FILES + "${CMAKE_CURRENT_LIST_DIR}/Imu.fpp" + "${CMAKE_CURRENT_LIST_DIR}/Imu.cpp" + ) +register_fprime_module() +``` + +## Component Implementation + +F´ generates a series of handler functions for us to respond to each type of call. We need to fill in our specific logic +for each of these empty handlers. Additionally, F´ creates a series of helper functions that may be called to send +telemetry, emit events, and call output ports. + +To build our implementation we run `fprime-util build` while in the `Imu` folder. Run this now to ensure that the cmake +system is configured correctly for the component. Feel free to re-run the `build` command to check for compiler errors +or other problems as you build. + +Let's take a look at one specific handler `TODO`. + +**Note:** some helper functions for working with the specifics of the Imu are available in [Appendix I](./appendix-1.md) +and are useful for developers who are less familiar with C++ and working with hardware. Feel-free to use these helpers +in your code, or write your own! + +A full implementation of the component is available [here](../../SystemReference/Gnc/Imu/Imu.cpp) and the associated +header is available [here](../../SystemReference/Gnc/Imu/Imu.hpp). + +## Next Steps + +- [Topology Integration and Testing](./topology-integration.md) + + + diff --git a/docs/course/hardware.md b/docs/course/hardware.md new file mode 100644 index 0000000..ac6a19e --- /dev/null +++ b/docs/course/hardware.md @@ -0,0 +1,9 @@ +# Hardware Setup + +In order to complete the lab exercise we need to wire-up hardware. In this exercise we will be using the Raspberry PI 3 +and the MPU-6050 IMU. The wiring can be completed according to the following guide. Specifically, we need to wire the +MPU-6050 into the Raspberry PI's IMU bus (pin 3 and 5) as well as power and ground (pin 1 and 6). + +## TODO link to wiring diagram + + diff --git a/docs/course/introduction.md b/docs/course/introduction.md new file mode 100644 index 0000000..ec6902c --- /dev/null +++ b/docs/course/introduction.md @@ -0,0 +1,58 @@ +# Introduction + +This document will describe the use of the F´ system reference as a reference for the flight software workshop. We will +explore flight software through the lens of F´ and this exercise. In the exercise, we will integrate the +[MPU-6050 IMU](https://learn.adafruit.com/mpu6050-6-dof-accelerometer-and-gyro) into our F´ project with the goal of +generating telemetry. + +Please try to cover the prerequisite section (below) before attending the class. The other sections we'll cover during +the exercise portion of the class. + +- [Hardware Setup](./hardware.md) +- [Requirements and Design](./requirements-and-design.md) +- [Component Implementation](./component-implementation.md) +- [Unit Testing](./unit-testing.md) +- [Topology Integration and Testing](./topology-integration.md) +- [Appendix I: Code Snippets](./appendix-1.md) + + +## Prerequisites + +In order to run code on the reference hardware, we need the ability to cross-compile for the given target architecture. +Since students may be running any number of different laptops, we have placed the tools needed to cross-compile in a +Docker container, and we will run the class using this docker container. This means each student's laptop needs to be +setup to run Docker and our container. + +**Note:** it is entirely possible to run cross-compilation on a Linux laptop without docker by installing F´ as +discussed in the F´ [installation guide](https://nasa.github.io/fprime/INSTALL.html) and installing the 32-bit ARM gcc +package. However, it would be on the attendee to ensure this is set up and working prior to the class as instructor time +to help is limited. + +In order to set this up, follow these steps: + +1. Ensure that "git" is installed on your computer +2. Install [Rancher Desktop](https://rancherdesktop.io/) or another software to running docker containers locally + 1. When presented with a "Welcome to Rancher Desktop" dialog, choose the following settings: + 1. Disable Kubernetes + 2. Select `dockerd` + 3. Configure PATH Automatic + + ![Rancher Config](../img/rancher-config.png) +3. Pull the F´ Docker Raspberry PI Docker Container + 1. Run `docker pull nasa/fprime/fprime-raspi:devel` + 2. Check docker container: `docker run -it nasa/fprime/fprime-raspi:devel` +4. Clone the F´ System Reference + 1. Run `git clone https://github.com/fprime-community/fprime-system-reference` + 2. Checkout the "XYZ" branch `git checkout XYZ` +5. Test the docker container and code + 1. To start the container run `docker run --net host -it -v /path/to/fprime:/project nasa/fprime/fprime-raspi:devel` + 2. Generate an F´ build `cd SystemReference` then `fprime-util generate` + 3. Build F´ `fprime-util build` + 4. Run F´ GDS `fprime-gds` and open a browser to `https://localhost:5000` + 5. You should now see a GUI with a green circle in the upper right corner. Congratulations, F´ is running. + +## TODO, callout running the docker container, generating, and building + +## Next Steps + +- [Hardware Setup](./hardware.md) \ No newline at end of file diff --git a/docs/course/requirements-and-design.md b/docs/course/requirements-and-design.md new file mode 100644 index 0000000..9a515cd --- /dev/null +++ b/docs/course/requirements-and-design.md @@ -0,0 +1,153 @@ +# IMU Exercise: Requirements and Design + +When developing flight software and using F´ it is important to start the development of a component ny laying out the +requirements of that component and generating a design of that component of that component. In this portion of the +exercise we will walk through both of these steps. + +F´ formalizes the design of the component using the FPP modeling language. This allows us to take the design (called a +model in FPP parlance) and generate code that performs much of the work within that component. This greatly simplifies +the implementation later on. + +## Preparation + +In order to prepare to specify a design we need to do some folder setup. First, make sure to have followed the class +[prerequisites](./introduction.md#prerequisites) including starting the docker container and running generating the F´ +build cache. + +Next, move the existing IMU folder out of the way as we will be replacing it with our own design. We'll replace it with +a basic folder with and initial `CMakeList.txt` file inside. + +**On Unix Systems** +```bash +cd fprime-system-reference/SystemReference/Gnc +mv Imu Imu.reference +mkdir Imu +``` + +Finally, add the following `CMakeLists.txt` to that new folder. The new file must be named exactly `CMakeLists.txt` and +exist in the new Imu folder. + +```cmake +set(SOURCE_FILES + "${CMAKE_CURRENT_LIST_DIR}/Imu.fpp" +) +register_fprime_module() +``` + +We are now setup to generate requirements for our component, codify them into a design, and generate a base +implementation. **Note:** the above directory will not build until after we add the FPP file as noted in the design +section. + + + + + + +## Requirements + +Good requirements capture both the behavior of a component and its interaction with other components within the system. +Requirements should also capture necessary commands, events, telemetry channels, and parameters for the component. +Additionally, failure and off-nominal behaviors should be captured. + +For this exercise, we can follow the GNC sensor integration guide "Step 1: Define Component Requirements" to determine +the necessary requirements for the IMU. This section can be found +[here](../integration/gnc-sensor-integration.md#step-1-define-component-requirements). + +In order to check the requirements we defined, let's compare with the requirements published in the IMU's SDD found +[here](../../SystemReference/Gnc/Imu/docs/sdd.md). Note here, we have defined a command, several events, telemetry +channels, and defined error conditions. + +## Design + + + +In F´ the design of the component needs to be formally captured in a model. To do this, we write an FPP file. The design +should fall out from the requirements previously captured. Generally, if there are aspects of the design that do not map +to requirements, this is an indication that the requirements may be incomplete and should be revisited. + +For this exercise, we will follow the [design section](../integration/gnc-sensor-integration.md#step-2-component-design) +of the GNC sensor integration guide. We need to make sure to capture the commands, events, telemetry, parameters, and +ports of the IMU in our FPP model. + +Go ahead and construct an FPP file in your `Imu` directory called `Imu.fpp`. Below is a template you can use to get +started. Notice we chose a module of `Gnc` which will result in the Imu being part of the `Gnc` namespace. + +```fpp + +module Gnc { + passive component Imu { + # ---------------------------------------------------------------------- + # General ports + # ---------------------------------------------------------------------- + + @ Port to send telemetry to ground + guarded input port Run: Svc.Sched + ... + + # ---------------------------------------------------------------------- + # Special ports + # ---------------------------------------------------------------------- + + @ Port for emitting events + event port Log + + @ Port for emitting text events + text event port LogText + + @ Port for getting the time + time get port Time + + @ Telemetry port + telemetry port Tlm + + # ---------------------------------------------------------------------- + # Events + # ---------------------------------------------------------------------- + + @ Event where error occurred when requesting telemetry + event TelemetryError( + status: Drv.I2cStatus @< the status value returned + ) \ + severity warning high \ + format "I2C request failed with status {}" \ + throttle 1 + + ... + + # ---------------------------------------------------------------------- + # Telemetry + # ---------------------------------------------------------------------- + + @ X, Y, Z acceleration from accelerometer + telemetry accelerometer: Vector id 0 update always + + ... + } +} +``` +**Note:** your design may differ slightly from the example above. Fill in the `...` sections with other parts of your +design. The system reference [IMU model](../../SystemReference/Gnc/Imu/Imu.fpp) can be used as a reference to compare +our design against. + +## Generating Implementation Templates + +The key advantage of using FPP as a design language is we can now generate the basic implementation of our component. +Run the following commands, and you'll see what we mean: + +```bash +cd fprime-system-reference/SystemReference/Gnc/Imu +fprime-util impl +mv ImuComponentImpl.cpp-template Imu.cpp +mv ImyComponentImpl.hpp-template Imu.hpp +``` + +These template files contain fill-in functions that allow us to implement the logic for the IMU without needing to focus +on all the boilerplate code needed to make the `Imu` work with the rest of the system. + +## Next Steps + +- [Component implementation](./component-implementation.md) + +## Additional Resources + +-[FPP User Guide](https://fprime-community.github.io/fpp/fpp-users-guide.html) \ No newline at end of file diff --git a/docs/course/topology-integration.md b/docs/course/topology-integration.md new file mode 100644 index 0000000..19cf909 --- /dev/null +++ b/docs/course/topology-integration.md @@ -0,0 +1,8 @@ +# Topology Integration and Testing + +The next step in developing our component is to add our component into the system's topology, building it for the RPI, +and running the final code. + +## Topology Integration + +Since this example \ No newline at end of file diff --git a/docs/course/unit-testing.md b/docs/course/unit-testing.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/img/rancher-config.png b/docs/img/rancher-config.png new file mode 100644 index 0000000..1a6b761 Binary files /dev/null and b/docs/img/rancher-config.png differ