Key Points
- Basecamp apps use a JSON parameter file to define deployment configurations. Apps read this file during their initialization.
- Like NASA cFS apps, Basecamp apps use C header files for configuration parameters but limits them to parameters that must be part of the compilation process.
- The Basecamp application framework library provides utilities that make it easy to define and access the JSON configuration parameters.
- Code snippets from Basecamp’s demo app serve as examples.
Introduction
The reusable NASA cFS apps use configuration parameters to customize app deployments to different platforms. C header files are used to define parameters that are defined during the build process. They have either a mission or platform scope. Mission parameters are used for every instance of an app within the scope of a mission and platform parameters are for the deployment of an app on a particular hardware/operating system platform.
Parameter tables are another method for defining configuration parameters that can be changed while an app is executing. The default table is defined in a C source file that is converted to a binary table file during the build process. The cFS Table Service manages the ground interface processes for loading and dumping an app’s parameter table. Since tables are binary files, tools are required for creating the binary from text and for displaying text from the binary.
Basecamp apps use JSON files for parameter tables and app initialization parameters. JSON initialization files are the focus of this article. Code snippets are from Basecamp’s demo app.
JSON Initialization Files
All deployment configurations are defined in an app’s JSON file unless the configuration must be part of the build process in which case they are defined in C header files. For example, parameters that impact a data structure must be in a C header file.
By convention the JSON filename is xxx_ini.json and the filename is defined in the app’s xxx_platform_cfg.h file where xxx is the app name. As shown below the parameters are defined in the JSON “config” object as key-value pairs. Parameter types can be 32-bit unsigned integers, floats or strings.
Note
- Description is an array of strings that is used for parameter comments.
- Topic Identifiers (*_TOPICID) are defined in this file. The names must match the names used in the Electronic Data Sheet file that defines the project’s topic IDs.
Coding Steps
Basecamp’s application framework abstracts implementation details so developers can easily define and access JSON parameters. Every Basecamp app has an app configuration file named app_cfg.h. See the cFS Basecamp Application Developer’s Guide at https://github.com/cfs-tools/cfs-basecamp/blob/main/docs/basecamp-app-dev.pdf for details. JSON initialization parameters are defined in app_cfg.h as follows:
Complete the definitions and declarations in the app’s main header and source files as follows:
The final steps include instantiating the IniTbl object and accessing the parameters. Defining the following macro improves readability since a pointer to the IniTbl object is frequently referenced.
#define INITBL_OBJ (&(AppCDemo.IniTbl))
An IniTbl object is constructed as follows:
INITBL_Constructor(INITBL_OBJ, APP_C_DEMO_INI_FILENAME, &IniCfgEnum);
This example shows how the JSON parameters are accessed when the demo app’s command pipe is created:
CFE_SB_CreatePipe(&AppCDemo.CmdPipe, INITBL_GetIntConfig(INITBL_OBJ, CFG_APP_CMD_PIPE_DEPTH), INITBL_GetStrConfig(INITBL_OBJ, CFG_APP_CMD_PIPE_NAME));
Concluding Remarks
Each app’s JSON initialization parameter filename must be added to the “FILELIST’ in targets.cmake. Building a target with “make topicids” invokes the topic ID tool that populates the topic ID parameter values in the JSON files.
App functional objects often use deployment configurations. The object owner passes either a pointer to the app’s IniTbl object (const INITBL_Class_t *IniTbl) or individual parameters depending on the number of parameters. A functional object can either store the IniTbl pointer or the configuration values to access the values.
Operators can change an app’s initialization parameters and restart the app to have the changes take effect without rebuilding the cFS target. Note that initialization parameters are not like parameter tables that allow operators to load and dump them while an app is executing.