[radio] add OT_RADIO_CAPS_RX_ON_WHEN_IDLE capability

Add a new `OT_RADIO_CAPS_RX_ON_WHEN_IDLE` radio capability which lets
OpenThread know what the radio idle state operation will be: receive
or sleep.

This allows to save power on sleepy devices since the active --> idle
transition is much faster, specially for the cases in which there is
some kind of serialization between OpenThread core and the radio
driver.

examples/platforms/simulation/openthread-core-simulation-config.h

@@ -77,6 +77,10 @@
 #define OPENTHREAD_CONFIG_MAC_SOFTWARE_TX_TIMING_ENABLE 1
 #endif
 
+#ifndef OPENTHREAD_CONFIG_MAC_SOFTWARE_RX_ON_WHEN_IDLE_ENABLE
+#define OPENTHREAD_CONFIG_MAC_SOFTWARE_RX_ON_WHEN_IDLE_ENABLE 1
+#endif
+
 #endif // OPENTHREAD_RADIO
 
 #ifndef OPENTHREAD_CONFIG_PLATFORM_USEC_TIMER_ENABLE

include/openthread/instance.h

@@ -53,7 +53,7 @@ extern "C" {
  * @note This number versions both OpenThread platform and user APIs.
  *
  */
-#define OPENTHREAD_API_VERSION (367)
+#define OPENTHREAD_API_VERSION (368)
 
 /**
  * @addtogroup api-instance

include/openthread/platform/radio.h

@@ -119,7 +119,7 @@ enum
  * The value is a bit-field indicating the capabilities supported by the radio. See `OT_RADIO_CAPS_*` definitions.
  *
  */
-typedef uint8_t otRadioCaps;
+typedef uint16_t otRadioCaps;
 
 /**
  * Defines constants that are used to indicate different radio capabilities. See `otRadioCaps`.
@@ -136,6 +136,7 @@ enum
     OT_RADIO_CAPS_TRANSMIT_SEC     = 1 << 5, ///< Radio supports tx security.
     OT_RADIO_CAPS_TRANSMIT_TIMING  = 1 << 6, ///< Radio supports tx at specific time.
     OT_RADIO_CAPS_RECEIVE_TIMING   = 1 << 7, ///< Radio supports rx at specific time.
+    OT_RADIO_CAPS_RX_ON_WHEN_IDLE  = 1 << 8, ///< Radio supports RxOnWhenIdle handling.
 };
 
 #define OT_PANID_BROADCAST 0xffff ///< IEEE 802.15.4 Broadcast PAN ID
@@ -621,6 +622,15 @@ bool otPlatRadioGetPromiscuous(otInstance *aInstance);
  */
 void otPlatRadioSetPromiscuous(otInstance *aInstance, bool aEnable);
 
+/**
+ * Indicates whether radio should stay in Receive or Sleep state during idle periods.
+ *
+ * @param[in]  aInstance    The OpenThread instance structure.
+ * @param[in]  aEnable      TRUE to keep radio in Receive state, FALSE to put to Sleep state during idle periods.
+ *
+ */
+void otPlatRadioSetRxOnWhenIdle(otInstance *aInstance, bool aEnable);
+
 /**
  * Update MAC keys and key index
  *

src/core/config/mac.h

@@ -395,6 +395,16 @@
 #define OPENTHREAD_CONFIG_MAC_SOFTWARE_ENERGY_SCAN_ENABLE 0
 #endif
 
+/**
+ * @def OPENTHREAD_CONFIG_MAC_SOFTWARE_RX_ON_WHEN_IDLE_ENABLE
+ *
+ * Define to 1 to enable software rx off when idle switching.
+ *
+ */
+#ifndef OPENTHREAD_CONFIG_MAC_SOFTWARE_RX_ON_WHEN_IDLE_ENABLE
+#define OPENTHREAD_CONFIG_MAC_SOFTWARE_RX_ON_WHEN_IDLE_ENABLE 0
+#endif
+
 /**
  * @def OPENTHREAD_CONFIG_MAC_CSL_TRANSMITTER_ENABLE
  *

src/core/mac/mac.cpp

@@ -414,7 +414,7 @@ void Mac::SetRxOnWhenIdle(bool aRxOnWhenIdle)
 #endif
     }
 
-    mLinks.SetRxOnWhenBackoff(mRxOnWhenIdle || mPromiscuous);
+    mLinks.SetRxOnWhenIdle(mRxOnWhenIdle || mPromiscuous);
     UpdateIdleMode();
 
 exit:
@@ -2101,7 +2101,7 @@ void Mac::SetPromiscuous(bool aPromiscuous)
     mShouldDelaySleep = false;
 #endif
 
-    mLinks.SetRxOnWhenBackoff(mRxOnWhenIdle || mPromiscuous);
+    mLinks.SetRxOnWhenIdle(mRxOnWhenIdle || mPromiscuous);
     UpdateIdleMode();
 }
 

src/core/mac/mac_links.hpp

@@ -402,17 +402,17 @@ class Links : public InstanceLocator
     }
 
     /**
-     * Indicates whether radio should stay in Receive or Sleep during CSMA backoff.
+     * Indicates whether radio should stay in Receive or Sleep during idle periods.
      *
-     * @param[in]  aRxOnWhenBackoff  TRUE to keep radio in Receive, FALSE to put to Sleep during CSMA backoff.
+     * @param[in]  aRxOnWhenIdle  TRUE to keep radio in Receive, FALSE to put to Sleep during idle periods.
      *
      */
-    void SetRxOnWhenBackoff(bool aRxOnWhenBackoff)
+    void SetRxOnWhenIdle(bool aRxOnWhenIdle)
     {
 #if OPENTHREAD_CONFIG_RADIO_LINK_IEEE_802_15_4_ENABLE
-        mSubMac.SetRxOnWhenBackoff(aRxOnWhenBackoff);
+        mSubMac.SetRxOnWhenIdle(aRxOnWhenIdle);
 #endif
-        OT_UNUSED_VARIABLE(aRxOnWhenBackoff);
+        OT_UNUSED_VARIABLE(aRxOnWhenIdle);
     }
 
     /**

src/core/mac/sub_mac.cpp

@@ -76,7 +76,7 @@ void SubMac::Init(void)
     mTransmitRetries = 0;
     mShortAddress    = kShortAddrInvalid;
     mExtAddress.Clear();
-    mRxOnWhenBackoff   = true;
+    mRxOnWhenIdle      = true;
     mEnergyScanMaxRssi = Radio::kInvalidRssi;
     mEnergyScanEndTime = Time{0};
 #if OPENTHREAD_CONFIG_MAC_ADD_DELAY_ON_NO_ACK_ERROR_BEFORE_RETRY
@@ -141,10 +141,14 @@ otRadioCaps SubMac::GetCaps(void) const
     caps |= OT_RADIO_CAPS_RECEIVE_TIMING;
 #endif
 
+#if OPENTHREAD_CONFIG_MAC_SOFTWARE_RX_ON_WHEN_IDLE_ENABLE
+    caps |= OT_RADIO_CAPS_RX_ON_WHEN_IDLE;
+#endif
+
 #else
     caps = OT_RADIO_CAPS_ACK_TIMEOUT | OT_RADIO_CAPS_CSMA_BACKOFF | OT_RADIO_CAPS_TRANSMIT_RETRIES |
            OT_RADIO_CAPS_ENERGY_SCAN | OT_RADIO_CAPS_TRANSMIT_SEC | OT_RADIO_CAPS_TRANSMIT_TIMING |
-           OT_RADIO_CAPS_RECEIVE_TIMING;
+           OT_RADIO_CAPS_RECEIVE_TIMING | OT_RADIO_CAPS_RX_ON_WHEN_IDLE;
 #endif
 
     return caps;
@@ -176,6 +180,18 @@ void SubMac::SetExtAddress(const ExtAddress &aExtAddress)
     LogDebg("RadioExtAddress: %s", mExtAddress.ToString().AsCString());
 }
 
+void SubMac::SetRxOnWhenIdle(bool aRxOnWhenIdle)
+{
+    mRxOnWhenIdle = aRxOnWhenIdle;
+
+    if (RadioSupportsRxOnWhenIdle())
+    {
+        Get<Radio>().SetRxOnWhenIdle(mRxOnWhenIdle);
+    }
+
+    LogDebg("RxOnWhenIdle: %d", mRxOnWhenIdle);
+}
+
 Error SubMac::Enable(void)
 {
     Error error = kErrorNone;
@@ -211,17 +227,22 @@ Error SubMac::Disable(void)
 
 Error SubMac::Sleep(void)
 {
-    Error error = Get<Radio>().Sleep();
+    Error error = kErrorNone;
+
+    VerifyOrExit(ShouldHandleTransitionToSleep());
 
+    error = Get<Radio>().Sleep();
+
+exit:
     if (error != kErrorNone)
     {
         LogWarn("RadioSleep() failed, error: %s", ErrorToString(error));
-        ExitNow();
+    }
+    else
+    {
+        SetState(kStateSleep);
     }
 
-    SetState(kStateSleep);
-
-exit:
     return error;
 }
 
@@ -507,11 +528,11 @@ void SubMac::StartTimerForBackoff(uint8_t aBackoffExponent)
     backoff = Random::NonCrypto::GetUint32InRange(0, static_cast<uint32_t>(1UL << aBackoffExponent));
     backoff *= (kUnitBackoffPeriod * Radio::kSymbolTime);
 
-    if (mRxOnWhenBackoff)
+    if (mRxOnWhenIdle)
     {
         IgnoreError(Get<Radio>().Receive(mTransmitFrame.GetChannel()));
     }
-    else
+    else if (ShouldHandleTransitionToSleep())
     {
         IgnoreError(Get<Radio>().Sleep());
     }
@@ -970,6 +991,8 @@ bool SubMac::ShouldHandleTransmitTargetTime(void) const
     return swTxDelay;
 }
 
+bool SubMac::ShouldHandleTransitionToSleep(void) const { return !(!mRxOnWhenIdle && RadioSupportsRxOnWhenIdle()); }
+
 void SubMac::SetState(State aState)
 {
     if (mState != aState)

src/core/mac/sub_mac.hpp

@@ -278,12 +278,12 @@ class SubMac : public InstanceLocator, private NonCopyable
     }
 
     /**
-     * Indicates whether radio should stay in Receive or Sleep during CSMA backoff.
+     * Indicates whether radio should stay in Receive or Sleep during idle periods.
      *
-     * @param[in]  aRxOnWhenBackoff  TRUE to keep radio in Receive, FALSE to put to Sleep during CSMA backoff.
+     * @param[in]  aRxOnWhenIdle  TRUE to keep radio in Receive, FALSE to put to Sleep during idle periods.
      *
      */
-    void SetRxOnWhenBackoff(bool aRxOnWhenBackoff) { mRxOnWhenBackoff = aRxOnWhenBackoff; }
+    void SetRxOnWhenIdle(bool aRxOnWhenIdle);
 
     /**
      * Enables the radio.
@@ -604,13 +604,15 @@ class SubMac : public InstanceLocator, private NonCopyable
     bool RadioSupportsEnergyScan(void) const { return ((mRadioCaps & OT_RADIO_CAPS_ENERGY_SCAN) != 0); }
     bool RadioSupportsTransmitTiming(void) const { return ((mRadioCaps & OT_RADIO_CAPS_TRANSMIT_TIMING) != 0); }
     bool RadioSupportsReceiveTiming(void) const { return ((mRadioCaps & OT_RADIO_CAPS_RECEIVE_TIMING) != 0); }
+    bool RadioSupportsRxOnWhenIdle(void) const { return ((mRadioCaps & OT_RADIO_CAPS_RX_ON_WHEN_IDLE) != 0); }
 
     bool ShouldHandleTransmitSecurity(void) const;
     bool ShouldHandleCsmaBackOff(void) const;
     bool ShouldHandleAckTimeout(void) const;
     bool ShouldHandleRetries(void) const;
     bool ShouldHandleEnergyScan(void) const;
     bool ShouldHandleTransmitTargetTime(void) const;
+    bool ShouldHandleTransitionToSleep(void) const;
 
     void ProcessTransmitSecurity(void);
     void SignalFrameCounterUsed(uint32_t aFrameCounter, uint8_t aKeyId);
@@ -642,7 +644,7 @@ class SubMac : public InstanceLocator, private NonCopyable
     uint8_t      mTransmitRetries;
     ShortAddress mShortAddress;
     ExtAddress   mExtAddress;
-    bool         mRxOnWhenBackoff : 1;
+    bool         mRxOnWhenIdle : 1;
 #if OPENTHREAD_CONFIG_MAC_FILTER_ENABLE
     bool mRadioFilterEnabled : 1;
 #endif

src/core/radio/radio.cpp

@@ -61,6 +61,7 @@ void Radio::Init(void)
     SetMacFrameCounter(0);
 
     SetPromiscuous(false);
+    SetRxOnWhenIdle(true);
 #endif // OPENTHREAD_CONFIG_RADIO_LINK_IEEE_802_15_4_ENABLE
 }
 #endif // OPENTHREAD_RADIO

src/core/radio/radio.hpp

@@ -434,6 +434,14 @@ class Radio : public InstanceLocator, private NonCopyable
      */
     void SetPromiscuous(bool aEnable);
 
+    /**
+     * Indicates whether radio should stay in Receive or Sleep during idle periods.
+     *
+     * @param[in]  aEnable   TRUE to keep radio in Receive, FALSE to put to Sleep during idle periods.
+     *
+     */
+    void SetRxOnWhenIdle(bool aEnable);
+
     /**
      * Returns the current state of the radio.
      *
@@ -803,6 +811,8 @@ inline bool Radio::GetPromiscuous(void) { return otPlatRadioGetPromiscuous(GetIn
 
 inline void Radio::SetPromiscuous(bool aEnable) { otPlatRadioSetPromiscuous(GetInstancePtr(), aEnable); }
 
+inline void Radio::SetRxOnWhenIdle(bool aEnable) { otPlatRadioSetRxOnWhenIdle(GetInstancePtr(), aEnable); }
+
 inline otRadioState Radio::GetState(void) { return otPlatRadioGetState(GetInstancePtr()); }
 
 inline Error Radio::Enable(void)
@@ -944,6 +954,8 @@ inline bool Radio::GetPromiscuous(void) { return false; }
 
 inline void Radio::SetPromiscuous(bool) {}
 
+inline void Radio::SetRxOnWhenIdle(bool) {}
+
 inline otRadioState Radio::GetState(void) { return OT_RADIO_STATE_DISABLED; }
 
 inline Error Radio::Enable(void) { return kErrorNone; }

src/core/radio/radio_platform.cpp

@@ -314,3 +314,9 @@ OT_TOOL_WEAK otError otPlatRadioReceiveAt(otInstance *aInstance, uint8_t aChanne
 
     return kErrorNotImplemented;
 }
+
+OT_TOOL_WEAK void otPlatRadioSetRxOnWhenIdle(otInstance *aInstance, bool aEnable)
+{
+    OT_UNUSED_VARIABLE(aInstance);
+    OT_UNUSED_VARIABLE(aEnable);
+}

src/lib/spinel/radio_spinel.cpp

@@ -866,6 +866,11 @@ otError RadioSpinel::SetPromiscuous(bool aEnable)
     return error;
 }
 
+otError RadioSpinel::SetRxOnWhenIdle(bool aEnable)
+{
+    return Set(SPINEL_PROP_MAC_RX_ON_WHEN_IDLE_MODE, SPINEL_DATATYPE_BOOL_S, aEnable);
+}
+
 otError RadioSpinel::SetShortAddress(uint16_t aAddress)
 {
     otError error = OT_ERROR_NONE;

src/lib/spinel/radio_spinel.hpp

@@ -103,6 +103,18 @@ class RadioSpinel
      */
     otError SetPromiscuous(bool aEnable);
 
+    /**
+     * Sets the status of RxOnWhenIdle mode.
+     *
+     * @param[in]   aEnable     Whether to enable or disable RxOnWhenIdle mode.
+     *
+     * @retval  OT_ERROR_NONE               Succeeded.
+     * @retval  OT_ERROR_BUSY               Failed due to another operation is on going.
+     * @retval  OT_ERROR_RESPONSE_TIMEOUT   Failed due to no response received from the transceiver.
+     *
+     */
+    otError SetRxOnWhenIdle(bool aEnable);
+
     /**
      * Sets the Short Address for address filtering.
      *

src/lib/spinel/spinel.c

@@ -1263,6 +1263,7 @@ const char *spinel_prop_key_to_cstr(spinel_prop_key_t prop_key)
         {SPINEL_PROP_MAC_PROMISCUOUS_MODE, "MAC_PROMISCUOUS_MODE"},
         {SPINEL_PROP_MAC_ENERGY_SCAN_RESULT, "MAC_ENERGY_SCAN_RESULT"},
         {SPINEL_PROP_MAC_DATA_POLL_PERIOD, "MAC_DATA_POLL_PERIOD"},
+        {SPINEL_PROP_MAC_RX_ON_WHEN_IDLE_MODE, "MAC_RX_ON_WHEN_IDLE_MODE"},
         {SPINEL_PROP_MAC_ALLOWLIST, "MAC_ALLOWLIST"},
         {SPINEL_PROP_MAC_ALLOWLIST_ENABLED, "MAC_ALLOWLIST_ENABLED"},
         {SPINEL_PROP_MAC_EXTENDED_ADDR, "MAC_EXTENDED_ADDR"},

src/lib/spinel/spinel.h

@@ -420,7 +420,7 @@
  * Please see section "Spinel definition compatibility guideline" for more details.
  *
  */
-#define SPINEL_RCP_API_VERSION 9
+#define SPINEL_RCP_API_VERSION 10
 
 /**
  * @def SPINEL_MIN_HOST_SUPPORTED_RCP_API_VERSION
@@ -2124,6 +2124,17 @@ enum
      */
     SPINEL_PROP_MAC_DATA_POLL_PERIOD = SPINEL_PROP_MAC__BEGIN + 10,
 
+    /// MAC RxOnWhenIdle mode
+    /** Format: `b`
+     *
+     * Set to true to enable RxOnWhenIdle or false to disable it.
+     * When True, the radio is expected to stay in receive state during
+     * idle periods. When False, the radio is expected to switch to sleep
+     * state during idle periods.
+     *
+     */
+    SPINEL_PROP_MAC_RX_ON_WHEN_IDLE_MODE = SPINEL_PROP_MAC__BEGIN + 11,
+
     SPINEL_PROP_MAC__END = 0x40,
 
     SPINEL_PROP_MAC_EXT__BEGIN = 0x1300,

src/ncp/ncp_base.cpp

@@ -1452,6 +1452,18 @@ template <> otError NcpBase::HandlePropertySet<SPINEL_PROP_MAC_PROMISCUOUS_MODE>
     return error;
 }
 
