From 339d5d3c36b870be6d06efeb3bdc09472e15d451 Mon Sep 17 00:00:00 2001 From: hAkselS <86744896+hAkselS@users.noreply.github.com> Date: Wed, 28 Jun 2023 14:17:22 -0700 Subject: [PATCH] Migrate HelloWorld tutorial to F' community (#2095) --- README.md | 2 +- docs/Tutorials/HelloWorld/Deployments.md | 185 --------------------- docs/Tutorials/HelloWorld/HelloWorld.md | 198 ----------------------- docs/Tutorials/HelloWorld/NewProject.md | 84 ---------- docs/Tutorials/HelloWorld/README.md | 3 + docs/Tutorials/HelloWorld/Tutorial.md | 78 --------- docs/Tutorials/README.md | 13 +- 7 files changed, 9 insertions(+), 554 deletions(-) delete mode 100644 docs/Tutorials/HelloWorld/Deployments.md delete mode 100644 docs/Tutorials/HelloWorld/HelloWorld.md delete mode 100644 docs/Tutorials/HelloWorld/NewProject.md create mode 100644 docs/Tutorials/HelloWorld/README.md delete mode 100644 docs/Tutorials/HelloWorld/Tutorial.md diff --git a/README.md b/README.md index 29fa2022e28..f5c57a5c9fa 100644 --- a/README.md +++ b/README.md @@ -41,7 +41,7 @@ Then, create a new project with: fprime-util new --project ``` -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. +See the [HelloWorld Tutorial](https://fprime-community.github.io/fprime-tutorial-hello-world/) to guide you through all the steps of developing an F´ project. 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). diff --git a/docs/Tutorials/HelloWorld/Deployments.md b/docs/Tutorials/HelloWorld/Deployments.md deleted file mode 100644 index 96ee274801b..00000000000 --- a/docs/Tutorials/HelloWorld/Deployments.md +++ /dev/null @@ -1,185 +0,0 @@ -# Getting Started: Integration and Testing With F´ Deployments - -This section will walk new users through creating a new F´ [deployment](./Tutorial.md#deployment). This deployment will -build a [topology](./Tutorial.md#topology) containing the standard F´ stack of components and a single `HelloWorld` -component instance. The `HelloWorld` was created in the [last section](./HelloWorld.md). The tutorial will close by -testing the deployment and `HelloWorld` component through the `fprime-gds`. - -### Prerequisites: -- [Getting Started: F´ Hello World Component](./HelloWorld.md) - -### Tutorial Steps: -- [Creating A New Deployment](#creating-a-new-deployment) -- [Adding The Hello World Component](#adding-the-hello-world-component) -- [Testing With `fprime-gds`](#testing-with-fprime-gds) -- [Conclusion](#conclusion) - -## Creating A New Deployment - -F´ deployments represent one flight software executable. All the components we develop for F´ run within a deployment. -The deployment created here will contain the standard command and data handling stack. This stack enables -ground control and data collection of the deployment. - -To create a deployment, run the following commands: -```bash -# In: MyProject -fprime-util new --deployment -``` -This command will ask for some input. Respond with the following answers: - -``` -deployment_name [MyDeployment]: MyDeployment -path_to_fprime [./fprime]: -``` - -> For any other questions, select the default response. - -At this point, the `MyDeployment` has been created, but our `HelloWorld` component has not been added. - -## Adding The Hello World Component - -First, the project's components should be added to this deployment's build. This can be done by adding the following -to `MyDeployment/CMakeLists.txt`. - -```cmake -... -### -# Components and Topology -### -include("${FPRIME_PROJECT_ROOT}/project.cmake") -... -``` -> To build this new deployment generate a build cache and then build. -> ```bash -> # In: MyProject/MyDeployment -> fprime-util generate -> fprime-util build -> ``` -> > Notice `fprime-util generate` was used again. This is because this new deployment builds in a separate environment. - -In this section the `HelloWorld` component will be added to the `MyDeployment` deployment. This can be done by adding -the component to the topology defined in `MyDeployment/Top`. - -Topologies instantiate all the components in a running system and link them together. For some port types, like the -commanding, event, and telemetry ports used by `HelloWorld`, the connections are made automatically. In addition, the -topology specifies how to construct the component instance. This is also done automatically unless the component has -specific configuration. - -In order to add a component to the topology, it must be added to the topology model. An instance definition and an -instance initializer must both be added. - -To add an instance definition, add `instance helloWorld` to the instance definition list in the `topology MyDeployment` section -of `MyDeployment/Top/topology.fpp`. This is shown below. - -Edit `MyDeployment/Top/topology.fpp`: -``` -... - topology MyDeployment { - # ---------------------------------------------------------------------- - # Instances used in the topology - # ---------------------------------------------------------------------- - - instance ... - instance ... - instance helloWorld -``` -> Be careful to not remove any other instances from the list. - -`helloWorld` is the name of the component instance. Like variable names, component instance names should be descriptive -and are typically named in camel or snake case. - -Next, an instance initializer must be added to topology instances defined in `MyDeploymment/Top/instances.fpp` file. -Since the `HelloWorld` component is an `active` component it should be added to the active components section and should -define a priority and queue depth options. This is shown below. - -Add to `MyDeploymment/Top/instances.fpp`: -``` -... - # ---------------------------------------------------------------------- - # Active component instances - # ---------------------------------------------------------------------- - instance ... - ... - ... - ... - - instance ... - - instance helloWorld: MyComponents.HelloWorld base id 0x0F00 \ - queue size Default.QUEUE_SIZE \ - stack size Default.STACK_SIZE \ - priority 50 -``` -> The user must ensure that the base id (0x0F00) does not conflict with any other base ids in the topology. 0x0F00 -> should be safe for deployments created with `fprime-util new --deployment`. - -> Make sure to use the same instance name (i.e. helloWorld) as defined in the instance definition just added to -> `topology.fpp`. - -Finally, our new telemetry channel should be added to our telemetry packet specification. For this tutorial the -channel can be ignored as the deployment will not use the telemetry packetizer. Add the following to the `ignore` -section of `MyDeployment/Top/MyDeploymentPackets.xml`. - -Update `MyDeployment/Top/MyDeploymentPackets.xml`: -``` - - ... - - -``` - -Since this component has no custom ports nor does it require special configuration, our addition to the topology is -completed. The deployment can now be set up and built using the following commands: - -``` -# In: MyProject/MyDeployment -fprime-util build -j4 -``` -> Resolve any errors that occur before continuing to the running section. - -## Running With `fprime-gds` - -It is now time to test the `HelloWorld` component by running the deployment created in this section. This can be -accomplished by running the `fprime-gds` command in the deployment, verifying connection, sending the new SEND_HELLO -command and verifying that the `Hello` event and `GreetingCount` channel appears. - -To start the deployment with default settings, run: -```bash -fprime-gds -``` - -The F´ GDS control page should open up in your web browser. If it does not open up, navigate to `http://127.0.0.1:5000`. - -Once the F´ GDS page is visible, look for a green circle icon in the upper right corner. This shows that the flight -software deployment has connected to the GDS system. If a red X appears instead, navigate to the Logs tab and look for -errors in the various logs. - -Now that communication is verified, navigate to the "Commanding" tab and select `helloWorld.SAY_HELLO` from the -dropdown list. Type a greeting into the argument input box and click the button "Send Command". If the argument has -validated successfully the command will send. Resolve all errors and ensure the command has sent. - -> Notice commands are instance specific. Had several HelloWorld component instances been used, there would be multiple -> `SAY_HELLO` listings, one for each component instance. - -Now that the command has sent, navigate to the "Events" tab. Ensure that the event list contains the Hello event with -the text entered when sending the command. - -Lastly, navigate to the "Channels" tab. Look for "helloWorld.GreetingCount" in the channel list. Ensure it has recorded -the number of times a `helloWorld.SAY_HELLO` was sent. - -Congratulations, you have now set up a project, component, and deployment in F´. - -## Conclusion - -This concludes both the adding deployment section of the Getting Started tutorial and the tutorial itself. The user has -been able to perform the following actions: - -1. Create a new blank F´ projects -2. Create a new F´ components -3. Create a new F´ deployments and add components it - -To explore components more in-depth and see how components communicate with one another, see the -[Math Component Tutorial](../MathComponent/Tutorial.md). - -**Next:** [Math Component Tutorial](../MathComponent/Tutorial.md) - diff --git a/docs/Tutorials/HelloWorld/HelloWorld.md b/docs/Tutorials/HelloWorld/HelloWorld.md deleted file mode 100644 index b034509fdbc..00000000000 --- a/docs/Tutorials/HelloWorld/HelloWorld.md +++ /dev/null @@ -1,198 +0,0 @@ -# Getting Started: Creating an F´ Hello World Component - -This tutorial will walk new users through creating a basic F´ component. Users should have completed the new project -tutorial and have the tools sourced as shown in the [conclusion](./NewProject.md#conclusion) portion of that tutorial. - -F´ components encapsulate the various parts of system behavior. These components can interact with the ground system -through [commands](Tutorial.md#command), [events](./Tutorial.md#event), and -[telemetry channels](./Tutorial.md#telemetry-channel). Components communicate with other components through -[ports](./Tutorial.md#port), which covered in-depth in [another tutorial](../MathComponent/Tutorial.md). - -### Prerequisites: -- [Getting Started: Creating an F´ Project](./NewProject.md) - -### Tutorial Steps: -- [Hello World Component](#hello-world-component-requirements) -- [Creating the Hello World Component](#creating-the-hello-world-component) -- [Editing the Component Model](#editing-the-component-model) -- [Implementing Component Behavior](#implementing-component-behavior) -- [Conclusion](#conclusion) - -## Hello World Component Requirements - -The first step for creating a new component is understanding what it is that we wish to implement. This is called -defining requirements. In the spirit of "Hello World" this component will encapsulate greeting behavior. The component -will define three items to implement greeting behaviour: - -1. A [command](./Tutorial.md#command) called `SAY_HELLO` that will command the component to send a greeting -2. An [event](./Tutorial.md#event) called `Hello` that is the greeting sent in response to the `SAY_HELLO` command -3. A [telemetry channel](./Tutorial.md#telemetry-channel) called `GreetingCount` that will count each `Hello` event sent - -These are a simple set of requirements for this component. - -## Creating the Hello World Component - -The next step is to create the new component. First, create a directory called `MyComponents` to contain this project's -components and change into that directory. - -```bash -# In: MyProject -mkdir -p MyComponents -cd MyComponents -``` - -Creating a new component is accomplished with the following command: - -```bash -# In: MyProject/MyComponents -fprime-util new --component -``` -This command will ask for some input. You should respond with the following answers: - -``` -[INFO] Cookiecutter source: using builtin -component_name [MyComponent]: HelloWorld -component_short_description [Example Component for F Prime FSW framework.]: Hello World Tutorial Component -component_namespace [HelloWorld]: MyComponents -Select component_kind: -1 - active -2 - passive -3 - queued -Choose from 1, 2, 3 [1]: 1 -Select enable_commands: -1 - yes -2 - no -Choose from 1, 2 [1]: 1 -Select enable_telemetry: -1 - yes -2 - no -Choose from 1, 2 [1]: 1 -Select enable_events: -1 - yes -2 - no -Choose from 1, 2 [1]: 1 -Select enable_parameters: -1 - yes -2 - no -Choose from 1, 2 [1]: 1 -[INFO] Found CMake file at 'MyProject/project.cmake' -Add component MyComponents/HelloWorld to MyProject/project.cmake at end of file (yes/no)? yes -Generate implementation files (yes/no)? yes -``` - -> For any other questions, select the default response. - -This will create a new component called "HelloWorld" in the "MyProject" namespace. This new component will be able to -define commands, events, telemetry channels, and parameters. - -We should navigate to the component's directory and look around: - -```bash -# In: MyProject/MyComponents -cd HelloWorld -ls -``` -This will show the following files: -1. `HelloWorld.fpp`: design model for the component -2. `HelloWorld.hpp` and `HelloWorld.cpp`: C++ implementation files for the component, currently empty. -3. `CMakeList.txt`: build definitions for the component. -4. `docs` folder to place component documentation - -To build this component run `fprime-util build` in the current folder. - -> Any component in F´ can be built by navigating to the component's folder and running `fprime-util build`. - -## Editing the Component Model - -A component model defines the interface of the component with the rest of the F´ system and with the ground system F´ -communicates with. In this case we intend to define a command, an event, and a telemetry channel as specified above. - -Open the model file `HelloWorld.fpp` and add replace the line: - -``` -async command TODO opcode 0 -``` - -with the following: - -``` -@ Command to issue greeting with maximum length of 20 characters -async command SAY_HELLO( - greeting: string size 20 @< Greeting to repeat in the Hello event -) - -@ Greeting event with maximum greeting length of 20 characters -event Hello( - greeting: string size 20 @< Greeting supplied from the SAY_HELLO command -) severity activity high format "I say: {}" - -@ A count of the number of greetings issued -telemetry GreetingCount: U32 -``` -> You should ensure to replace any existing command, event, and channel definitions with those supplied above but leave -> the 'Standard AC Ports' section untouched. - -With this step completed you can generate a basic implementation with the following command: - -```bash -# In: MyProject/MyComponents/HelloWorld -fprime-util impl -``` - -This creates `HelloWorld.hpp-template` and `HelloWorld.cpp-template` files that contain our new fill-in template. While -normally one would merge new templates with the existing code, we will instead overwrite the existing implementations as -we have not edited those files yet. To do this: - -```bash -mv HelloWorld.hpp-template HelloWorld.hpp -mv HelloWorld.cpp-template HelloWorld.cpp -``` -We are now ready for implementing component behavior. - -## Implementing Component Behavior - -F´ behavior is implemented in two types of methods command handler functions to implement command behavior and handler -functions to implement port behavior (as described in the next tutorial). For this tutorial we need to implement the -`SAY_HELLO` command, so we need to edit the `SAY_HELLO_cmdHandler` function in the `HelloWorld.cpp` file. Ensure its -contents look like: - -```c++ -void HelloWorld:: SAY_HELLO_cmdHandler(FwOpcodeType opCode, U32 cmdSeq, const Fw::CmdStringArg& greeting) { - // Copy the command string input into an event string for the Hello event - Fw::LogStringArg eventGreeting(greeting.toChar()); - // Emit the Hello event with the copied string - this->log_ACTIVITY_HI_Hello(eventGreeting); - - this->tlmWrite_GreetingCount(++this->m_greetingCount); - - // Tell the fprime command system that we have completed the processing of the supplied command with OK status - this->cmdResponse_out(opCode, cmdSeq, Fw::CmdResponse::OK); -} -``` -> We must also add the m_greetingCount member variable to the class defined in `HelloWorld.hpp` and the constructor -> defined in `HelloWorld.cpp`. This looks like: -> -> **HelloWorld.hpp: Adding New Member Variable** -> ```c++ -> private: -> U32 m_greetingCount; -> ``` -> Should be added inside the `class` definition in `HelloWorld.hpp`. -> -> **HelloWorld.cpp: Updating Constructor** -> ```c++ -> HelloWorld:: HelloWorld(const char *const compName) : HelloWorldComponentBase(compName), -> m_greetingCount(0) -> { -> ``` -> Should be added to the `HelloWorld` constructor at the top of the file. - -The component should build without errors by running `fprime-util build`. Resolve any errors that occur before -proceeding to the next section. - -## Conclusion - -This tutorial has walked through the creation of component that implements a "Hello World" style greeting behavior for -our F´ system. In the next tutorial, this component will be hooked-up to an F´ deployment and tested! - -**Next:** [Getting Started: Integration and Testing With F´ Deployments](./Deployments.md) diff --git a/docs/Tutorials/HelloWorld/NewProject.md b/docs/Tutorials/HelloWorld/NewProject.md deleted file mode 100644 index 817bd81e242..00000000000 --- a/docs/Tutorials/HelloWorld/NewProject.md +++ /dev/null @@ -1,84 +0,0 @@ -# Getting Started: Creating an F´ Project - -This tutorial will walk new users through creating a new F´ project. - -### Tutorial Steps: -- [Bootstrapping F´](#bootstrapping-f) -- [Creating a New F´ Project](#creating-a-new-f-project) -- [Building the New F´ Project](#building-the-new-f-project) -- [Conclusion](#conclusion) - -## Bootstrapping F´ - -An F´ [project](./Tutorial.md#project) ties to a specific version of tools to work with F´. In order to create -this project and install the correct version of tools, an initial bootstrap version of F´ tools must be installed. This -is accomplished with the following command: - -```bash -pip install fprime-tools -``` - -## Creating a New F´ Project - -Now that to tools are installed a new F´ project should be created. An F´ project internalizes the version of F´ that -the project will build upon and provides the user the basic setup for creating, building, and testing components. - -In order to make a new project, run the following command and answer the questions as indicated below: - -```bash -fprime-util new --project -``` - -This command will ask for some input. Respond with the following answers: -``` -project_name [MyProject]: MyProject -fprime_branch_or_tag [devel]: devel -Select install_venv: -1 - yes -2 - no -Choose from 1, 2 [1]: 1 -``` - -Use the default for anything not specified. This command will take a moment to run. - -The above command creates a new F´ project structure in a folder called `MyProject`, use the `devel` branch of F´ as -the basis for the project, and sets up the matching tools in a new Virtual Environment. - -> Load the tools for this project via the virtual environment. -> -> ```bash -> cd MyProject -> . venv/bin/activate ->``` -> -> Make sure to load these tools any time you are working with the this project. - -## Building the New F´ Project - -The next step is to set up and build the newly created project. This will serve as a build environment for any newly -created components, and will build the F´ framework supplied components. - -```bash -cd MyProject -fprime-util generate -fprime-util build -j4 -``` - -> `fprime-util generate` sets up the build environment for a project/deployment. It only needs to be done once. At the -> end of this tutorial, a new deployment will be created and `fprime-util generate` will also be used then. - -## Conclusion - -A new project has been created with the name `MyProject` and has been placed in a new folder called in `MyProject` in -the current directory. It includes the initial build system setup, and F´ version. It is still empty in that the user -will still need to create components and deployments. - -For the remainder of this Getting Started tutorial we should use the tools installed for our project and issue commands -within this new project's folder. Change into the project directory and load the newly install tools with: - -```bash -cd MyProject -. venv/bin/activate -``` - -**Next:** [Getting Started: Creating an F´ Hello World Component](./HelloWorld.md) diff --git a/docs/Tutorials/HelloWorld/README.md b/docs/Tutorials/HelloWorld/README.md new file mode 100644 index 00000000000..6bf352ed4a1 --- /dev/null +++ b/docs/Tutorials/HelloWorld/README.md @@ -0,0 +1,3 @@ +## Welcome + +HelloWorld tutorial has been reworked and moved to [fprime-community/fprime-tutorial-hello-world](https://fprime-community.github.io/fprime-tutorial-hello-world/) \ No newline at end of file diff --git a/docs/Tutorials/HelloWorld/Tutorial.md b/docs/Tutorials/HelloWorld/Tutorial.md deleted file mode 100644 index 3c3f952a111..00000000000 --- a/docs/Tutorials/HelloWorld/Tutorial.md +++ /dev/null @@ -1,78 +0,0 @@ -# Getting Started: Introduction and F´ Terminology - -The getting started tutorial is designed to teach new users the basics of F´ usage, instruct existing users on new -command that help in F´ development, and act as the canonical "Hello World" example for F´. - -This tutorial walks through the following steps: -1. [Creating an F´ Project](./NewProject.md) -2. [Creating an F´ Hello World Component](./HelloWorld.md) -3. [Integration and Testing With F´ Deployments](./Deployments.md) - -Once finished, users should have a good understanding of the basic development mechanics for working with F´ and then -could dive deeper into concepts through the [Math Component Tutorial](../MathComponent/Tutorial.md). - -## F´ Terminology - -F´ uses specific terminology to refer to specific parts of the system. This section dives into the basic F´ terminology -used in this tutorial and an explanation of how the terminology is used. - -#### Project - -An F´ project is a collection of files and folders used to work with F´. At its core, a project is just a folder that -can be used to hold F´ code. Projects should specifically exclude the core F´ library to avoid the "clone and own" -problem. Rather projects should link-to a version of F´. - -This tutorial will create a new `MyProject` project used to contain the other things created by the tutorial. - -#### Component - -An F´ component encapsulates a unit of system behavior. Components use ports to communicate with other components and -define commands, events, telemetry channels, and parameters. - -This tutorial will create a new `HelloWorld` component that defines a `SAY_HELLO` command, `Hello` event, and -`GreetingCount` telemetry channel. The component only used built-in ports. It does not use custom ports nor parameters. - -#### Port - -A port is an interface used to communicate between components. This tutorial only uses built-in ports. - -#### Command - -Commands represent actions that a component can execute. Commands can be sent from the ground or via command sequences. -Command behavior is defined in a command handler defined in the component's implementation. - -This tutorial defines one command `SAY_HELLO` with a single argument `greeting`. This command will be sent via the -ground system and will echo the greeting back via the `Hello` event. - -#### Event - -Events represent actions that a component has performed. Events are akin to software log messages. Events are received -and displayed by the ground system. - -This tutorial defines one event `Hello` emitted in response to the `SAY_HELLO` command and containing the same greeting -that the command had. - -#### Telemetry Channel - -Telemetry channels provide the active state of the component. Each channel represents a single item of state that will -be sent to the ground system. - -This tutorial defines a single channel `GreetingCount` that contains the count of the number of `SAY_HELLO` greeting -commands received. - -#### Deployment - -Deployments are a single build of F´ software. Each deployment results in one software executable that can be run along -with other associated files. Each deployment has a topology that defines the system. - -This tutorial will create the `MyDeployment` deployment, run this deployment, and test it through the F´ GDS. - -#### Topology - -Topologies are networks of connected components that define the software. Multiple instances of a component may be added -to the topology. - -This tutorial will use a standard command and data handling topology. A single `HelloWorld` component instance called -`helloWorld` will be added to the standard topology. - -**Next:** [Getting Started: Creating an F´ Project](./NewProject.md) diff --git a/docs/Tutorials/README.md b/docs/Tutorials/README.md index de4086583f3..a20aec3854c 100644 --- a/docs/Tutorials/README.md +++ b/docs/Tutorials/README.md @@ -8,20 +8,17 @@ users to learn F´ and walk through the most basic steps in developing an F´ ap ## Tutorials Index -1. [HelloWorld](HelloWorld/Tutorial.md): An Introduction to F´ +1. [HelloWorld](https://fprime-community.github.io/fprime-tutorial-hello-world/): An Introduction to F´ 2. [LedBlinker](https://github.com/fprime-community/fprime-workshop-led-blinker/blob/main/README.md): F´ and Embedded Hardware 3. [MathComponent](MathComponent/Tutorial.md) 4. [Cross-Compilation Tutorial](CrossCompilation/Tutorial.md) -## [HelloWorld](HelloWorld/Tutorial.md): An Introduction to F´ +## [HelloWorld](https://fprime-community.github.io/fprime-tutorial-hello-world/): An Introduction to F´ + +The HelloWorld tutorial walks a new users through creating a new project, designing their first F´ component, and testing that +component through an F´ deployment. -The HelloWorld tutorial walks a new user through creating a new project, their first F´ component, and testing that -component through an F´ deployment. This tutorial has the following subsections: -1. [Introduction and F´ Terminology](./HelloWorld/Tutorial.md) -2. [Creating an F´ Project](./HelloWorld/NewProject.md) -3. [Creating an F´ Hello World Component](./HelloWorld/HelloWorld.md) -4. [Integration and Testing With F´ Deployments](./HelloWorld/Deployments.md) ## [LedBlinker](https://github.com/fprime-community/fprime-workshop-led-blinker/blob/main/README.md): F´ and Embedded Hardware