FLIGHT CONTROL FRAMEWORK README Team Elderberry (2013)
The Flight Control Framework, or FCF, is a bit of a misnomer in and of itself. While it was originally developed to run on high-power rockets, the core framework itself is extendable to work with practically any two pieces of C code that exchange data. With minimal overhead, this lightweight framework was designed for fast and efficient data transfer between multiple, interrelated, but abstracted, pieces of code. This abstraction is created by allowing these different code fragments, called user modules, to pass data between each other without referencing one another explicitly. Instead, a relationship between any two or more user modules is set up in a language called MIML.
/- All the files that comprise the framework, code generator, modules, Makefile, miml files, helper utilities and other configuration files and scripts are all in the root of the framework repository./documentation- The documentation for the code generation and MIML specification./examples- Example files, demos, miscellaneous code and a reworked copy of the AV3 code that removes GLib and uses the modular framework paradigm./html- The Doxygen user documentation folder. The documentation can also be found here: http://psas.github.com/elderberry//profiler- External profiler that feeds input through sockets from a remote python script./templates- Basic templates for creating modules that connect to libusb or sockets. Read the in-file instructions for how to properly configure and save to a new module file.
The framework itself is simply a conduit for passing data between code modules. It's principally made up of the framework file, fcfutils.c, that includes the main loop and API functions and a collection of sender/receiver relationships, or intermodular data handlers, in the fcfmain.c file.
User hardware modules connect to the framework by passing in their file descriptors to the fcf_add_fd(...) API function in their initialize function. These file descriptors are essential for telling the framework that they have data to pass to other user modules. If the need arises that a module needs to disconnect from the framework, the fcf_remove_fd(...) API function fulfills this purpose.
In rare cases where a user module must end program execution, a third API function, fcf_stop_main_loop(...) is used. This function will stop the framework from iterating over another polling loop and will consequently begin the process of methodically shutting down the application. It is important to note that any user module has the ability to call fcf_stop_main_loop(...).
Once the user modules have registered themselves with the framework using the fcf_add_fd(...) API function, the "main loop," or "polling loop," of the framework checks to see which file descriptors are active. When an active file descriptor is found, the polling callback function located in the respective user module is called.
To allow modules to pass data between each other without having explicit reference to each other, the framework contains two other components to facilitate this: the MIML language and a code generator.
For user modules, MIML is used to detail the data-passing, initialization and finalize functions, as well as its header and object file. The data-passing functions can either be considered "senders" or "receivers," depending on the direction of data flow. Senders, which are not part of the user module itself but are auto-generated using the code generator, initiates the calls to the the receivers.
In a separate file called Main.miml, these user module MIML files are listed as "sources" and coupled with a unique identifier. The intermodular data passing is defined using simple binary hierarchy, headed by the sender and subordinated by the receiver functions.
Once the relationships are set up, the code generator parses the MIML files to create C files, fcfmain.c and fcfmain.h that contain the intermodular data handlers, as well as a Makefile include, Miml.mk.
While user modules have been referenced many times in this document already, they haven't been formally introduced. A user module is a piece of code created by the user that is utilized in conjunction with the framework that serves a specific and usually unique purpose of the application. Examples of user modules may include code that reads from a GPS device off of USB, code that takes in data and prints to disk, or code that holds the state of a game.
There are two general categories of user modules, "software" and "hardware."
Hardware user modules are those that connect to physical devices outside the framework and provide the necessary code to interface and pass data to and from them. Hardware user modules connect to the framework by passing file descriptors into the system to be polled.
Software user modules generally do not use file descriptors, but are instead called into via their receiver functions by other software or hardware user modules. However, software modules that need execution time independent of other modules can use timerfds, or file descriptors that are read at specified time intervals, to fit in the polling paradigm of hardware user modules.
There are a few conventions that will make user modules work more seamlessly with the framework.
-
Tokens: Every module should have a unique identifier that is somewhat descriptive of what it is, but keeps its functions from having namespace collisions. Possible examples include "mouse1" or "diskLogger."
-
Initialize functions: Every user module should have an initialization function. Whether it's setting up dynamically allocated data, referencing a secondary API or library, or simply doing nothing, MIML requires that every user modules have an initialize function. Since its called from auto-generated code, the initialize function should not take any arguments. A recommended naming scheme is:
void init_<module token>(void); -
Finalize functions: Every modules should have a finalize function. This function is used to execute code necessary to shut down the user module before the application terminates, such as deallocating any dynamic memory. Since its called from auto-generated code, the finalize function should not take any arguments. A recommended naming scheme is:
void finalize_<module token>(void); -
Data-passing functions: Receiver functions should at least contain the token of the user module it's being defined in. A recommended naming scheme is:
void get<function name>_<module token>(args);An example might bevoid getMessage_diskLogger(char *buf);Sender functions, which are references to the respective auto-generated intermodular data handler are best defined as:void send<function name>_<module token>(args);An example might bevoid sendMessage_diskLogger(char *buf);User modules may have multiple sender and receiver functions. -
Filenames: A recommended naming scheme for the user modules is module_.c and .h. An example might be "module_diskLogger.c" and "module_diskLogger.h".
To help speed up user module creation and reduce duplicated code clutter, helper files can be included to keep common code out of user modules that use the same bus interface. Included in the framework are two helper files, utils_libusb-1.0.c and utils_sockets.c, and their respective headers that can greatly aid in making user modules that interface with libusb or use socket code for data transfers. Both of these helper files are also used in templates.
For purposes of quickly creating user modules based on libusb or sockets, there are two templates in the "templates" directory that can be modified to create unique instances of user modules. To use the templates, its best to open up the desired file in a text editor and read its directions in the code file itself. They are created so that the user can search-and-replace the ###DEVTAG### value with a unique token in both the .c and .h file and save it with a unique filename (see Section 3.1 for filename conventions).
Due to the need for user module abstraction, the build process for the framework is a little more complicated than that of a typical C application. Here is the general build process:
- User module MIML files and the Main.miml file are passed into the code generator.
- The code generator, upon successful parsing and validation, creates the fcfmain.c file that include the intermodular data handlers and a Miml.mk Makefile include file.
- The Makefile imports the Miml.mk and should successfully compile, link and build the executable "fc."
To help uncomplicate this process, however, the Makefile has been created so that the user only needs to 'make' the project to complete all three steps.
As a helper to the user, a script called header2Miml.py is used to parse the header file of a user module and create the corresponding MIML file. To use this script, however, each function prototype in the header file should have in an inline comment beside it a special miml directive detailing its role in the form "[miml:]" where role can be init, final, receiver or sender . Here is an example of a header file with the special miml directive in the comments:
extern void init_diskLogger(void); // [miml:init]
extern void finalize_diskLogger(void); // [miml:final]
extern void getMessage_diskLogger(char *buf); // [miml:receiver]
extern void sendMessage_diskLogger(char *buf); // [miml:sender]The user can run either ./header2Miml to take in the header and output the miml file. An example would be:
./header2Miml.py module_diskLogger.h module_diskLogger.miml
As a short cut ./header2Miml . An example would be:
./header2Miml.py module_diskLogger
Otherwise, MIML files can be created manually (see separate documentation regarding MIML in documentation folder).
As discussed in the introduction to this section, the easiest way to use the Makefile is to just type "make".
Here are some other possible uses: "make miml" generates Miml.mk. "make" builds the project. Then, every repeated use of "make" rebuilds the project. If one of the ".miml" files changes, make automatically runs the code generator to rebuild fcfmain.c and fcfmain.h. If the miml files change so that modules are added or removed, one would have to rebuild the Miml.mk manually by rerunning "make miml".
A special profiler module can be added to the system to check latency of the framework on a particular machine setup. The directions for installing and using the profiler are as follows:
- Hook up the profile module: Edit Main.miml so that the source and messages sections include the following lines:
sources:
- [PROFILE, module_profile.miml]
messages: PROFILE.sendMessage_profile:
- PROFILE.getMessage_profile
PROFILE.sendMessage_profile3:
- PROFILE.getMessage_profile3
- Run the FC.
- After a couple of seconds, the program prints a report message and terminates. The message is in the format: Finished with count: in sec. , where Y is the time it took to send X dummy messages.
- The value of X can be configured by setting MAX_COUNT in module_profile.c. See module_profile.c for details.