Key Points
- Basecamp apps use an app framework that provides service objects and utility functions.
- The Initialization Table (IniTbl) and Command Manager (CmdMgr) services are used by every app. These services are an integral part of Basecamp app’s object-based design.
- The framework is implemented as a shared library.
App Framework-based Architecture
Here’s the Unified Modeling Language (UML) representation of the top-level app design structure:
Every app has an App Main object (rectangular box) that uses 1 instance of the Application Framework package (folder icon). The Application Framework is a cFS library called APP_C_FW that provides common app services and utilities. It is represented as an aggregate because APP Main contains instances of the framework services it uses. Each app is composed of 0 to N Functional Objects. Functional Objects may reference framework service objects owned by App Main and use framework utilities.
Basecamp’s Demo app (APP_C_DEMO) provides coding examples for how to use all the framework services and many of the utilities.
Framework Services
Framework services are designed as objects which means they have state information that is stored in a structure. The structure typedef naming convention is X_Class_t where X is the name of the service. App Main objects declare an instance of the service object and a pointer to this instance is passed as the first parameter of service functions. If an App’s Functional Object requires access to a service, then the App Main object passes its instance pointer to the functional object. Framework services must be coded as reentrant because they are shared by all the basecamp apps. Reentrant coding is a technique that allows a function to be Interrupted and called again by another execution thread before it finishes executing with the first thread.
Initialization Table (IniTbl)
This service allows apps to define deployment configuration parameters in a JSON file that is read during an app’s startup process. 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. All Basecamp apps use this service, and it is recommended that all user apps use it to at least define command and telemetry message topic identifiers (superset of message IDs). The ‘make topicids’ command invokes a tool that uses the electronic data sheet topic identifier definitions to set the JSON topic identifier parameter values.
During App Main’s initialization process it constructs an IniTbl instance during which the JSON configuration parameters are read. If needed, IniTbl references are passed to Functional Objects. Configuration parameters are accessed using GetTypeConfig() where Type is either a String, Integer, or Float.
Command Manager (CmdMgr)
This service simplifies app command validation and dispatching. It is also an integral part of Basecamp’s object-based design pattern. Command functions are like virtual functions and use a common function prototype. CmdMgr validates command function codes, command lengths and checksums prior to dispatching a command. Command functions return a Boolean value that is used by CmdMgr to manage the app’s command valid and invalid counters that are included in an app’s status telemetry.
During App Main’s initialization process it constructs a CmdMgr instance and registers all app command functions. Each app has a command pipe that is checked as part of its main execution. If a command is received on the pipe, the CmdMgr DispatchCmd() function is called.
Table Manager (TblMgr)
This optional service allows apps to read and write JSON parameter files also known as tables. In cFS nomenclature read and write operations are called table loads and dumps, respectively.
During App Main’s initialization process it constructs a TblMgr instance and sends a reference to the Table Owner object. It also registers TblMgr’s table load and dump commands. The Table Owner object’s constructor constructs the Table Object and registers it with the TblMgr. The default JSON table file is used to populate the Table Owner’s parameter data during the registration process.
The Basecamp table design pattern is to have a separate object for managing the table. Its scope of responsibility is parsing and transferring parameter data to and from the JSON file. The Table Owner understands the purpose of the parameters and how the data is used. It provides an optional Validate() function that validates the data prior to accepting it during a load command. This separation of scope makes it easy for a developer to clone an existing Table Object and make changes specific to the new table’s JSON parsing needs.
Child Manager (ChildMgr)
This optional service provides an infrastructure for running Functional Object functions within the context of a child task. It is designed to help two common child task use cases and is not intended to solve all design scenarios.
In this first use case, the child task main loop pends indefinitely for commands. App Main constructs an instance of ChildMgr and registers the commands that need to be run within the context of a child task. When a command is received the ChildMgr service is invoked to queue the command to the child task. This process uses a mutex to manage access to the queue shared between the parent and child tasks. ChildMgr provides utility functions to periodically suspend the command function’s execution, so it doesn’t hog the CPU. See Basecamp’s File Manager (file_mgr) app for an example. The Demo app (app_c_demo) uses a variation on this design and periodically invokes its child task command in response to a periodic scheduler message.
The second use case is when a child task has an infinite loop that calls a user supplied callback function. App Main constructs an instance of ChildMgr and passes a pointer to the child task’s main function. This function is continuously called until the parent task exits or if the app designer provides a mechanism to terminate the child task. It is the callback function’s responsibility to periodically suspend execution to prevent CPU hogging.
Framework Utilities
CJSON provides an interface to the FreeRTOS coreJSON library that simplifies managing and parsing JSON files. Table Objects use CJSON for managing JSON parameter table files.
Fileutil provides utilities that simplify file management. FileUtil_GetFileInfo() is a commonly used function that validates the filename string and returns the file state as either invalid, nonexistent, open, closed or it’s a directory. See FILE_MGR for example calls.
Pktutil provides general utilities used with command and telemetry packets. For example, the KIT_TO app uses PktUtil_IsPacketFiltered() to determine whether a telemetry packet should be output.