Get Started with C API

Use the C API to monitor and tune generated model elements during the execution of generated model code on the target platform. The C API is an optional programmatic interface that you can add to the code generated from a Simulink^® model.

Use the C API:

through the development of your model, to fine tune values of model elements.
after deployment of the generated model code, to calibrate the value of model elements in the generated model code in real time, while it is running on the target platform.

C API Background and Prerequisites

To use the C API, you need to be familiar with these concepts.

Concept	Related Documentation
Using Simulink Coder™ to generate code from your Simulink models	Simulink Coder Code Generation Output
Configuring and controlling the generated model code	Configure Model, Generate Code, and Simulate
Executing the generated model code	How to Interface with Generated Entry-Point Functions
Exchanging data between external code and the generated Simulink model code	Exchange Data Between External Calling Code and Generated Code Exchange Data Between External C/C++ Code and Simulink Model or Generated Code How Generated Code Exchanges Data with an Environment
Monitoring and tuning model elements in the generated model code	Configure Parameters for C Code Generation Real-Time Parameter Tuning (Simulink Real-Time) Create Tunable Calibration Parameter in the Generated Code

To learn about other ways to monitor and tune elements in generated model code, see:

C API Technology

C API is a MathWorks^® developed technology. It is an additional layer to the primary generated model code. The primary generated model code, generated from the model by the Simulink Coder (or the Embedded Coder^®), includes a programmatic interface that your external code uses to invoke the generated code and control its execution. The C API layer provides an additional programmatic interface through which your external code can access the structure and real-time values of model elements. The C API code is written in the same programming language as the primary generated model code. This additional layer provides tools for monitoring and tuning (calibrating) model elements in the generated code in real time, while it is running on the target platform. The C API layer serves as a gateway to accessing elements in the primary code and depends on the primary code. Model elements that are optimized away do not exist in the primary generated code, and are inaccessible through the C API interface.

Instantiation of C API Data Structure Arrays

Once C API is enabled for model model, Simulink Coder (or Embedded Coder) generates two additional files:

A header file model_capi.h
A source file model_capi.c (or model_capi.cpp)

The C API data structures are instantiated in the source file. You do not need to fully understand the instantiation code, but you can examine it to get a general idea about which C API elements were generated. It can also be helpful for debugging purposes. The instantiated C API elements are structure arrays and primitive type arrays. This page provides a high level description of the arrays instantiation. To learn how to write external code that uses these C API structures, see Write External Code to Access Generated C API Code.

The arrays are instantiated statically in the source file. Each model element that is included in the generated C API code has a corresponding entry in one of these arrays. In addition, each array contains a sentinel entry, with all elements set to null values. These are the model element arrays.

Structure Array Variable	Corresponding Element Type
`rtBlockSignals`	Block output signals
`rtRootInputs`	Output signal of root-level input ports
`rtRootOutputs`	Input signal of root-level output ports
`rtBlockParameters`	Block parameters
`rtModelParameters`	Model parameters
`rtBlockStates`	Model states

This code is an example of the instantiation of the root-level input ports array:

/* Root Inputs information */
static const rtwCAPI_Signals rtRootInputs[] = {
  /* addrMapIndex, sysNum, blockPath,
   * signalName, portNumber, dataTypeIndex, 
   * dimIndex, fxpIndex, sTimeIndex
   */
  { 0, 0, TARGET_STRING("CapiConfigDemo/Inport1"),
    TARGET_STRING(""), 1, 0, 0, 0, 0 },

  { 1, 0, TARGET_STRING("CapiConfigDemo/Inport2"),
    TARGET_STRING(""), 2, 0, 0, 0, 0 },

  { /* Sentinel entry */
    0, 0, (NULL), (NULL), 0, 0, 0, 0, 0
  }
};

C API General Workflow

There are two major steps in using C API:

Configure the model to include, in the generated code, C API elements that correspond to the model elements you want to monitor and tune. For more information, see Configure Model to Generate C API Code.
Write code that interacts with the generated C API elements during the execution of the generated model code on the target platform. For more information, see Write External Code to Access Generated C API Code.