Skip to content

Commit

Permalink
Update README and bump fprime-tools (#1971)
Browse files Browse the repository at this point in the history 
* Fix tutorial link

* Update README !

* Fixes

* Add user guide to getting started

* Resources

* Review update

* Peer review

* Bump tooling versions

* spelling
  • Loading branch information
@thomas-bc
thomas-bc authored Apr 19, 2023
1 parent 124b6e8 commit 6ac7b73
Show file tree
Hide file tree
Showing 6 changed files with 79 additions and 153 deletions.
1 change: 1 addition & 0 deletions .github/actions/spelling/expect.txt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1504,6 +1504,7 @@ toklist
TOLOWER
toolchain
toolchains
toolset
tooltip
topologyapp
Torvalds
Expand Down
96 changes: 45 additions & 51 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,75 +1,69 @@
# F´: A Flight-Proven, Multi-Platform, Open-Source Flight Software Framework
<p align="center">
<img width="230em" src="docs/img/fprime-logo.png"><br/>
<h2 align="center">A Flight-Proven, Multi-Platform, Open-Source Flight Software Framework</h2>
</p>

**F´ (F Prime)** is a component-driven framework that enables rapid development and deployment of spaceflight and other embedded software applications. Originally developed at the [Jet Propulsion Laboratory](https://www.jpl.nasa.gov/), F´ has been successfully deployed on several space applications. It is tailored but not limited to small-scale spaceflight systems such as CubeSats, SmallSats, and instruments.
#
F´ (F Prime) is a component-driven framework that enables rapid development and deployment of spaceflight and other embedded software applications. Originally developed at the [Jet Propulsion Laboratory](https://www.jpl.nasa.gov/), F´ has been successfully deployed on [several space applications](https://nasa.github.io/fprime/projects.html). It is tailored but not limited to small-scale spaceflight systems such as CubeSats, SmallSats, and instruments.

**Please Visit the F´ Website:** [https://nasa.github.io/fprime/](https://nasa.github.io/fprime/). This website contains project information, user guides, documentation, tutorials, and more!
**Please Visit the F´ Website:** [https://nasa.github.io/fprime](https://nasa.github.io/fprime/) for more information.

F´ comprises several elements:

* An architecture that decomposes flight software into discrete components with well-defined interfaces
* A C++ framework that provides core capabilities such as message queues and threads
* Modeling tools for specifying components and connections and automatically generating code
* A growing collection of ready-to-use components
* Testing tools for testing flight software at the unit and integration levels.
## What does F´ provide

For installation instructions, including virtual environment creation and installation verification, see [INSTALL.md](./docs/INSTALL.md).
- An architecture that decomposes flight software into discrete components with well-defined interfaces
- A C++ framework that provides core capabilities such as message queues and threads
- Modeling tools for specifying components and connections and automatically generating code
- A growing collection of ready-to-use components
- Testing tools for testing flight software at the unit and integration levels.

## Example Deployments
Learn more about F' key features [here](https://nasa.github.io/fprime/features.html).

F´ comes with two example deployments. The deployments represent working F´ applications to help you understand F´. You can use these examples for reference, or clone them to start a new project.

The next section links to more step-by-step tutorials, but it's a good idea to build and run at least the first example deployment to ensure that F´ is installed correctly.
## System Requirements

**Example one:** [Ref](./Ref/README.md)
1. Linux, Windows with WSL, or macOS operating system
2. git
3. [CMake 3.16+](https://cmake.org/download/). CLI tool must be available on the system path.
4. CLang or GNU C and C++ compilers (e.g. gcc and g++)
5. [Python 3.7+](https://www.python.org/downloads/), virtual environments, and PIP

The standard reference application demonstrates how most of the system components should be wired together. The reference application can build on Linux or macOS, allowing you to get started immediately without the need for embedded hardware.

**Example two:** [RPI](./RPI/README.md)
## Getting Started

This Raspberry PI application shows how to run F´ in an embedded context by running on the Raspberry PI (a $35 embedded Linux computer). This application shows you how to get started on embedded projects with cross-compiling, drivers, and more. The Raspberry Pi was chosen because it is commercially available for a low price and runs Linux.
To get started with F´, install the F´ toolset with:
```
pip install fprime-tools
```

## Tutorials
Then, create a new project with:
```
fprime-util new --project
```

F´ provides several tutorials in order to help understand and develop within the framework. These tutorials cover basic component creation, system and topology design, tooling, and more. These tutorials are available at [docs/Tutorials/README.md](./docs/Tutorials/README.md).
See the [HelloWorld Tutorial](https://nasa.github.io/fprime/Tutorials/HelloWorld/Tutorial.html) to guide you through all the steps of developing an F´ project.

## Getting Help with F´
New users are encouraged to read through the [User Guide](https://nasa.github.io/fprime/UsersGuide/guide.html) and explore the [other tutorials](https://nasa.github.io/fprime/Tutorials/README.html).

As F´ becomes a community centered product line, there are more items available from the community at large.

To ask questions, discuss improvements, ask for help, please use the project's GitHub Discussions at: [https://github.com/nasa/fprime/discussions](https://github.com/nasa/fprime/discussions).
## Getting Help

The F´ community GitHub Organization contains third party contributions, more documentation of flight software development, and more! [https://github.com/fprime-community](https://github.com/fprime-community).
### Discussions
To ask questions, discuss improvements, and ask for help please use the project's [GitHub Discussions](https://github.com/nasa/fprime/discussions).
### Bug reports
To report bugs and issues, [open an issue here](https://github.com/nasa/fprime/issues).
### Community
The [F´ Community](https://github.com/fprime-community) GitHub Organization contains third party contributions, more documentation of flight software development, and additional resources.

You can open issues with this repository at: [https://github.com/nasa/fprime/issues](https://github.com/nasa/fprime/issues)

## F´ Features
## Resources
- [User Guide](https://nasa.github.io/fprime/UsersGuide/guide.html)
- [Tutorials](https://nasa.github.io/fprime/Tutorials/README.html)
- [Discussions](https://github.com/nasa/fprime/discussions)
- [Submit an Issue](https://github.com/nasa/fprime/issues)
- [F´ Community](https://github.com/fprime-community)

F´ has the following key features that enable robust embedded system design.

### Reusability

F´'s component-based architecture enables a high degree of modularity and software reusability.

### Rapid Deployment

F´ provides a complete development ecosystem, including modeling tools, testing tools, and a ground data system. Developers use the modeling tools to write high-level specifications, automatically generate implementations in C++, and fill in the implementations with domain-specific code. The framework and the code generators provide all the boilerplate code required in an F´ deployment, including code for thread management, code for communication between components, and code for handling commands, telemetry, and parameters. The testing tools and the ground data system simplify software testing, both on workstations and on flight hardware in the lab.

### Portability

F´ runs on a wide range of processors, from microcontrollers to multicore computers, and on several operating systems. Porting F´ to new operating systems is straightforward.

### High Performance

F´ utilizes a point-to-point architecture. The architecture minimizes the use of computational resources and is well suited for smaller processors.

### Adaptability

F´ is tailored to the level of complexity required for small missions. This makes F´ accessible and easy to use while still supporting a wide variety of missions.

### Analyzability

The typed port connections provide strong compile-time guarantees of correctness.

## Release Notes

The version history and artifacts associated with the project can be found at [Releases](https://github.com/nasa/fprime/releases) and [CHANGELOG.md](./CHANGELOG.md).
The version history and artifacts associated with the project can be found at [Releases](https://github.com/nasa/fprime/releases).
115 changes: 28 additions & 87 deletions docs/INSTALL.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,17 +5,13 @@ title: "F´ Installation Guide"

## Overview

This installation guide is specifically designed to enable individuals and researchers to get up and
running with F´ quickly. Larger projects with specific requirements may need to extend this process.
This installation guide is specifically designed to enable individuals and researchers to get up and running with F´ quickly. Larger projects with specific requirements may need to extend this process.

**Note:** See the troubleshooting section at the bottom for help resolving common issues found during F´ installs.

## Requirements

F´ depends on several items before the user should attempt to install it. These requirements are
listed below and the user should ensure they are installed before proceeding with this guide. Should these items not
be available on the user's Operating System, then a Virtual Machine should be used. One option is
[VirtualBox](https://www.virtualbox.org/).
F´ depends on several items before the user should attempt to install it. These requirements are listed below and the user should ensure they are installed before proceeding with this guide.

Requirements:

Expand All @@ -27,91 +23,44 @@ Requirements:

**Note:** OS-specific notes are in the [Troubleshooting](#Troubleshooting) section below.

### Setting Up F´ Environment
### Bootstrapping the F´ Development Environment

The ecosystem of tools supporting F´ is installed as python packages available via PIP. In order to install F´, the user should
setup an environment to run these tools in.

>Note: Python is used by many operating systems. To prevent problems users are encouraged to run F´ python
>from within a [virtual environment](https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/)
**Setting Up a Virtual Environment**

Choose a location to generate a virtual environment. This can be any path the user has read and write access to. In this guide we'll
use the path: `$HOME/fprime-venv`

```
python3 -m venv $HOME/fprime-venv
. $HOME/fprime-venv/bin/activate
pip install -U setuptools setuptools_scm wheel pip
```

> Note: `. $HOME/fprime-venv/bin/activate` must be run in each new terminal where the user wishes to use the virtual environment.
### Cloning the F´ Repository and Installing F´ Tools

Installation of F´ requires cloning of the F´ core repository via Git. This will bring down the core framework and C++ files.
F´ ships with a `requirements.txt` file enumerating the tools F´ uses and their specific tested versions.

**Clone F´ and Install Tools**
The ecosystem of tools supporting F´ is installed as python packages available via PIP.

```
git clone https://github.com/nasa/fprime
pip install -r fprime/requirements.txt
pip install fprime-tools
```

>Note: When changing F´ versions make sure to re-run the `pip install -r fprime/requirements.txt` to get the tested tool versions.
>Note: Alternative tool installations are described in [Advanced](#Advanced).
## Checking Your F´ Installation
> Python is used by many operating systems. To prevent problems users are encouraged to run F´ python from within a [virtual environment](https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/). This is set up when creating a new F´ project.
The user may easily checkout that their F´ installation has succeeded by testing the following
commands. First, the user will test the build and Autocoder install. Next, the user will test the GDS
layer components. Should the user not have installed the given component, the commands won't work.

**Testing F´ Autocoder Installation Via Building Ref Application**
### Creating a New F´ Project

The entrypoint to developing with F´ is creating a new project. This will clone the F´ repository and install the necessary tool versions for working with the specified version of F´.
```
cd Ref
fprime-util generate
fprime-util build --jobs "$(nproc || printf '%s\n' 1)"
fprime-util new --project
```

**Testing F´ GDS Installation Via Running HTML GUI**

This command will ask for some input. Sample responses are below:
```
fprime-gds -g html -r <path to fprime checkout>/Ref/build-artifacts
project_name [MyProject]: MyProject
fprime_branch_or_tag [devel]: devel
Select install_venv:
1 - yes
2 - no
Choose from 1, 2 [1]: 1
```

**Note:** `Ref` should contain pre-built dictionaries and binaries for the user's system. This can
be achieved by running the Autocoder installation test (the user must have a working Autocoder
installation).
Next steps: [HelloWorld Tutorial](Tutorials/HelloWorld/Tutorial.md)

## Advanced

There are several advanced options users can consider while installing F´. However, users should be warned that some
knowledge of our tools and versions is often required.
There are several advanced options users can consider while installing F´. However, users should be warned that some knowledge of our tools and versions is often required.


### Installing Tab Completion

Several of F´s command-line utilities support tab completion. To enable these tools to use it, see the
[instructions here](UsersGuide/user/autocomplete.md).


## Installing Individual Tools

Each of the F´ tools can be installed individually through sub packages. However, users should use care to ensure that
compatible versions are installed.

| Tool(s) | Package |
|-------------|--------------|
| fpp | fprime-fpp |
| fprime-util | fprime-tools |
| GDS | fprime-gds |
Several of F´s command-line utilities support tab completion. To enable these tools to use it, see the [instructions here](UsersGuide/user/autocomplete.md).

> Note: `fprime-gds` depends on `fprime-tools`. It is advisable to install `fprime-gds` and let PIP pull in a compatible
version of `fprime-tools`.

### Installing Optional Components

Expand All @@ -124,8 +73,7 @@ Some F´ packages contain optional components. These components can be installed
| fprime-gds[test-api-xls] | Installs excel logging for use within the integration test framework |


> Note: these packages are optional as they pull in many additional packages and libraries. These may not be supported
on all systems.
> These packages are optional as they pull in many additional packages and libraries. These may not be supported on all systems.
**Example:**
```
Expand All @@ -135,20 +83,17 @@ pip install fprime-gds[uart-adapter]

## Troubleshooting

This section will add some known hints to trouble-shooting with the installation of F´. This will hopefully help users
install things more effectively.
This section will add some known hints to trouble-shooting with the installation of F´. This will hopefully help users install things more effectively.

### fprime-util: command not found

If the user is using a virtual environment and receives the 'command not found', the problem is likely caused by the
environment not being sourced in a new terminal. Make sure to source the environment before running:
If the user is using a virtual environment and receives the 'command not found', the problem is likely caused by the environment not being sourced in a new terminal. Make sure to source the environment before running:

```
. $HOME/fprime-venv/bin/activate
```

If installing without a virtual environment, PIP occasionally uses `$HOME/.local/bin` as a place to install user tools.
Users running without virtual environments should add this directory to the path.
If installing without a virtual environment, PIP occasionally uses `$HOME/.local/bin` as a place to install user tools. Users running without virtual environments should add this directory to the path.

### Helper script 'fpp-redirect-helper' exited with reason: Permission denied

Expand All @@ -175,8 +120,7 @@ Now you should be able to run the installation without trouble.

### Mac OS X and CMake Command Not Found

If the user chooses to install CMake directly from the CMake site (not using homebrew nor Mac Ports), then the CMake
command-line tools must be added to the user's PATH or default system libraries. The quickest command to do that is:
If the user chooses to install CMake directly from the CMake site (not using homebrew nor Mac Ports), then the CMake command-line tools must be added to the user's PATH or default system libraries. The quickest command to do that is:

```
sudo "/Applications/CMake.app/Contents/bin/cmake-gui" --install
Expand All @@ -186,17 +130,14 @@ More information can be found [here](https://stackoverflow.com/questions/3066860

### System Python, Packages, and Python3

Many operating systems offer python PIP packages through their package manager (apt, yum, etc). Most python projects
recommend avoiding those packages and instead installing them from PIP in a virtual environment. The reason for this is that the version of the python package from the OS may not be the required version that the python project depends on. Thus, users may choose to install F´ into a virtual environment. This is outside the scope of this document.
Many operating systems offer python PIP packages through their package manager (apt, yum, etc). Most python projects recommend avoiding those packages and instead installing them from PIP in a virtual environment. The reason for this is that the version of the python package from the OS may not be the required version that the python project depends on. Thus, users may choose to install F´ into a virtual environment. This is outside the scope of this document.

### SSL Error with Python 3.6+ on macOS
### SSL Error with Python 3.7+ on macOS

The version of openSSL bundled with Python 3.6+ requires access to macOS's root certificates. If the following error is
encountered while installing fprime:
The version of openSSL bundled with Python 3.7+ requires access to macOS's root certificates. If the following error is encountered while installing fprime:

```
Failed find expected download: <urlopen error [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get
local issuer certificate
Failed find expected download: <urlopen error [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate
```

Then run the following command in a macOS terminal to install necessary certificates:
Expand Down
Loading

0 comments on commit 6ac7b73

Please sign in to comment.