Introduction

Background

The External Code Interface (ECI) is an application framework for the Core Slight System (CFS) environment.

According to https://cfs.gsfc.nasa.gov/:

The core Flight System (cFS) is a platform and project independent reusable software framework and set of reusable software applications. There are three key aspects to the cFS architecture:

• a dynamic run-time environment,
• layered software, and
• a component based design.

It is the combination of these key aspects that makes it suitable for reuse on any number of NASA flight projects and/or embedded software systems at a significant cost savings.

Use cases for ECI:

ECI's primarily purpose is to provide a mechanism for executing code which was not writen as a CFS application (called external code) within a CFS environment. The CFE provides a robust API for managing an app's execution and provides a number of services commonly required in a flight software context to its apps, including:

• message passing,
• parameter management,
• and time management, amongst others.

Code missing these API calls is unable to function in a CFS environment and the ECI addresses the fact that there are several cases in which it may be impractical for a piece of code to utilize these CFE APIs. These situations include (but are not limited to):

• Autogenerated Code, whose generator may be difficult to modify/customize to produce the required API calls
• Legacy Code, which may be undesirable to modify on the basis of maintaining heritage or compatibility with existing systems
• Complex algorithms, which may be made more complex by the additions of the CFE APIs within the code

The core of the ECI is a generic CFS application whose interfaces are configured by a user-provided interface definition, which controls how an instantiation of an ECI app manages its CFS interfaces. Depending on the architecture of the external code, the ECI can typically manage the CFS interfaces with no (or minimal) changes to the external code.

The ECI also strives to be concious of resource limitations of embedded applications and so provides compile-time mechanism to only enable needed functionality.

ECI Heritage:

The ECI started as a subcomponent of another tool, the Simulink Interface Layer (SIL), which aimed to smooth the process of generating code from Simulink models and integrating that code into a CFS environment. The SIL contained two parts:

• a code generation target which extended the code generation pipeline to additionally generate a definition of the code's interfaces
• and a framework which used that interface definition to setup and execute that code as a CFS app

The first component continues to be called the SIL, but the second component is now called the ECI.

The SIL/ECI has/is being used on a several NASA missions including LADEE, NICER, GEDI, and PACE and is actively maintained to meet the requirements of those missions and to stay current with ongoing development of the cFE/cFS.

How to Read This Documentation:

These docs are intended to provide enough information for a new user to define and integrate an app using the ECI. The documentation itself takes a couple of forms:

• standard docs (such as this one) describing parts of the framework and workflow
• several examples, which are buildable and runnable
• a continuous integration pipeline which can be used as a recipie

For new users, its highly recommended that you become familiar with the CFS app paradigm and app organization, as the ECI documentation is focused on documenting how ECI changes/fits in with those concepts and not providing a comprehensive guide to those topics. From there, we recommend examining the examples to gain a better understanding on the setup of an ECI app and the CI pipeline as a command-by-command guide for building the examples.

ECI Integration Requirements:

Due to its implementation, external code must have certain properties for it to be compatible with the ECI architecture. These properties can be broken into several categories, listed below:

• Calling:
  • External code must provide a single “Step” function to be called each execution of the app
  • External code may optionally also provide an initialization function and a termination function to implement setup/teardown
  • Step/Init/Term functions must not take any arguments (void/void interface)
• I/O:
  • Each message (input or output) must be a contiguous region of memory
  • Each message structure must have global scope in the external code (so that the ECI can interact with it)
• Parameters:
  • Each parameter table must be a contiguous region of memory
  • Each parameter structure must have global scope in the external code (so that the ECI can interact with it)
• All interfaces must be declared at compilation (can’t register new messages/events/etc at runtime)

For pieces of code which do not adhere to these restrictions, the author might consider writting a think wrapper such that the interface exposed to the ECI is compliant. An example of a wrapper implementation is available in the examples.

Main Components of the ECI:

Given the prevalence of the C language in embedded programming and the cFE, the ECI is designed to be compatible with typical C constructs/workflows. The ECI's interface to the external code takes the form of a header file named eci_interface.h, which is ideally written by a software developer knowledgeable with the target external code. This interface header is compiled together with the ECI source code (which is fully generic) to create the CFS application.

You can find the specification governing the contents of the interface header file in Interface_Spec.md, more details on writing this interface header here, or two examples of these header files in the /examples directory in the repository.

Supported Features:

The ECI was designed to support most core CFE features such as:

• initialization, execution, and termination of application
• input/output message management with CFE Software Bus (SB)
• table management with CFE Table Services (TS)
• housekeeping counter management
• event services registration and event triggering
• Critical Data Store (CDS) nonvolatile storage of data

For a more in depth explanation of the inner workings of ECI, we've created several diagrams indicating the order of events here.

Quick Start:

For people interested in getting their feet wet with the ECI, we've provided a quick start section that covers building ECI apps with both the CFE 6.5 and 6.6 here. This was intended as a quick introduction and avoids the implementation details of integrating an ECI app.

Change Requests and Community Involvement:

ECI is first and foremost a framework designed to support the integration of flight software for NASA missions. Those missions have been and will continue to be the primary drivers of the ECI requirements. That being said, we think there's value in the workflow developed here, as an alternative to traditional app development, and welcomes community involvement. ECI devs plan to be receptive towards issues posted on the official ECI repository on GitHub, provided they don't conflict with internally-generated requirements and pending developer availability.

If you find yourself having trouble with something that hasn't been provided in this documentation, find a problem with the code, or would like to suggest/contribute a feature, please consider opening an issue. The development team for ECI is relatively small and issue-based feedback helps identify, communicate, and allow us to prioritize development and maintenence of the ECI.