README update

README.md

@@ -1,6 +1,19 @@
-# The ROMEO Flight Software
+# ROMEO Onboard Software (OBSW)
+## What is ROMEO?
 
 [For a broader introduction and documentation refer to the OBSW Wiki in the ROMEO Knowledge Base](https://openproject.mm.intra.irs.uni-stuttgart.de/projects/romeo-phase-c/wiki/obsw). This README gives a very brief introduction and aims to document the compile process for experienced developers.
+[_Research and Observation in Medium Earth Orbit (ROMEO)_](https://www.irs.uni-stuttgart.de/en/research/satellitetechnology-and-instruments/smallsatelliteprogram/romeo/) is the third small satellite of the Institute of Space Systems (IRS), University of Stuttgart with the objective of technology demonstration in Medium and Low Earth Orbit (MEO/LEO) with a mission duration of 1 year. 
+
+The Onboard Software (OBSW) is written in Rust for run-time stability. The implemented framework is losely based on the C++ Flight Software Framework (FSFW) developed at the IRS in cooperation with industry. The shift to Rust was discussed in Paul Nehlich's master thesis: [_Analysis and preparation of the transformation of the Flight Software Framework from C++ to Rust_](https://www.researchgate.net/publication/372439213_Analysis_and_preparation_of_the_transformation_of_the_Flight_Software_Framework_from_C_to_Rust).
+
+![ROMEO Preliminary Design](romeo_design_from_website.bmp)
+(design from IRS ROMEO Website)
+
+## How to Configure This Repository? TODO
+
+
+# First Stage Bootloader (FSBL)
+FSBL code is at https://github.com/Xilinx/embeddedsw/
 
 ## Scope
 This is the central repository for the flight software of the ROMEO satellite.
@@ -60,20 +73,38 @@ docker build -t compile_fsbl .
 docker run -v ./embeddedsw:/fsbl compile_fsbl /bin/bash -c "cd lib/sw_apps/zynq_fsbl/src && make BOARD=zed SHELL=/bin/bash"
 ```
 
+## Requirements [TBC]:
+1. `cmake`
+2. `arm-none-eabi-gcc`
+3. `doxygen` 
+4. `graphviz`
 If you want, copy the fsbl.elf to the docker/compile_fsbl directory for easier access:
 ```sh
 cp embeddedsw/lib/sw_apps/zynq_fsbl/src/fsbl.elf .
 ```
 
+## Steps
+1. Configure doxygen:
 
 ## mission_rust
 
 ##### Build the docker image:
 ```sh
+export DOT_PATH=/usr/local/bin
+```
+2. Satisfy Rust requirements 
+```sh
+cd ../mission_rust
+cargo update 
+rustup toolchain install nightly
+rustup component add rust-src --toolchain nightly-x86_64-unknown-linux-gnu
+rustup override set nightly
+cargo build -Z build-std
 cd docker/compile_mission/
 docker build -t compile_mission .
 ```
 
+3. Configure the ROMEO OBSW repository in `.../obsw/`
 ##### To build the mission_rust, run the following command in the `docker/compile_mission` directory:
 ```sh
 docker run -v $(pwd)/../../mission_rust:/mission_rust compile_mission /bin/bash -c "cargo build -Z build-std"
@@ -100,18 +131,17 @@ docker run -v $(pwd)/../..:/obsw compile_obsw /bin/bash -c "mkdir -p build_cli &
 ```
 
 The romeo-obsw binary can now be found in the `build_cli` directory.
+# Debugging on `zedboard`
+`zedboard` is the `Xilinx Zynq-7000` development board. 
+## Requirements [TBC]:
+- `OpenOCD`
+- `arm-none-eabi-gdb` 
 
-
-
-# Debugging on zedboard
-
-Requirements [TBC]:
-- OpenOCD
-- arm-none-eabi-gdb
-
-Set Zedboard boot mode to jtag and connect debugging PC to zedboard jtag and uart usb port.
-
-On PC connected to zedboard jtag usb port:
+## Steps
+TODO: discuss this with paul
+1. Set Zedboard `boot mode` to JTAG and connect debugging PC to zedboard JTAG and UART USB port.
+TODO: what is which port, use distinct name/add a graphic
+2. On PC connected to zedboard JTAG USB port:
 ```sh
 openocd -f board/digilent_zedboard.cfg
 ```
@@ -121,7 +151,7 @@ If you have one around, load bitstream at startup (go get a coffee, takes time w
 openocd -f board/digilent_zedboard.cfg -c "init" -c "pld load 0 system.bit"
 ```
 
-To use JTAG Boot for the obsw, you first need to run the FSBL once.
+3. To use JTAG Boot for the OBSW, you first need to run the FSBL once.
 
 On build PC (adapt IP if different from debugging PC) in the folder where you build the FSBL as above:
 ```sh
@@ -132,14 +162,14 @@ arm-none-eabi-gdb fsbl.elf
 >^C^D^D
 ```
 
-You can automate this run:
+### (Optional) Automate this run:
 ```sh
 arm-none-eabi-gdb fsbl.elf -iex "target extended-remote localhost:3333" -ex "set pagination off" -ex "load" -ex "break FsblHandoffJtagExit" -ex "cont" -ex="set confirm off" -ex "exit"
 ```
 
 It will exit after the Zynq is configured and ready to firmware.
 
-Then load the actual obsw, in the build (`build_cli` in the example above) folder run:
+Then load the actual OBSW, in the build (`build_cli` in the example above) folder run:
 ```sh
 arm-none-eabi-gdb romeo-obsw
 >target extended-remote localhost:3333
@@ -147,9 +177,9 @@ arm-none-eabi-gdb romeo-obsw
 >cont
 ```
 
-Again, cli commands can be moved to the gdb call. Also, a small function is used as marker to return from gdb if the mission code returns (should not happen in production but might be useful during testing).
+Again, `Command Line Interface (CLI) commands` can be moved to the GNU Debugger (DGB) call. Also, a small function is used as marker to return from GDB if the mission code returns (should not happen in production but might be useful during testing).
 ```sh
 arm-none-eabi-gdb romeo-obsw -iex "target extended-remote localhost:3333" -ex "set pagination off" -ex "load" -ex "break done" -ex "cont" -ex="set confirm off" -ex "exit"
 ```
 
-Uart usb port should output something at 115200baud, (I use moserial to monitor).
+UART USB port should output something at `115200baud`, (I use moserial to monitor).