diff --git a/docs/getting-started.md b/docs/getting-started.md index 1dd936759e..64fa43902c 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -4,35 +4,45 @@ layout: default --- # Getting Started with F' -In this guide, we will cover the basics of working with F'. To start with, we will grab the code, build the reference application, and verify -that the reference application will run. After that we will create a custom F' component and build it into out own application. Along the way -we will cover: Components, Topologies, Events, Telemetry, and Commands. In addition, we will see how to modify the build-system to include our +In this guide, we will cover the basics of working with F'. To start with, we retrieve the code, build the reference application, and verify +that the reference application will run. After that we will create a custom F' component and create our own application. Along the way +we will cover: Components, Topologies, Events, Telemetry, and Commands. In addition, we will see how to modify the build system to include our new components and topologies. ## Getting Started with F' and the Reference Application The first step to running F' is to ensure that the required build tools are available on your system. At its most basic, F' requires -several tools to be installed: Git, GNU make, lxml, and python w/ cheetah. In order, to run the ground-system several more packages are required (see: Gse/bin/required.txt). Make is available on most systems, as well as git and lxml. +several tools to be installed: Git, GNU make, lxml, and python 2 w/ cheetah. In order, to run the ground-system several more packages are required (see: Gse/bin/required.txt). Make is available on most systems, as well as git and lxml. -To install the packages in ubuntu, you can run the following commands: +### Cloning the Software and Building the Reference Application + +The first step is to clone the software from GitHub. The following command will clone the software straight from NASA's GitHub project page. -#### Ubuntu Installation ``` -sh fprime/mk/os-pkg/ubuntu-packages.sh -pip install -r fprime/Gse/bin/required.txt +git clone https://github.com/nasa/fprime.git ``` -*Note:* other installation and setup instructions are availabe in the [user guide.](https://github.com/nasa/fprime/blob/master/docs/UsersGuide/FprimeUserGuide.pdf) -### Cloning the Software and Building the Reference Application +### Installation -The next step is to clone the software from GitHub. The following command will clone the software straight from NASA's GitHub project page. +The next step is to install the software. Make sure git, and lxml are installed on your system. Then, using Python 2's pip tool the python dependencies can be installed. Both these steps can be accomplished on Ubuntu with the following commands: +#### Ubuntu Installation (sudo may be required) ``` -git clone https://github.com/nasa/fprime.git +sh fprime/mk/os-pkg/ubuntu-packages.sh +pip install numpy +pip install -r fprime/mk/python/pip_required_build.txt +pip install -r fprime/mk/python/pip_required_gui.txt ``` +*Note:* other installation and setup instructions are availabe in the [user guide.](https://github.com/nasa/fprime/blob/master/docs/UsersGuide/FprimeUserGuide.pdf) +*Note 2:* numpy is required for some packages setup scripts, and thus must be install first. -Once the software is cloned, the reference-application can be built by changing into the reference directory, generating make files, -clean and makeing the code. +### Building the Reference Application + +The reference application is used to help developers develop F Prime applications by showing various features. It is also a useful test of the +installation and thus we will run it here. + +Once the software is cloned and packages installed, the reference-application can be built by changing into the reference directory, generating make files, +cleaning and makeing the code. ``` cd fprime/Ref @@ -50,17 +60,13 @@ In order to run the reference application, one needs to run the binary named *Re show that the reference application was successfully built and runnable. Replace *darwin-darwin-x86-debug-llvm-bin* in the below commands by the target used in building the reference application -**On OS X**: +**Running with the GUI:** ``` -cd fprime/Ref/darwin-darwin-x86-debug-llvm-bin -./Ref +cd fprime/Ref +./scripts/run_ref.sh ``` -**On Linux**: -``` -cd fprime/Ref/linux-linux-x86-debug-gnu-bin -./Ref -``` +**Note:** running with the gui is the recommended way of running the application. However, one can run the application directly from target output directory if desired. Success!!! We have now successfully run the reference application, showing that the build tools work. We are ready to proceed to a custom application. @@ -72,7 +78,7 @@ pretending to be am ACM device for basic serial communication. The messages thes ![USB GPS Hardware](img/usb-gps.jpg) This quick-start guide will show how to integrate one of these GPS receivers with the F' framework by wrapping it in a Component and defining commands, -telemetry, and log events. Finnaly, we will modify the reference Topology to include this new component such that we can downlink our telemetry to +telemetry, and log events. Finally, we will modify the reference Topology to include this new component such that we can downlink our telemetry to the F' supplied ground station (GSE). **Note:** all the sample files, and a working deployment are available at [https://github.com/LeStarch/fprime/tree/gps-application](https://github.com/LeStarch/fprime/tree/gps-application). @@ -84,7 +90,7 @@ and finish up by adding an event to report GPS lock status and a command to repo ### Designing the GPS Component -Currently, F' designs are stored in XML files that feed the auto-coding system. An XML file represents a signle component including the ports it uses +The F’ designs are specified by XML files that are compiled by code generators. An XML file represents a single component including the ports it uses to communicate with other components as well as references to the dictonaries that define events/log messages, telmetry, and commands. Further discussion of components, ports, events, telemetry, and commands can be found in the F' user guide. [User Guide](docs/UsersGuide/FprimeUserGuide.pdf). *Side note:* Ports are also defined with XML, however; this application does not need any customized ports and thus we need not elaborate here. @@ -98,7 +104,7 @@ mkdir -p GpsApp/Gps cd GpsApp/Gps ``` -Next, in this directory, we will create a file called *GpsComponentAi.xml* filled with the below text. This represents our Components design by defining +Next, in this directory, we will create a file called *GpsComponentAi.xml* filled with the below text. This represents our component's design by defining the ports it uses to connect with other components and the files used to specify commands, telemetry, and events. As can be seen, we are creating our component to have 5 ports: @@ -124,9 +130,9 @@ file should look like this: Svc/Sched/SchedPortAi.xml Fw/Tlm/TlmPortAi.xml Fw/Cmd/CmdResponsePortAi.xml - Svc/FileDownlink/Commands.xml - Svc/FileDownlink/Telemetry.xml - Svc/FileDownlink/Events.xml + GpsApp/Gps/Commands.xml + GpsApp/Gps/Telemetry.xml + GpsApp/Gps/Events.xml @@ -158,11 +164,10 @@ see this step later. ## Creating Commands.xml, Events.xml and Telemetry.xml Dictionaries These three XML dictionaries define the structure of commands, events, and telemetry that our component uses. This allows the auto-coding system -to automatically generate the needed code to process commands, and emit events and telemetry. This save the developer for writing the specific code -to drive the component. +to automatically generate the needed code to process commands, and emit events and telemetry. This allows the developer to concentrate on the specific code for the component. First we will create a command dictionary. The purpose of our command is to report the lock status of the GPS unit. This command will trigger an event -which will report if the GPS is locked or not. Command.xml should look like the following: +which will report if the GPS is locked or not. Commands.xml should look like the following: ``` @@ -174,9 +179,7 @@ which will report if the GPS is locked or not. Command.xml should look like the ======================================================================--> - + ``` -**Note:** opcode_base is auto-filled by the auto-coder giving out component's opcodes a unique offset so that we need not worry about what op-codes are -defined outside this component. We can just number them within the component, and expect the auto-coder to resolve collisions by prefixing the op-codes -with a defined offset. - Next we will create an Events.xml dictionary that setup the events our component can log. In this case we have two events, GPS locked and GPS lock lost. Here again we have and ID base allowing us to fill in the event offsets later. The Events.xml file should look like: @@ -206,9 +205,7 @@ Here again we have and ID base allowing us to fill in the event offsets later. T ======================================================================--> - + - + ``` -Now our dictionaries are setup. Before we can continue, we need to add *GpsIdBase* into the auto-coder constants file located at *fprime/Fw/Cfg/AcConstants.ini*. The end of this file should look like the following. This is the offset we disscussed earlier. In order to prevent collisions, it should be unique for other base ids set in -this file. - -``` -... -# -# Demo application components -# -# Base IDs -GpsIdBase = 0x0000 ; Starting range for GPS IDs -# Define starting opcodes -GpsIdOpcodeBase = %(GpsIdBase)s ; Starting range for GPS IDs -# Define starting telemetry IDs -GpsIdTelemetryBase = %(GpsIdBase)s ; Starting telemetry ID for GPS -# Define starting event IDs -GpsIdEventsBase = %(GpsIdBase)s ; Starting Event ID for GPS -``` - ## Setting Up the Build System for Gps and GpsApp The make system is configured to use *fprime/mk/configs/modules/modules.mk* as a place for specifying builds and various deployments. If we look @@ -334,7 +311,7 @@ GpsApp_MODULES := \ $(UTILS_MODULES) ... ``` -This adds our (future) topology to the make system as well as the component we just created. This allows us to generate make files, and make our component. In +This adds our (future) topology to the make system as well as the component we just created. This allows us to generate make files and make our component. In addition, we will be able to build our project's topology one we add that. *Note:* since we already added a folder for our Topology to the make system we'll need to create a placeholder folder (below) before we can build. @@ -346,7 +323,7 @@ DEPLOYMENTS := Ref GpsApp acdev Given that we have already defined our *Topology* folder in the *GpsApp/Top* line above, we will need to add a placeholder for the Topology of our GpsApp, which we will fill later. Make the folder *fprime/GpsApp/Top* and add an empty file *mod.mk*. We will fill this folder and mod.mk file -lateri, but creating it here enables us to build our component. Now our make system should be ready for us to build our new module, and take advantage of +later, but creating it here enables us to build our component. Now our make system should be ready for us to build our new module and take advantage of the code-generation that is available. ## Setting Up Module Make Files and Code @@ -388,7 +365,7 @@ HDR = \ ``` *Note:* since we have not created the code files yet, we leave them commented out. This allows us to test the make commands, without erring for missing files. We can test the make system by running the following commands. *make gen_make* will auto-generate parts of the make system, *make -clean* cleans the module, and *make* build the module. +clean* cleans the module, and *make* builds the module. ``` make gen_make @@ -401,19 +378,18 @@ If these commands pass without errors, we are ready to start coding our module. Now it is time to code our module to read the GPS module and downlink the GPS telemetry. This is where the framework will help us considerably. All these previous steps set us up to use the auto-coding features of F'. We can generate the basic implementation of the code by using the make -command *make impl*, which generates needed *GpsComponentImpl.cpp-tmpl* and *GpsComponentImpl.hpp-tmpl* files. We can use these as bases for our -implementation. In adition, the framework will also generate * *Ac.?pp* files, which handle the work of connecting ports allowing us to write -minimal code to support the component interface. Below we will take a look. First we generate code templates, and move them into place (because +command *make impl*, which generates needed *GpsComponentImpl.cpp-tmpl* and *GpsComponentImpl.hpp-tmpl* files. We can use these as the basis for our +implementation. In addition, the framework will also generate * *Ac.?pp* files, which handle the work of connecting ports allowing us to write +minimal code to support the component interface. First we generate code templates, and move them into place (because don't already have implementations we can safely rename the template files). ``` make impl -mv GpsComponentImpl.cpp-tmpl GpsComponentImpl.cpp -mv GpsComponentImpl.hpp-tmpl GpsComponentImpl.hpp +mv GpsComponentImpl.cpp-template GpsComponentImpl.cpp +mv GpsComponentImpl.hpp-template GpsComponentImpl.hpp ``` -*Note:* if the developer previously created the implementation .cpp and .hpp files for out component, then moving the templates in place could -be dangerous. +*Note:* If the developer regenerates the templates, care must be taken to not overwrite already implemented code by copying the templates to the implementation files. These template file contents are in the following sections. @@ -565,9 +541,9 @@ Here it can be seen that we have two actions "TODO". First we will need to imple the second is to implement a command handler for *Gps_ReportLockStatus_cmdHandler*. Both are port calls that will be made into our component. Ports are found in the GpsComponentAi.xml, however; only our *schedIn* port is used directly. The rest are called as part of telemetry, event logging, or command processing and thus have helpful wrappers (seen below). -schedIn represents a call from a rate group driver. It is called a a set rate, e.g. 10Hz based on the rate group to which it -is connected. We will use this schedIn call to read the UART interface at a set rate of 1HZ. *Gps_ReportLockStatus_cmdHandler* is a -handler that implements the function for the command we defined in Command.xml. We also have the following out-going port calls, +schedIn represents a call from a rate group driver. It is called at a set rate, e.g. 10Hz based on the rate group to which it +is connected. We will use this schedIn call to read the UART interface at a set rate of 1Hz. *Gps_ReportLockStatus_cmdHandler* is a +handler that implements the function for the command we defined in Command.xml. We also have the following outgoing port calls, and events that can be used as part of our code. 1. log_ACTIVITY_HI_Gps_LockAquired: used to emit the event *Gps_Lock_aquired* as defined in Events.xml @@ -580,7 +556,7 @@ and events that can be used as part of our code. In order to make a GPS processor, we need to take the following steps: -0. Implement the schedIn function (called at 1HZ) +0. Implement the schedIn function (called at 1Hz) 1. (Re)initialize the UART in the call to schedIn 2. Read UART in schedIn 3. Parse UART data in schedIn @@ -685,7 +661,7 @@ namespace GpsApp { // Step 0: schedIn // - // By implementing this "handler" we can respond to the 1HZ call allowing + // By implementing this "handler" we can respond to the 1Hz call allowing // us to read the GPS UART every 1 second. void GpsComponentImpl :: schedIn_handler( @@ -707,7 +683,7 @@ namespace GpsApp { return; } //Then receive data from the GPS. Should block until available - //and thus, this module should not be driven at a rate faster than 1HZ + //and thus, this module should not be driven at a rate faster than 1Hz //Step 2: read the UART // Read the GPS message from the UART ssize_t size = read(m_fh, buffer, sizeof(buffer)); @@ -881,6 +857,24 @@ namespace GpsApp { #endif ``` +Next, we need to add (or uncomment) our .cpp and .hpp to the mod.mk in the GpsApp directory. The final version will look like this: + +### fprime/GpsApp/Gps/mod.mk (final) +``` +# ---------------------------------------------------------------------- +# mod.mk +# ---------------------------------------------------------------------- + +SRC = \ + GpsComponentAi.xml \ + GpsComponentImpl.cpp + +HDR = \ + GpsComponentImpl.hpp + +#SUBDIRS = test +``` + Finally, regenerate the makefiles, clean, and build. We will use this pattern a lot. ``` make gen_make @@ -897,11 +891,12 @@ if this will work. Generally, this process is done with a design tool like Magic have access to this tool, the topology Ai is provided below. The user may then edit it to make changes. First, the Reference application's topology is copied into the *Top* folder of *GpsApp* application and we'll grab the deployment makefile -too. +too. We do this as a convienence to save time during this tutorial. It is easier and faster to start with the Reference application's files +and modify them to construct our topology. ``` cp -r fprime/Ref/Top fprime/GpsApp/Top -cp fprime/Ref/Makefile fprimt/GpsApp +cp fprime/Ref/Makefile fprime/GpsApp ``` Then update *fprime/GpsApp/Makefile* to set the following line to our deployment's name *GpsApp*. @@ -912,18 +907,21 @@ DEPLOYMENT := GpsApp After this adjustment to the make system, we need to add 3 custom files that represent our Topology. These files are the following: -1. **RefTopologyAppAi.xml**: the design file showing the list of components, and the connections between components. +1. **GpsTopologyAppAi.xml**: the design file showing the list of components, and the connections between components. This file is based +on RefTopologyAppAi.xml from the reference application. GpsTopologyAppAi.xml should replace RefTopologyAppAi.xml. 2. **Components.hpp**: the header file declaring in code the same components as listed in the topology ai XML, along with includes of the headers that define them. 3. **Topology.cpp**: top level code, main function, and initialization of the components, threads, and registration of commands. -Essentially, RefTopologyAppAi.xml is the design, Components.hpp is the definitions, and Topology is the implementation code. All of these +Essentially, GpsTopologyAppAi.xml is the design, Components.hpp is the definitions, and Topology.cpp is the implementation code. All of these files are referenced by the make files we inherited from the reference app. Building the distribution (fprime/GpsApp) will include the topology (fprime/GpsApp/Top) as its entry-point creating a single application, which represents our software. Sample versions of these files are provided below, and are annotated with comments representing the changes made to support the Gps Application. **Note:** these files are available in a working repository at: -[https://github.com/LeStarch/fprime/tree/gps-application](https://github.com/LeStarch/fprime/tree/gps-application) in case the user prefer a direct checkout of working code. +[https://github.com/LeStarch/fprime/tree/gps-application](https://github.com/LeStarch/fprime/tree/gps-application) in case the user prefers a direct checkout of working code. + +We will also need to update the mod.mk in the Top directory to change the name of "RefTopologyAppAi.xml" to "GpsTopologyAppAi.xml". Once these files have been added to the *fprime/GpsApp/Top* folder, we have a complete project. The project can be built by changing directory to the deployment directory, issuing our build commands and then running the executable. @@ -953,9 +951,6 @@ If you see output similar to the following, when running with the UART GPS you h [ERROR] Failed to open file: /dev/ttyACM0 ``` -That is it. In the next tutorial (comming soon), we'll cover how to connect this reference application to the -GSE environment in order to read the telemetry we are downlinking. - ### Topology.cpp (Sample) ``` #include @@ -1410,7 +1405,7 @@ extern GpsApp::GpsComponentImpl gpsImpl; #endif ``` -### RefTopologyAppAi.xml (Sample) +### GpsTopologyAppAi.xml (Sample) ```