Cookiecutter: F Prime Component

WARNING: This template uses the dictionary feature, which requires cookiecutter 1.5.0 or higher, AND there is a bug that requires click to be less than version 8.0.0. For more information, see Cookiecutter GitHub issue # 1558. To install a compatible version of click:

pip install click==7.1.2

Cookiecutter template for a F Prime deployment, to help with reducing the copy-pasta effect while creating new deployments. There are just enough pieces to remember to change/fix, that it is rather challenging to do without a template. So here is a template to fill in all the major adjustments, so you can spend time developing a deployment or writing a component instead of scratching your head over why you get weird errors.

This template currently supports only "F Prime as a library" style deployements where F Prime is probably a git submodule in the project. If enough interest is generated for the old-style clone-and-own deplyments, we will look into adding that support.

Table of Contents

• Features
• Requirements
• Usage and options
• Changelog

Features

• Working deployment created by running the Cookiecutter.
• Options to include or exclude several F Prime services, like health pinging.
• Creates a single deployment-owned component, especially useful for excercising a utility component that is under development.
• Choice of multiple target platforms for platform specific tweaks.
• Option to generate an Arduino platfrom deployment.
• Choice of various licenses.

Requirements

Projects using this template have these minimal dependencies:

• Cookiecutter - just for creating the project

To get quickly started on a new system, just install Cookiecutter. You should do this in your fprime-venv. To install it, just run this in your shell or command prompt, within the venv environment:

pip install cookiecutter click==7.1.2

Usage and options

This template is intended to make it easy to generate all the boilerplate required for a F Prime deployment and a single component internal to that deployment. A collection of components along with a mission/project configuration [deployment] completes the framework to fill out a robotic software project; e.g.: a balloon payload, an wheeled rover, or maybe a satellite.

First navigate to the directory where you want to add your deployment. The template is going to create the folder containing your component in the current directory (you should not try to create the folder ahead of the template). Next, generate the deployment's boilerplate:

cookiecutter gh:SterlingPeet/cookiecutter-fprime-deployment

You will be asked for these fields:

Template variable	Default	Description
full_name	"Sterling Peet"	Main author of this deployment. Can be set in your ~/.cookiecutterrc config file.
email	"noreply@nospam.com"	Contact email of the author. Can be set in your ~/.cookiecutterrc config file.
deployment_display_name	"My Example"	The printed name of this deployment for documentation and strings. It should be concise and convey the purpose of the deployment.
dep_short_description	"An example deployment [...]"	One line description of the deployment's purpose (used in headers and comments).
deployment_slug	"MyExample"	A slug is a simplified version of the deployment_name, which will be used for the topology assembly name and file names within the deployment folder structure. It should be TitleCase with no spaces or special characters.
deployment_path	"example/path"	This is the path from the F Prime root to the current directory, not including the deployment's folder. Do not add a / to the front or back of the path.
deployment_path_to_project_root	".."	This is the path from inside the deployment folder to the main project root. This is usually just up one directory.
deployment_path_to_fprime_framework	"../fprime"	This is the path from inside the deployment folder to the folder containing F Prime. In most cases, these two folders are adjacent in the project root folder.
deployment_target_platform_support	"Native"	Target platform for the deployment. This gets used in the settings.ini file to avoid typing the platform when invoking fprimt-util.
deployment_baremetal_scheduler	"no"	Select the bare metal scheduler instead of the normal Pthreads scheduler. Small platforms may not support Pthreads, and true bare metal platforms may not even have threading support at all. If you don't know that you want the bare metal schedular, you don't.
deployment_rg_sched_contexts_hpp	"no"	Use a separate contexts header file to define the deployment's rate group contexts.
deployment_parameter_support	"yes"	Include components and connections to support persistent parameter storage using the F Prime parameter subsystem.
deployment_command_sequence_support	"yes"	Include the components and connections needed for command sequence support.
deployment_event_text_log_support	"yes"	Include the components and connections needed for for local text logging of events.
deployment_file_xfer_support	"yes"	Include the components and connections needed for file uplink and downlink support.
deployment_health_support	"yes"	Include the components and connections needed for component health check/ping support.
deployment_ref_doc_boilerplate	"no"	Extra boilerplate documentation to support better understanding of the project.
component_name	"Led Blinker"	The printed name of this internal deployment component for documentation and strings. It should be concise and convey the purpose of the component.
component_short_description	"An example component [...]"	One line description of the project (used in headers and comments). This should describe the purpose of the component in the Imperetive Voice, not the context where the component is used.
component_slug	"LedBlinker"	A slug is a simplified version of the component_name, which will be used for the class name and file names within the component folder structure. It should be TitleCase with no spaces or special characters.
component_dir_name	"LedBlinker"	This is the name of the component's main directory. The obvious choice is to use your deployment_slug for this field.
component_explicit_component_suffix	"Component"	The general convention is for F Prime components to have the Component suffix for file names and class names. While it is not required, the Autocoder will assume this format, and Autocoder provided templates may be more difficult to adapt if this is not selected.
component_explicit_common	""	If preferred, the cpp file with the common implementation code can be appended with the suffix Common.
component_impl_suffix	""	Some F Prime components use the Impl suffix for component class names and files. It is redundant because the autocoded base file always uses the suffix Base, but is available for backwards compatibility and completeness.
component_path_to_fprime_root	"../.."	This is the path from inside the component's folder to the F Prime root. Do not add a / to the front or back of the path (this should auto-populate from the deployment path).
component_namespace	"MyExample"	This is the namespace where your component's implementation class resides. It is usually the same but can be different from the path. If you want multiple levels of namespace, use the :: notation.
component_kind	"passive"	You can choose and active or passive component type. If you change your mind, is it set in the Autocoder input file (and some of the component's port kinds may also affected).
component_multiplatform_support	"no"	If you need different implementations of your component based on the target platform, choose yes to get additional support file templates.
component_instance_name	"ledBlinker"	This is the variable name given to the instantiation of your component in the topology.
startup_delay_msec	"2000"	Startup delay during the deployment startup, so you can tell if you got the deployment into a boot loop. This is only available on the Arduino platform.
startup_arduino_led_flash	"yes"	Flash the onboard LED to signal the startup process has worked. Only available on Arduino.
arduino_log_stream	"Serial"	This is the Arduino stream where the debug statements for the main deployment will print.
license	"None"	License to use. Available options: None (no license text, assume project level license) BSD license MIT license What license to pick? https://choosealicense.com/
internal_use	"default"	This variable is an autogenerated dictionary built from the previous answers. You should not need to adjust it, but if you are getting stuck, see the very top of this README for a solution.

You should now have a basic deployment that can be compiled and run.

If you want to add components to the deployment, you can do that next. This can be done by adding a line like this, near the bottom of the deployment's CMakeLists.txt file:

add_fprime_subdirectory("${CMAKE_CURRENT_LIST_DIR}/../Prjct/Grp/MyExample")

Then you need to (possibly purge) and generate the new cmake config in that deployment:

fprime-util generate
fprime-util build

Now you should be able to run the executable from the build folder.

Changelog

See CHANGELOG.rst.