Clarification Required on MC_ProgramPositionCommandMotor1() and Position Control Status

[prathmeshpatil06]

Dear ST Community,

I am currently testing the position control functionality using the following API:

MC_ProgramPositionCommandMotor1(target, duration_s);

I would like to clarify the behavior of the duration parameter. Does this parameter define only the expected movement duration, or does the position control algorithm also ensure that the motor reaches the specified target position within that duration?

I am testing a case where the target position is intentionally very large:

float actual = MC_GetCurrentPosition1();
float commanded_target = actual + 10000;

MC_ProgramPositionCommandMotor1(commanded_target, 2.0f);

In this case, completing a 10000-radian movement within 2 seconds is physically unrealistic for my motor.

I am monitoring the control status using the following code:

uint32_t start = HAL_GetTick();

printf("ms (planned %ld ms)\r\n",
       (long)(MC_GetMoveDuration1() * 1000));

while (1)
{
    if (HAL_GetTick() - start < 10000)
    {
        printf("Control status : %d state : %d Fault : %d Ack : %d "
               "Current fault : %d command status : %d\n",
               MC_GetControlPositionStatusMotor1(),
               MCI_GetSTMState(pMCI[M1]),
               MC_GetCurrentFaultsMotor1(),
               MC_AcknowledgeFaultMotor1(),
               MCI_GetCurrentFaults(pMCI[M1]),
               MC_GetCommandStateMotor1());

        HAL_Delay(1000);
    }
    else
    {
        break;
    }
}

My observation is that after approximately 2 seconds, MC_GetControlPositionStatusMotor1() returns:

TC_READY_FOR_COMMAND

However, the motor is still rotating continuously and has not reached the commanded target position.

Could you please clarify:

1. Does duration represent only the planned trajectory duration, or does the API guarantee that the motor will actually reach the target within this duration?
2. If the motor cannot reach the target within the specified duration, what is the expected behavior?
3. Is there a specific position-control timeout, stall detection, position error, or velocity condition that can be used to determine that the target cannot be reached?
4. Is there any recommended way to handle a large target position or a target that cannot be reached within the requested duration?
5. Target commanded
          ↓
   Motor starts moving
          ↓
   Motor becomes stuck / cannot reach target
          ↓
   Target position not reached within expected time
          ↓
   How should firmware detect and report this fault?

I would appreciate your clarification on the expected behavior of these APIs.

Regards,
Prathmesh