diff --git a/include/openthread/instance.h b/include/openthread/instance.h index e2cc51602..234ee3428 100644 --- a/include/openthread/instance.h +++ b/include/openthread/instance.h @@ -52,7 +52,7 @@ extern "C" { * * @note This number versions both OpenThread platform and user APIs. */ -#define OPENTHREAD_API_VERSION (476) +#define OPENTHREAD_API_VERSION (477) /** * @addtogroup api-instance diff --git a/include/openthread/platform/radio.h b/include/openthread/platform/radio.h index 8f7f38f9a..7cef06b9d 100644 --- a/include/openthread/platform/radio.h +++ b/include/openthread/platform/radio.h @@ -865,6 +865,17 @@ otError otPlatRadioReceive(otInstance *aInstance, uint8_t aChannel); /** * Schedule a radio reception window at a specific time and duration. * + * After a radio reception is successfully scheduled for a future time and duration, a subsequent call to this + * function MUST be handled as follows: + * + * - If the start time of the previously scheduled reception window has not yet been reached, the new call to + * `otPlatRadioReceiveAt()` MUST cancel the previous schedule, effectively replacing it. + * + * - If the start of the previous window has already passed, the previous receive schedule is already being executed + * by the radio and MUST NOT be replaced or impacted. The new call to `otPlatRadioReceiveAt()` would then schedule + * a new future receive window. In particular, if the new `otPlatRadioReceiveAt()` call occurs after the start + * but while still within the previous reception window, the ongoing reception window MUST NOT be impacted. + * * @param[in] aChannel The radio channel on which to receive. * @param[in] aStart The receive window start time relative to the local * radio clock, see `otPlatRadioGetNow`. The radio @@ -879,7 +890,7 @@ otError otPlatRadioReceive(otInstance *aInstance, uint8_t aChannel); * reception has either succeeded or failed. * * @retval OT_ERROR_NONE Successfully scheduled receive window. - * @retval OT_ERROR_FAILED The receive window could not be scheduled. + * @retval OT_ERROR_FAILED The receive window could not be scheduled. For example, if @p aStart is in the past. */ otError otPlatRadioReceiveAt(otInstance *aInstance, uint8_t aChannel, uint32_t aStart, uint32_t aDuration);