[Vitis Vision Library] Kalman Filter Kernel documentation is misleading and incomplete

[dshemnv]

Hi.

I've been trying to implement a Kalman Filter by making use of Vitis Vision Library. If one follows the official documentation, it would simply not work.

Here is what the documentation states about the Kalman Filter Kernel usage:

//Control Flag
    INIT_EN      = 1; TIMEUPDATE_EN = 2; MEASUPDATE_EN = 4;
    XOUT_EN_TU  = 8; UDOUT_EN_TU    = 16; XOUT_EN_MU    = 32;
    UDOUT_EN_MU = 64; EKF_MEM_OPT   = 128;
    //Load A_mat,B_mat,Uq_mat,Dq_mat,H_mat,X0_mat,U0_mat,D0_mat,R_mat
    //Initialization
KalmanFilter(A_mat, B_mat, Uq_mat, Dq_mat,  H_mat, X0_mat, U0_mat, D0_mat, R_mat, u_mat, y_mat, Xout_mat, Uout_mat, Dout_mat, INIT_EN);

for(int iteration=0; iteration< count; iteration++)
{
    //Load u_mat (control input)
    for(int index=0; index <C_CTRL; index ++)
        u_mat.write_float(index, control_input[index]);

//Time Update
KalmanFilter(A_mat, B_mat, Uq_mat, Dq_mat,  H_mat, X0_mat, U0_mat, D0_mat, R_mat, u_mat, y_mat, Xout_mat, Uout_mat, Dout_mat, TIMEUPDATE_EN + XOUT_EN_TU + UDOUT_EN_TU);

//Load y_mat (measurement vector)
    for(int index =0; index <M_MEAS; index ++)
        y_mat.write_float(index, control_input[index]);

//Measurement Update
KalmanFilter(A_mat, B_mat, Uq_mat, Dq_mat,  H_mat, X0_mat, U0_mat, D0_mat, R_mat, u_mat, y_mat, Xout_mat, Uout_mat, Dout_mat, MEASUPDATE_EN + XOUT_EN_MU + UDOUT_EN_MU);
}

You can clearly see three steps:

• Initialization, flag INIT_EN
• Time update (Update), flags TIMEUPDATE_EN + XOUT_EN_TU + UDOUT_EN_TU
• Measure update (Correction), flags MEASUPDATE_EN + XOUT_EN_MU + UDOUT_EN_MU

In practice, calling KalmanFilter with only INIT_EN flag would result in what seems to be a CU deadlock since the Kernel just hangs in the START state (verified by using xbutil examine --device --report all).

Calling KalmanFilter with flag INIT_EN + TIMEUPDATE_EN + XOUT_EN_TU + UDOUT_EN_TU will work only once, then the kernel will hang in a START state.

Actually, in the L2 example for Kalman Filter, the flag is set to 103, which is INIT_EN + TIMEUPDATE_EN + MEASUPDATE_EN + XOUT_EN_MU + UDOUT_EN_MU. This is completely misleading in comparison to the documentation and is not further explained anywhere. Why would you have TIMEUPDATE_EN and MEASUPDATE_EN flags if, in practice, both of them are required for the Kernel to work? Is the overhead of doing a measurement update necessary if only the prediction output is required?

Calling KalmanFilter with flag 103 will work. But then calling KalmanFilter with control flag set to TIMEUPDATE_EN + XOUT_EN_TU + UDOUT_EN_TU to get the prediction output will work once, and then kernel will hang in the START state on subsequent executions.

More explanation about how the control flags should be used would be of great help.

Other suggestions:

• Adding assertions for the matrices size.
• Add some references for the UDU factorization, which was not that trivial to find.