Generate Code for Online State Estimation in MATLAB

You can generate C/C++ code from MATLAB^® code that uses extendedKalmanFilter, unscentedKalmanFilter and particleFilter objects for online state estimation. C/C++ code is generated using the codegen (MATLAB Coder) command from MATLAB Coder™ software. Use the generated code to deploy online estimation algorithms to an embedded target. You can also deploy online estimation code by creating a standalone application using MATLAB Compiler™ software.

To generate C/C++ code for online state estimation:

1. Create a function to declare your filter object as persistent, and initialize the object. You define the object as persistent to maintain the object states between calls.

   function [CorrectedX] = ukfcodegen(output)
   % Declare object as persistent.
   persistent obj;
   if isempty(obj)
   % Initialize the object.
   obj = unscentedKalmanFilter(@vdpStateFcn,@vdpMeasurementFcn,[2;0]);
   obj.MeasurementNoise = 0.01;
   end
   % Estimate the states.
   CorrectedX = correct(obj,output);
   predict(obj);
   end

   The function creates an unscented Kalman filter object for online state estimation of a van der Pol oscillator with two states and one output. You use the previously written and saved state transition and measurement functions, vdpStateFcn.m and vdpMeasurementFcn.m, and specify the initial state values for the two states as [2;0]. Here output is the measured output data. Save the ukfcodegen.m function on the MATLAB path. Alternatively, you can specify the full path name for this function.

   In the ukfcodegen.m function, the persistent object is initialized with condition if isempty(obj) to ensure that the object is initialized only once, when the function is called the first time. Subsequent calls to the function only execute the predict and correct commands to update the state estimates. During initialization, you specify the nontunable properties of the object, such as StateTransitionFcn (specified in ukfcodegen.m as vdpStateFcn.m) and MeasurementFcn (specified in ukfcodegen.m as vdpMeasurementFcn.m). After that, you can specify only the tunable properties. For more information, see Tunable and Nontunable Object Properties.

   In the state transition and measurement functions you must use only commands that are supported for code generation. For a list of these commands, see Functions and Objects Supported for C/C++ Code Generation (MATLAB Coder). Include the compilation directive %#codegen in these functions to indicate that you intend to generate code for the function. Adding this directive instructs the MATLAB Code Analyzer to help you diagnose and fix violations that would result in errors during code generation. For an example, type vdpStateFcn.m at the command line.

2. Generate C/C++ code and MEX files using the codegen (MATLAB Coder) command from MATLAB Coder software.

   codegen ukfcodegen -args {1}

   The syntax -args {1} specifies an example of an argument to your function. The argument sets the dimensions and data types of the function argument output as a double-precision scalar.

   Note

   If you want a filter with single-precision floating-point variables, you must specify the initial value of the states as single-precision during object construction.

   obj = unscentedKalmanFilter(@vdpStateFcn,@vdpMeasurementFcn,single([2;0]))

   Then to generate code, use the following syntax.

   codegen ukfcodegen -args {{single(1)}

3. Use the generated code.

   • Use the generated C/C++ code to deploy online state estimation to an embedded target.

   • Use the generated MEX file for testing the compiled C/C++ code in MATLAB. The generated MEX file is also useful for accelerating simulations of state estimation algorithms in MATLAB.

     Load the estimation data. Suppose that your output data is stored in the measured_data.mat file.

     load measured_data.mat output
     

     Estimate the states by calling the generated MEX file.

     for i = 1:numel(output)
         XCorrected = ukfcodegen_mex(output(i));
     end

   This example generates C/C++ code for compiling a MEX file. To generate code for other targets, see codegen (MATLAB Coder) in the MATLAB Coder documentation.

Tunable and Nontunable Object Properties

Property Type	Extended Kalman Filter Object	Unscented Kalman Filter Object	Particle Filter Object
Tunable properties that you can specify multiple times either during object construction, or afterward using dot notation	State, StateCovariance, ProcessNoise, and MeasurementNoise	State, StateCovariance, ProcessNoise, MeasurementNoise, Alpha, Beta, and Kappa	Particles and Weights
Nontunable properties that you can specify only once, either during object construction, or afterward using dot notation, but before using the predict or correct commands	StateTransitionFcn, MeasurementFcn, StateTransitionJacobianFcn, and MeasurementJacobianFcn	StateTransitionFcn and MeasurementFcn	StateTransitionFcn, MeasurementLikelihoodFcn, StateEstimationMethod, StateOrientation, ResamplingPolicy and ResamplingMethod
Nontunable properties that you must specify during object construction	HasAdditiveProcessNoise and HasAdditiveMeasurementNoise	HasAdditiveProcessNoise and HasAdditiveMeasurementNoise