lestarch: initial course documentation

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)
+
+
+

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
+
+

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)

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)

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