+template <> otError NcpBase::HandlePropertySet<SPINEL_PROP_MAC_RX_ON_WHEN_IDLE_MODE>(void)
+{
+    bool    enabled;
+    otError error = OT_ERROR_NONE;
+
+    SuccessOrExit(error = mDecoder.ReadBool(enabled));
+    otPlatRadioSetRxOnWhenIdle(mInstance, enabled);
+
+exit:
+    return error;
+}
+
 template <> otError NcpBase::HandlePropertyGet<SPINEL_PROP_MAC_15_4_PANID>(void)
 {
     return mEncoder.WriteUint16(otLinkGetPanId(mInstance));

src/ncp/ncp_base_dispatcher.cpp

@@ -430,6 +430,7 @@ NcpBase::PropertyHandler NcpBase::FindSetPropertyHandler(spinel_prop_key_t aKey)
         OT_NCP_SET_HANDLER_ENTRY(SPINEL_PROP_MAC_PROMISCUOUS_MODE),
 #if OPENTHREAD_MTD || OPENTHREAD_FTD
         OT_NCP_SET_HANDLER_ENTRY(SPINEL_PROP_MAC_DATA_POLL_PERIOD),
+        OT_NCP_SET_HANDLER_ENTRY(SPINEL_PROP_MAC_RX_ON_WHEN_IDLE_MODE),
         OT_NCP_SET_HANDLER_ENTRY(SPINEL_PROP_NET_IF_UP),
         OT_NCP_SET_HANDLER_ENTRY(SPINEL_PROP_NET_STACK_UP),
         OT_NCP_SET_HANDLER_ENTRY(SPINEL_PROP_NET_ROLE),