diff --git a/README.md b/README.md index d373be5..fc3a04f 100644 --- a/README.md +++ b/README.md @@ -1,26 +1,18 @@ # SAMWISE Flight Computer Code -For now intended to be run on a Raspberry Pi Pico (RP2040 based) as a dev board. - -## IDE Setup -We strongly recommend using VSCode in combination with the pi pico extension for development. -See the pi pico getting started guide for how to get setup. +Flight computer firmware for the SAMWISE 2U cubesat. Designed for the Raspberry +Pi RP2040 and RP2350 microcontrollers. ## Getting Started -Referecnce `main.c` for the program entry point. - -## Core Design Principles -* The ability to perform reliable OTAs, and maintain two independent copies of software is a key requirement -* The codebase will use the blackboard pattern - different components will edit one central state object. -* No heap allocation after init time - buffers must be statically sized and allocated at init time. -* Flight vs non-flight builds are distinguished by a single symbol - to configure a flight build, define the `FLIGHT` symbol in `macros.h`. Other parts of the codebase that need different behavior in test and flight builds should check this symbol (`#ifdef FLIGHT` or `if (IS_FLIGHT) ...`). -* Where possible, try to explicitly check for errors (to avoid weird undefined C behavior). -## Style Guidelines -* Comments abve functions in the `.c` files, minimal `.h` files -* Doxygen comments for functions +See [the onboarding doc](docs/ONBOARDING.md) for development environment setup. -(feel free to fight me on the clang format settings) +## Design Objectives -Started by Niklas Vainio, 2024/08/23 -Stanford SSI Satellites 2024 \ No newline at end of file +Beyond functional parity with the prior CircuitPython-based Sapling firmware, +this project has a few additional goals: +* Reliable OTAs +* Use the [blackboard pattern](https://en.wikipedia.org/wiki/Blackboard_(design_pattern)) +* Eliminate heap allocations +* Simple flight/debug configuration +* Clean code \ No newline at end of file diff --git a/docs/ONBOARDING.md b/docs/ONBOARDING.md new file mode 100644 index 0000000..d246d78 --- /dev/null +++ b/docs/ONBOARDING.md @@ -0,0 +1,267 @@ +# Sat Software Onboarding + +Welcome to software! We put code **in space**!! + +# Part -1: History + +First, some context. + +Long ago, SSI designed a CubeSat "framework" called the PyCubed. It was great, +because it was a "commercial off-the-shelf" satellite, meaning we could build it +quickly and reliably. + +While much of the original design had changed up until this year, one design +decision stuck with us: CircuitPython for our flightcode. + +Over time, the benefits of Python as a language began to pale in comparison to +its costs: implicit heap allocations caused random (catastrophic) errors, lack +of proper interrupt support meant lots of polling, lack of explicit static +memory allocation made the aforementioned heap allocations worse, etc. + +This year, we decided to finally pivot and ***rewrite all flight +software in C***. + +We *also* switched microcontrollers from the SAMD51 (which was mostly hidden +from us by CircuitPython) to the lovely RP2350 (A.K.A. the Raspberry Pi Pico 2). + +What does that mean for ***you***? Lots of opportunity to build on what you +learned in CS 106A, 106B, 107, 107E, etc. etc. and build some **real satellite +flight code**. Not only is this a *great* learning experience, but it's +**great** on a resume! SSI software alumni have gone on to NASA, SpaceX, and +grad school ;) + +Today we're going to be building a blinking LED. That sounds trivial, but it's a +good way to get all the tools you need set up. + +# Part 0: Install + +### MacOS + +You will need to use the terminal to install some programs. If you are not +familiar with a terminal, I recommend first installing [Visual Studio +Code](https://code.visualstudio.com/). Then, you should use the VS Code +integrated terminal (tutorial +[here](https://code.visualstudio.com/docs/terminal/basics)). Ubuntu has a neat +[tutorial](https://ubuntu.com/tutorials/command-line-for-beginners#4-creating-folders-and-files) on terminal usage - ignore the Ubuntu specific stuff. + +Install Homebrew if you don't already have it: +``` +/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" +``` + +After installin Homebrew, close and re-open your terminal. + +Install CMake & compiler toolchain: +``` +brew install cmake +brew install --cask gcc-arm-embedded +``` + +Again, after installing both, close and re-open your terminal. + +### Linux + +For [ubuntu/linux](https://askubuntu.com/questions/1243252/how-to-install-arm-none-eabi-gdb-on-ubuntu-20-04-lts-focal-fossa), ARM recently +changed their method for distributing the tool change. Now you +must manually install. As of this lab, the following works: + + wget https://developer.arm.com/-/media/Files/downloads/gnu-rm/10.3-2021.10/gcc-arm-none-eabi-10.3-2021.10-x86_64-linux.tar.bz2 + + sudo tar xjf gcc-arm-none-eabi-10.3-2021.10-x86_64-linux.tar.bz2 -C /usr/opt/ + +We want to get these binaries on our `$PATH` so we don't have to type the +full path to them every time. There's a fast and messy option, or a slower +and cleaner option. + +The fast and messy option is to add symlinks to these in your system `bin` +folder: + + sudo ln -s /usr/opt/gcc-arm-none-eabi-10.3-2021.10/bin/* /usr/bin/ + +The cleaner option is to add `/usr/opt/gcc-arm-none-eabi-10.3-2021.10/bin` to +your `$PATH` variable in your shell configuration file (e.g., `.zshrc` or +`.bashrc`), save it, and `source` the configuration. When you run: + + arm-none-eabi-gcc + arm-none-eabi-ar + arm-none-eabi-objdump + +You should not get a "Command not found" error. + +If gcc can't find header files, try: + + sudo apt-get install libnewlib-arm-none-eabi + +### Windows + +Unfortunately, I have not gotten to fully supporting Windows. The best option is +to install the [compiler toolchain](https://developer.arm.com/downloads/-/gnu-rm) & [CMake](https://cmake.org/download/) according to their respective websites. + +# Part 1: Blinking LED + +All microcontrollers come with some pins you can turn on and off, communicate +over, etc. These pins are called *general purpose input/output pins* or GPIO +pins. You can configure them from software. + +Generally, these are the steps: +- Initialize the pin +- Set the direction (input or output) of the pin +- Write (if it's output) or read (if it's input) from the pin + +Some GPIO pins are connected to physical wires on the board, whereas others are +routed to built-in components. For this example, we are going to use pin 25, +which is routed to an LED on the board. This magic number is provided with a +convenient name in the SDK: `PICO_DEFAULT_LED_PIN`. + +Microcontrollers also come with some timing facilities. For now, all we need to +use is the sleeping methods, which are exactly like the ones from Python. + +## Git + +You should create a clone of [this tepository](https://github.com/shetaye/ssi-onboarding-24/tree/main) using VSCode +(or a git client of your choice). If you are using VSCode, they provide a +[tutorial](https://code.visualstudio.com/docs/sourcecontrol/intro-to-git) on how +to do this. + +The rest of this guide takes place from within this folder/repository. + +To download the SDK, you need to run +``` +git submodule update --init +``` +from within the cloned repository (e.g. `ssi-onboarding-24`). You will need to +do this once per clone. You should see a bunch of files appear in `pico-sdk/`. + +You also need to run the same command within the `pico-sdk` directory: + +``` +cd pico-sdk +git submodule update --init +``` + +## Code + +Put this in `main.c` +```c +#include "pico/stdlib.h" + +int main() { + gpio_init(PICO_DEFAULT_LED_PIN); + gpio_set_dir(PICO_DEFAULT_LED_PIN, GPIO_OUT); + while (1) { + gpio_put(PICO_DEFAULT_LED_PIN, 0); + sleep_ms(250); + gpio_put(PICO_DEFAULT_LED_PIN, 1); + sleep_ms(1000); + } +} +``` + +## Building + +We use **CMake** to build our project. It is like Makefiles for Makefiles. +Honestly, it isn't pretty, but it works quite well! CMake needs to be aware of +all your source files. Each source file is tied to a single *executable* that +CMake will build. + +For this example, all you need to do is go to `CMakeLists.txt` and replace `# +FIXME #` with the name of the c file you put all the prior code into. + +In a terminal (e.g. the integrated VSCode terminal), make a new directory called +`build` (at the same level as `CMakeLists.txt` and `main.c`). + +Your directory structure should look like: + +``` +ssi-onboarding-24/ + build/ + CMakeLists.txt + main.c + README.md + +``` + +Because of the way we have configured CMake, there is one weird step. Run these +commands: + +``` +mkdir -p ~/.pico-sdk/cmake +touch ~/.pico-sdk/cmake/pico-vscode.cmake +``` + +Now, enter `build`, then initialize CMake: + +``` +cd build/ +cmake .. +``` + +Re-run `cmake ..`, and keep repeating this process while pop-ups happen. + +Once `cmake ..` has finished, run the following from within `build`: +``` +make +``` + +You should now have a file at +``` +ssi-onboarding-24/ + build/ + onboarding.uf2 +``` + +You will repeat the `cd build/`, `cmake ..`, and `make` steps every time you want to make changes + +## Uploading + +Unplug your pi, hold the button on your pi, plug it in, then move +`build/onboarding.uf2` into the drive that shows up. The light should start to +blink! + +# Part 1.5: Github + +Now we're going to write code within the actual SSI codebase. + +## Git + +We will get each of you set up on the GitHub. If you don't already have an +account, make one [here](https://github.com). + +If you have no or little experience with Git, I recommend installing [Github +Desktop](https://desktop.github.com/download/). We will be running a special +onboarding session for Git later on. + +## Repository + +Clone *this* repository via whatever Git client you want + +# Part 2: Scheduler + +The flight software is organized into a state machine. The satellite can be in +any of several states e.g. "running," "low power," etc. + +Each state is associated with tasks that are run regularily (e.g. every half a +second) while the satellite is in that state e.g. the running state might be +associated with a "beacon" task. + +If a task is associated with the active state, its `task_dispatch` function is +called at most every `dispatch_period_ms` milliseconds. Additionally, its +`task_init` function is called as part of satellite boot. + +You will also see references to a "slate." The slate is a huge block of +statically allocated memory. + +For this part, you are going to write your own task. + +## Code Navigation + +The scheduler code is located in `scheduler/`. It isn't necessary for this part, +but it might be interesting to you. + +The state machine is located in `state_machine/`, with tasks in +`state_machine/tasks` and states in `state_machine/states`. There is a README in +`state_machine` that explains how to add new tasks and states. + +## Your task + +Make it do whatever you want! \ No newline at end of file diff --git a/docs/datasheets/README.md b/docs/datasheets/README.md new file mode 100644 index 0000000..a07c1b6 --- /dev/null +++ b/docs/datasheets/README.md @@ -0,0 +1,7 @@ +# Component Datasheets + +| Description | Document | Source | +|---|---|---| +| RP2040 Microcontroller | [rp2040-datasheet.pdf](rp2040-datasheet.pdf) | [Raspberry Pi](https://datasheets.raspberrypi.com/rp2040/rp2040-datasheet.pdf) | +| RP2350 Microcontroller | [rp2350-datasheet.pdf](rp2350-datasheet.pdf) | [Raspberry Pi](https://datasheets.raspberrypi.com/rp2350/rp2350-datasheet.pdf) | +| RFM95/96/97/98(W) - Low Power Long Range Transceiver Module | [RFM9X.pdf](RFM9X.pdf) | [Sparkfun](https://cdn.sparkfun.com/assets/learn_tutorials/8/0/4/RFM95_96_97_98W.pdf) | \ No newline at end of file diff --git a/docs/datasheets/RFM9X.pdf b/docs/datasheets/RFM9X.pdf new file mode 100644 index 0000000..f8d1848 Binary files /dev/null and b/docs/datasheets/RFM9X.pdf differ diff --git a/docs/datasheets/rp2040-datasheet.pdf b/docs/datasheets/rp2040-datasheet.pdf new file mode 100644 index 0000000..4c5c9db Binary files /dev/null and b/docs/datasheets/rp2040-datasheet.pdf differ diff --git a/docs/datasheets/rp2350-datasheet.pdf b/docs/datasheets/rp2350-datasheet.pdf new file mode 100644 index 0000000..1795558 Binary files /dev/null and b/docs/datasheets/rp2350-datasheet.pdf differ