Skip to content

Commit 4e12e3d

Browse files
jhhocsjhhocs
authored
docs: Updated documentation (#5)
1 parent fdd2511 commit 4e12e3d

File tree

11 files changed

+434
-36
lines changed

11 files changed

+434
-36
lines changed

‎README.md‎

Lines changed: 36 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -1,34 +1,36 @@
1-
# fprime-zephyr-reference F' project
2-
3-
A reference deployment built on the Zephyr RTOS.
4-
5-
**F´:** https://fprime.jpl.nasa.gov
6-
**Zephyr RTOS:** https://docs.zephyrproject.org/latest/index.html
7-
8-
Installation Steps (See https://docs.zephyrproject.org/latest/develop/getting_started/index.html):
9-
10-
0. Source your preferred Virtual Environment `python3 -m venv fprime-venv` then `. ./fprime-venv/bin/activate`
11-
1. Update submodules `git submodule update --init --recursive`
12-
2. Install Packages: `brew install gperf ccache qemu dtc libmagic wget openocd` or `apt install gperf ccache dfu-util device-tree-compiler wget xz-utils file xz-utils make gcc gcc-multilib g++-multilib libsdl2-dev libmagic1`
13-
3. `git submodule update --init --update`
14-
4. `pip install -r requirements.txt`
15-
5. `cd lib/zephyr-workspace && west update && west zephyr-export && west packages pip --install` Note: may take a while
16-
6. Install Zephyr SDK: https://docs.zephyrproject.org/latest/develop/toolchains/zephyr_sdk.html#toolchain-zephyr-sdk
17-
7. Build: `cd fprime-zephyr-reference/ReferenceDeployment && fprime-util generate && fprime-util build`
18-
8. Flash onto board: `cd` into `build-artifacts` directory and run `teensy_loader_cli -v -mmcu=TEENSY41 -w zephyr.hex` for **Teensy41** or for **Raspberry Pi Pico**, put the Pico into bootloader mode by holding down the BOOTSEL button while connecting it to your computer via USB, then drag `zephyr.uf2` into the drive that appears
19-
9. Open GDS: `cd` into the project directory and run `fprime-gds -n --dictionary ./build-artifacts/zephyr/fprime-zephyr-deployment/dict/ReferenceDeploymentTopologyDictionary.json --communication-selection uart --uart-baud 115200 --output-unframed-data -`
20-
21-
---
22-
### Common Trouble-shooting
23-
* If it seems to be a Zephyr issue, run `west update`
24-
* When changing boards
25-
* Update `settings.ini` to the new board
26-
* Update `prj.conf` to the new board's Device PID and VID configurations
27-
* Run `fprime-util generate -f` to generate new build files
28-
* Run `fprime-util build` to build the new project
29-
* **Zephyr Supported Boards**: https://docs.zephyrproject.org/latest/boards/index.html#
30-
* Remember to ensure new build is successful before flashing onto board
31-
* For debugging using **FDTI** cable, see relevant pinout, https://microcontrollerslab.com/ftdi-usb-to-serial-converter-cable-use-linux-windows/
32-
33-
34-
1+
# fprime-zephyr-reference project
2+
This project is an implementation of F` on Zephyr RTOS.
3+
4+
<!-- Not sure if this will be true in the future -->
5+
<!-- > [!Note]
6+
> This deployment by default builds for the Teensy 4.1 development board and has been verified on macOS and on Windows 11 using WSL (Ubuntu 22.04 LTS).
7+
> -->
8+
9+
## System Requirements
10+
- F Prime System Requirements listed [here](https://fprime.jpl.nasa.gov/latest/docs/getting-started/installing-fprime/#system-requirements)
11+
- Zephyr dependencies listed [here](https://docs.zephyrproject.org/latest/develop/getting_started/index.html#install-dependencies)
12+
- Minimum required **CMake version: 3.27.0**
13+
14+
## Prerequisites
15+
1. Follow the [Hello World Tutorial](https://fprime.jpl.nasa.gov/latest/tutorials-hello-world/docs/hello-world/)
16+
2. Follow the [Zephyr Getting Started Guide](https://docs.zephyrproject.org/latest/develop/getting_started/index.html). Ensure that the Zephyr's dependencies and SDK have been installed
17+
3. If you are using WSL, make sure to refer to the [WSL Notes][wsl-notes] docs
18+
19+
## Table of Contents
20+
1. [Initial Project Setup][initial-setup]
21+
2. [Building, Flashing, and Running the Deployment][build-flash-run]
22+
23+
## Additional Resources
24+
- [Using a Custom Board Configuration][custom-board]
25+
- [Tested Board List][board-list]
26+
- [Troubleshooting][troubleshooting]
27+
- [WSL Notes][wsl-notes]
28+
29+
<!-- Links -->
30+
[initial-setup]: ./docs/main-content/initial-setup.md
31+
[board-dependencies]: ./docs/main-content/board-dependencies.md
32+
[build-flash-run]: ./docs/main-content/build-flash-run.md
33+
[custom-board]: ./docs/additional-resources/specifying-board-configuration.md
34+
[board-list]: ./docs/additional-resources/board-list.md
35+
[troubleshooting]: ./docs/additional-resources/troubleshooting.md
36+
[wsl-notes]: ./docs/additional-resources/wsl-notes.md

‎docs/additional-resources/board-list.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
# Install Board Specific Dependencies
2+
3+
In order to upload software to a board, additional steps may need to be taken depending on the board you are using.
4+
5+
## List of Tested Boards
6+
The following boards were able to successfully deploy this reference deployment. The upload guide contain setup and flashing instructions for specific boards.
7+
8+
| Board Name | Chip | Toolchain | Date Tested | Board Config | Upload Guide | Notes |
9+
| ----------------- | ----------------- | ------------- | ------------- | ------------- | --------------------- | ---------------------------- |
10+
| teensy41 | ARM Cortex-M7 | teensy41 | 08/01/2025 | supported | [README][teensy] | |
11+
| NUCLEO-H723ZG | ARM Cortex-M7 | nucleo_h723zg | 08/01/2025 | supported | [README][stm32] | Requires two USB Connecitons |
12+
13+
14+
15+
16+
<!-- Links -->
17+
[stm32]: ../uploading/stm32/stm32.md
18+
[teensy]: ../uploading/teensy.md

‎docs/additional-resources/specifying-board-configuration.md‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
# Specifying Zephyr Board Configuration
2+
This reference deployent can be used for any board running zephyr so long as the correct zephyr board configuration is provided.
3+
4+
## Update the Zephyr West Configuration File
5+
6+
If your board is supported by Zephyr, the config file in `./lib/zephyr-workspace/.west/` may need to be updated in order to install the correct board configurations. This deployment by default only installs the board configurations for hal_nxp boards.
7+
8+
The following is an example of a configuration for stm32 boards.
9+
```ini
10+
# In fprime-zephyr-reference/lib/zephyr-workspace/.west/config
11+
[zephyr]
12+
base = zephyr
13+
14+
[manifest]
15+
path = zephyr
16+
group-filter = -hal,-debug
17+
project-filter = -.*,+hal_stm32,+cmsis,+cmsis_6
18+
```
19+
20+
More information on West Configuration files can be found [here](https://docs.zephyrproject.org/latest/develop/west/config.html)
21+
22+
> [!TIP]
23+
> If your board is supported by Zephyr and you are unsure how to set up the configuration file, a temporary solution is to remove the config file and running `west update` to install all board configurations.
24+
25+
## Using Custom Board Configurations
26+
27+
<!-- Commented out for now. Not sure if this will confuse users -->
28+
<!-- Using a custom board configuration may require updating the CMakeLists.txt file depending on where the board folder is loacted. This example appends the board root of a board that in another directory/repository.
29+
30+
```cmake
31+
list(APPEND BOARD_ROOT "${CMAKE_CURRENT_SOURCE_DIR}/lib/fprime-stm32h7-zephyr")
32+
```
33+
34+
Make sure to update the path to match the location of your custom board configuration if needed. More information on creating custom board configurations can be found on zephyr's official documentation [here][custom-board-config]. -->
35+
Information on creating custom board configurations can be found on zephyr's official documentation [here][custom-board-config]
36+
37+
## Update the settings.ini File
38+
In order to specify the board to build for, update the `BOARD` option in the `settings.ini` file to the correct board name.
39+
40+
41+
```ini
42+
# In fprime-zephyr-reference/settings.ini
43+
BOARD=nucleo_h723zg # Example for the NUCLEO-H723ZG (existing zephyr support)
44+
BOARD=teensy41 # Example for the Teensy 4.1 (existing zephyr support)
45+
```
46+
47+
A list of supported boards can be found [here](https://docs.zephyrproject.org/latest/boards/index.html#).
48+
49+
## Update prf.conf
50+
Different boards may have different USB PID and VID configurations. Update the following atrributes to your board's PID and VID configurations.
51+
52+
```ini
53+
# In fprime-zephyr-reference/prj.conf
54+
CONFIG_USB_DEVICE_VID=<VID>
55+
CONFIG_USB_DEVICE_PID=<PID>
56+
```
57+
58+
# Return to the [Initial Setup Documentation][initial-setup]
59+
60+
<!-- Links -->
61+
[initial-setup]: ../main-content/initial-setup.md
62+
[custom-board-config]: https://docs.zephyrproject.org/latest/hardware/porting/board_porting.html

‎docs/additional-resources/troubleshooting.md‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Troubleshooting
2+
3+
## General
4+
5+
## Linux
6+
7+
## macOS
8+
9+
## Windows/WSL
10+
### WSL can't detect my USB ports
11+
WSL does not natively install USB drivers. Refer to the guide [here][wsl-notes] for installation instructions
12+
13+
## Zephyr
14+
15+
## Additional Resources
16+
- [General F` Troubleshooting](https://fprime.jpl.nasa.gov/latest/docs/getting-started/installing-fprime/#troubleshooting)
17+
18+
19+
<!-- Links -->
20+
[wsl-notes]: ./wsl-notes.md

‎docs/additional-resources/wsl-notes.md‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
# WSL (Windows 11) Notes
2+
WSL natively does not have access to USB devices. To flash the board properly and allow the GDS to communicate with the deployment board via UART over USB, follow these one-time steps.
3+
4+
1. On Powershell as administrator, install and run **usbipd-win**:
5+
Run Powershell as administrator
6+
```sh
7+
winget install dorssel.usbipd-win
8+
```
9+
10+
2. On Powershell find your USB device:
11+
```sh
12+
usbipd list
13+
```
14+
> [!Note]
15+
> You should see two STM32 devices listed with different BUSID's. One corresponds to the USB PWR and the other to USER USB.
16+
17+
3. On Powershell bind both devices to USBIPD in two seperate commands (as administrator):
18+
```sh
19+
usbipd bind --busid <BUSID_USB_PWR> --wsl
20+
```
21+
22+
```sh
23+
usbipd bind --busid <BUSID_USER_USB> --wsl
24+
```
25+
26+
5. On WSL confirm visibility of USB device:
27+
```sh
28+
ls /dev/ttyACM*
29+
```
30+
> [!Note]
31+
> On WSL, the device will usually appear as /dev/ttyACM0. You can check using ls /dev/ttyACM*

‎docs/main-content/build-flash-run.md‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
# Building, Flashing, and Running the Reference Deployment
2+
3+
This guide assumes that the initial setup steps have been completed, and will walk through the steps of building, flashing, and running the reference deployment. This deployment implements an LED blinker component that is able to communicate with the fprime-gds.
4+
5+
## Building the Deployment
6+
> [!Note]
7+
> This step can be skipped if the setup.sh script is run. However, any changes made will require you to run `fprime-util build` and may require `fprime-util generate`
8+
9+
1. In order to build the ReferenceDeployment application, or any other F´ application, we first need to generate a build directory. This can be done with the following commands:
10+
11+
```sh
12+
# In fprime-zephyr-reference (fprime-venv)
13+
fprime-util generate
14+
```
15+
16+
2. The next step is to build the ReferenceDeployment application's code.
17+
```sh
18+
# In fprime-zephyr-reference (fprime-venv)
19+
fprime-util build
20+
```
21+
22+
## Flashing the Board
23+
24+
Different boards will likely require different steps to flash software onto the board. Instructions for tested boards are provided [here][board-list] The following is an example of flashing the deployment onto a stm32 board.
25+
26+
```sh
27+
# In fprime-zephyr-reference
28+
29+
# Linux/Windows WSL
30+
sh ~/.arduino15/packages/STMicroelectronics/tools/STM32Tools/2.3.0/stm32CubeProg.sh -i swd -f build-fprime-automatic-zephyr/zephyr/zephyr.hex -c /dev/ttyACM0
31+
32+
# MacOS
33+
sh ~/Library/Arduino15/packages/STMicroelectronics/tools/STM32Tools/2.3.0/stm32CubeProg.sh -i swd -f build-fprime-automatic-zephyr/zephyr/zephyr.hex -c /dev/cu.usbmodem142203
34+
```
35+
36+
> [!Note]
37+
> Change `/dev/ttyACM0` (`/dev/cu.usbmodem141203` for MacOS) to the correct serial device connected to the device. To find the correct serial port, refer to thie documentation [here](https://github.com/ngcp-project/gcs-infrastructure/blob/d34eeba4eb547a5174d291a64b36eaa8c11369c8/Communication/XBee/docs/serial_port.md)
38+
39+
> [!Note]
40+
> Two USB connections may be required depending on the board configuration. USB PWR is used to power and flash the development board and access the debug terminal, USER USB is used to connect to the F Prime GDS
41+
42+
## Running the Deployment
43+
44+
The following command will spin up the F' GDS as well as run the application binary and the components necessary for the GDS and application to communicate.
45+
46+
```sh
47+
# In fprime-zephyr-reference (fprime-venv)
48+
fprime-gds -n --dictionary ./build-artifacts/zephyr/fprime-zephyr-deployment/dict/ReferenceDeploymentTopologyDictionary.json --communication-selection uart --uart-baud 115200 --output-unframed-data
49+
50+
# Or
51+
fprime-gds -n --dictionary ./build-artifacts/zephyr/fprime-zephyr-deployment/dict/ReferenceDeploymentTopologyDictionary.json --communication-selection uart --uart-device /dev/cu.usbmodem142101 --uart-baud 115200
52+
53+
```
54+
55+
> [!Note]
56+
> `/dev/cu.usbmodem142101` will likely need to be replaced with the correct port. This can be found by running the following command: `ls -l /dev/cu.usb*`
57+
58+
59+
## Any Issues?
60+
Refer to the [additional resources][additional-resources] section in the main README file for potential fixes.
61+
62+
<!-- Links -->
63+
[board-list]: ../additional-resources/board-list.md
64+
[additional-resources]: ../../README.md#additional-resources

‎docs/main-content/initial-setup.md‎

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
# Initial Project Setup
2+
3+
This guide will walk through the steps of setting up the reference deployment.
4+
5+
<!-- TODO: UPDATE REPO NAME -->
6+
## 1. Clone the GitHub repository
7+
Clone the GitHub repository onto your local machine.
8+
```sh
9+
git clone https://github.com/fprime-community/fprime-zephyr-reference.git
10+
```
11+
12+
> [!NOTE]
13+
> If you would like to use fprime-bootstrap instead of git to clone this project, run this command and skip to step 5.
14+
> ```sh
15+
> fprime-bootstrap clone https://github.com/fprime-community/fprime-zephyr-reference.git
16+
> ```
17+
18+
## 2. Fetch git submodules
19+
Install the required libraries for this deployment
20+
```sh
21+
# In fprime-zephyr-reference
22+
git submodule update --recursive --init
23+
```
24+
25+
## 3. Create a virtual environment
26+
Create a virtual environment in the main project directory
27+
28+
```sh
29+
# In fprime-zephyr-reference
30+
python3 -m venv fprime-venv
31+
```
32+
33+
## 4. Activate the virtual environment
34+
35+
```sh
36+
# In fprime-zephyr-reference
37+
# Linux, MacOS, & Windows WSL
38+
source fprime-venv/bin/activate
39+
```
40+
41+
## 5. Install python requirements
42+
With the virtual environment activated, install the requirements
43+
```sh
44+
# In fprime-zephyr-reference (fprime-venv)
45+
pip install -r requirements.txt
46+
```
47+
48+
> [!NOTE]
49+
> You will need to follow some additional steps if you are using a different board than the one specified in the `settings.ini` file. Please refer to the [Specifying Board Configuration][specifying-board-configuration] documentation for more information.
50+
51+
52+
## 6. Get Zephyr Source Code
53+
Navigate to the `zephyr-workspace` directory to set up zephyr. You may need to update the `config` file in `./lib/zephyr-workspace/.west/` if you are using a different board. Refer to the documentation [here][specifying-board-configuration]
54+
```sh
55+
# In fprime-zephyr-reference
56+
cd lib/zephyr-workspace
57+
58+
# Run the following commands
59+
west update
60+
west zephyr-export
61+
```
62+
63+
> [!NOTE]
64+
> If you have not installed the [Zephyr SDK](https://docs.zephyrproject.org/latest/develop/toolchains/zephyr_sdk.html#toolchain-zephyr-sdk), please install it with the following command:
65+
> ```shell
66+
> # In fprime-zephyr-reference/lib/zephyr-workspace/zephyr
67+
> west sdk install
68+
> ```
69+
> The Zephyr SDK only needs to be installed once.
70+
71+
# Next Steps: [Building, Flashing, and Running the Deployment][build-flash-run]
72+
73+
<!-- Links -->
74+
[build-flash-run]: ./build-flash-run.md
75+
[specifying-board-configuration]: ../additional-resources/specifying-board-configuration.md

0 commit comments

Comments
 (0)