Use C API to Access Model Parameters

This example helps you get started writing application code to interact with model parameters. To get started writing application code to interact with model signals and states, see Use C API to Access Model Signals and States.

The C API provides you with the flexibility of writing your own application code to interact with model signals, states, root-level inputs/outputs, and parameters. Your target-based application code is compiled with generated code into an executable program. The target-based application code accesses the C API structure arrays in model_capi.c (or .cpp). You might have host-based code that interacts with your target-based application code. Or, you might have other target-based code that interacts with your target-based application code. The files rtw_modelmap.h and rtw_capi.h, located in matlabroot/rtw/c/src (open), provide macros for accessing the structures in these arrays and their members.

Here is an example application that prints the parameter values of tunable parameters in a model to the standard output. This code is intended as a starting point for accessing parameter addresses. You can extend the code to perform parameter tuning. The application:

  • Uses the rtmGetDataMapInfo macro to access the mapping information in the mmi substructure of the real-time model structure

    rtwCAPI_ModelMappingInfo* mmi = &(rtmGetDataMapInfo(rtM).mmi);

    where rtM is the pointer to the real-time model structure in model.c (or .cpp).

  • Uses rtwCAPI_GetNumModelParameters to get the number of model parameters in mapped C API:

    uint_T nModelParams = rtwCAPI_GetNumModelParameters(mmi);

  • Uses rtwCAPI_GetModelParameters to access the array of model parameter structures mapped in C API:

    rtwCAPI_ModelParameters* capiModelParams = \
 rtwCAPI_GetModelParameters(mmi);

  • Loops over the capiModelParams array to access individual parameter structures. A call to the function capi_PrintModelParameter displays the value of the parameter.

The example application code is provided below:

{
/* Get CAPI Mapping structure from Real-Time Model structure */
rtwCAPI_ModelMappingInfo* capiMap = \
&(rtmGetDataMapInfo(rtwdemo_capi_M).mmi);

/* Get number of Model Parameters from capiMap */
uint_T nModelParams = rtwCAPI_GetNumModelParameters(capiMap);
printf("Number of Model Parameters: %d\n", nModelParams);

/* If the model has Model Parameters, print them using the
application capi_PrintModelParameter */
if (nModelParams == 0) {
   printf("No Tunable Model Parameters in the model \n");
}
else {
   unsigned int idx;

   for (idx=0; idx < nModelParams; idx++) {
      /* call print utility function */
      capi_PrintModelParameter(capiMap, idx);
   }
}
}

The print utility function is located in matlabroot/rtw/c/src/rtw_capi_examples.c. This file contains utility functions for accessing the C API structures.

To become familiar with the example code, try building a model that displays the tunable block parameters and MATLAB® variables. You can use rtwdemo_capi, the C API example model. The following steps apply to both grt.tlc and ert.tlc system target files, unless otherwise indicated.

  1. At the MATLAB command line, enter rtwdemo_capi to open the example model.

  2. Save the top model rtwdemo_capi and the referenced model rtwdemo_capi_bot to the same writable work folder.

  3. If you are licensed for Embedded Coder® software and you want to use the ert.tlc system target tile instead of the default grt.tlc, use model configuration parameter System target file to select an ert.tlc system target file. Make sure that you also select ert.tlc for the referenced model rtwdemo_capi_bot.

  4. Confirm these model configuration parameter settings:

    1. Select Generate C API for parameters.

    2. If you are using the ert.tlc system target file, select Support complex numbers.

    3. Select MAT-file logging.

    4. Click Apply.

    5. Update configuration parameter settings in the referenced model, rtwdemo_capi_bot, to match changes you made in the top model.

  5. Use the Custom Code pane to embed your custom application code in the generated code. Select the Custom Code pane, and then click Initialize function. The Initialize function input field is displayed.

  6. In the Initialize function input field, type or copy and paste the example application code shown above step 1. This embeds the application code in the model_initialize function.

    Note

    If you renamed the top model rtwdemo_capi, update the name rtwdemo_capi_M in the application code to reflect the new model name.

  7. Click Include directories, and type matlabroot/rtw/c/src, where matlabroot represents the root of your MATLAB installation folder. (If you are specifying a Windows® path that contains a space, place the text inside double quotes.)

  8. In the Additional Build Information subpane, click Source files, and type rtw_capi_examples.c.

    Click Apply.

  9. Clear model configuration parameter Generate code only.

    Build the model and generate an executable program. For example, on a Windows system, the build generates the executable file rtwdemo_capi.exe in your current working folder.

  10. In the MATLAB Command Window, enter !rtwdemo_capi to run the executable file. Running the program displays parameter information in the Command Window.

    >> !rtwdemo_capi

** starting the model **
Number of Model Parameters: 5
Ki =
    7
Kp =
    4
p1 =
    0.15
    0.36
    0.81
p2 =
    0.09    0.75    0.57
    0.13    0.96    0.059
p3 =
ans(:,:,1) =
    0.23    0.82    0.04    0.64
    0.35    0.01    0.16    0.73

ans(:,:,2) =
    0.64    0.54    0.74    0.68
    0.45    0.29    0.18    0.18

Related Topics

Simulink Coder Documentation

Support