Thread Direct Listener

This module includes functions and definitions for Thread Direct (TD) Wake Listener.

Summary

The APIs in this module require Thread Direct Wake Listener functionality to be enabled via OPENTHREAD_CONFIG_TD_WAKE_LISTENER_ENABLE.

Typedefs

otThreadDirectListenerConfig typedef
Represents the configuration parameters for starting the Thread Direct Wake Listener.
otThreadDirectListenerWakeCallback)(void *aContext) typedef
void(*
Pointer to a function that is called when a valid Thread Direct Wake frame is received by the Thread Direct Wake Listener.
otThreadDirectListenerWakeInfo typedef
Represents information about a received Thread Direct Wake frame.

Functions

otThreadDirectListenerEstablishLink(otInstance *aInstance, const otThreadDirectLinkConfig *aLinkConfig)
Accepts the most recently received Wake frame on the Thread Direct Wake Listener and initiates establishment of a Thread Direct Link (otThreadDirectLink).
otThreadDirectListenerGetWakeInfo(otInstance *aInstance, otThreadDirectListenerWakeInfo *aWakeInfo)
Gets the information for the most recently received Wake frame on the Thread Direct Wake Listener.
otThreadDirectListenerIsRunning(otInstance *aInstance)
bool
Indicates whether the Thread Direct Wake Listener is currently running.
otThreadDirectListenerStart(otInstance *aInstance, const otThreadDirectListenerConfig *aConfig)
Starts the Thread Direct Wake Listener with the given configuration.
otThreadDirectListenerStop(otInstance *aInstance)
void
Stops the Thread Direct Wake Listener if it is currently running.

Macros

OT_THREAD_DIRECT_LISTENER_CHANNEL 20
Default radio channel for Thread Direct Wake Listener.
OT_THREAD_DIRECT_LISTENER_DURATION 8000
Default listen duration in microseconds (8 milliseconds).
OT_THREAD_DIRECT_LISTENER_INTERVAL 1000000
Default listen interval in microseconds (1 second).

Structs

otThreadDirectListenerConfig

Represents the configuration parameters for starting the Thread Direct Wake Listener.

otThreadDirectListenerWakeInfo

Represents information about a received Thread Direct Wake frame.

Typedefs

otThreadDirectListenerConfig

struct otThreadDirectListenerConfig otThreadDirectListenerConfig

Represents the configuration parameters for starting the Thread Direct Wake Listener.

To ensure forward compatibility as new fields may be added in future revisions, the caller MUST zero-initialize (memset to zero) this structure before setting its fields.

For mChannel, mInterval, and mDuration, setting a field to 0 selects its specification-mandated default (OT_THREAD_DIRECT_LISTENER_CHANNEL, OT_THREAD_DIRECT_LISTENER_INTERVAL, and OT_THREAD_DIRECT_LISTENER_DURATION, respectively). Specifying a value other than 0 or the specification-mandated default makes the operation non-compliant with the specification and is intended for testing purposes only. Callers SHOULD either leave these fields set to 0 or set them to the corresponding OT_THREAD_DIRECT_LISTENER_* constant.

otThreadDirectListenerWakeCallback

void(* otThreadDirectListenerWakeCallback)(void *aContext)

Pointer to a function that is called when a valid Thread Direct Wake frame is received by the Thread Direct Wake Listener.

Inside this callback (or afterward while the listener remains running), the caller can call otThreadDirectListenerGetWakeInfo() to retrieve details of the received Wake frame, and otThreadDirectListenerEstablishLink() to accept the wake and initiate a Thread Direct Link. The caller MAY also call otThreadDirectListenerStop() from within this callback to stop the listener.

Details
Parameters
[in] aContext
The user context pointer (mWakeCallbackContext in otThreadDirectListenerConfig).

otThreadDirectListenerWakeInfo

struct otThreadDirectListenerWakeInfo otThreadDirectListenerWakeInfo

Represents information about a received Thread Direct Wake frame.

Functions

otThreadDirectLink * otThreadDirectListenerEstablishLink(
  otInstance *aInstance,
  const otThreadDirectLinkConfig *aLinkConfig
)

Accepts the most recently received Wake frame on the Thread Direct Wake Listener and initiates establishment of a Thread Direct Link (otThreadDirectLink).

This function can be called from within otThreadDirectListenerWakeCallback or afterward while the listener remains running, and acts on the latest Wake frame reported via otThreadDirectListenerWakeCallback (and inspectable via otThreadDirectListenerGetWakeInfo()). This function returns NULL if the wake cannot be accepted (for example, if the listener is not running, no Wake frame has been received yet, the latest Wake frame was already accepted, the wake type is not OT_THREAD_DIRECT_WAKE_TYPE_TD_LINK, or a link could not be allocated/started).

The caller MUST zero-initialize (memset to zero) aLinkConfig before populating its fields. OpenThread copies aLinkConfig, so it does not need to persist after this call returns.

Details
Parameters
[in] aInstance
The OpenThread instance.
[in] aLinkConfig
The configuration for the new Thread Direct Link.
Returns
A pointer to the newly created otThreadDirectLink, or NULL if the wake could not be accepted.

otThreadDirectListenerGetWakeInfo

otError otThreadDirectListenerGetWakeInfo(
  otInstance *aInstance,
  otThreadDirectListenerWakeInfo *aWakeInfo
)

Gets the information for the most recently received Wake frame on the Thread Direct Wake Listener.

This function can be called from within otThreadDirectListenerWakeCallback or afterward while the listener remains running. The mKey pointer in aWakeInfo remains valid as long as that key remains registered. If the key is unregistered (via otThreadDirectUnregisterKey() or otThreadDirectUnregisterAllKeys()), the stored Wake information is invalidated and subsequent calls to this function will return OT_ERROR_NOT_FOUND until a new Wake frame is received.

Details
Parameters
[in] aInstance
The OpenThread instance.
[out] aWakeInfo
A pointer to an otThreadDirectListenerWakeInfo structure to populate.
Return Values
OT_ERROR_NONE
Successfully retrieved the Wake frame information in aWakeInfo.
OT_ERROR_INVALID_STATE
The listener is not running.
OT_ERROR_NOT_FOUND
No valid Wake frame information is available.

otThreadDirectListenerIsRunning

bool otThreadDirectListenerIsRunning(
  otInstance *aInstance
)

Indicates whether the Thread Direct Wake Listener is currently running.

Details
Parameters
[in] aInstance
The OpenThread instance.
Return Values
TRUE
The Thread Direct Wake Listener is currently running.
FALSE
The Thread Direct Wake Listener is not running.

otThreadDirectListenerStart

otError otThreadDirectListenerStart(
  otInstance *aInstance,
  const otThreadDirectListenerConfig *aConfig
)

Starts the Thread Direct Wake Listener with the given configuration.

When running, the listener schedules periodic receive windows during radio sleep intervals (when the radio is enabled and sleeping). Other MAC and radio operations (such as continuous reception when RxOnWhenIdle is enabled, active frame transmissions, scans, or CSL receive windows) take precedence over the listener's receive windows.

The caller MUST zero-initialize (memset to zero) aConfig before populating its fields to ensure forward compatibility with future revisions. OpenThread copies the contents of aConfig, so the structure does not need to persist after this function returns.

Details
Parameters
[in] aInstance
The OpenThread instance.
[in] aConfig
The listener configuration.
Return Values
OT_ERROR_NONE
Successfully started the Thread Direct Wake Listener.
OT_ERROR_INVALID_ARGS
The configuration parameters in aConfig are invalid.
OT_ERROR_BUSY
The Thread Direct Wake Listener is already running.

otThreadDirectListenerStop

void otThreadDirectListenerStop(
  otInstance *aInstance
)

Stops the Thread Direct Wake Listener if it is currently running.

This function can be called at any time, including from within otThreadDirectListenerWakeCallback. If the listener is not running, this function does nothing.

Details
Parameters
[in] aInstance
The OpenThread instance.

Macros

OT_THREAD_DIRECT_LISTENER_CHANNEL

 OT_THREAD_DIRECT_LISTENER_CHANNEL 20

Default radio channel for Thread Direct Wake Listener.

OT_THREAD_DIRECT_LISTENER_DURATION

 OT_THREAD_DIRECT_LISTENER_DURATION 8000

Default listen duration in microseconds (8 milliseconds).

OT_THREAD_DIRECT_LISTENER_INTERVAL

 OT_THREAD_DIRECT_LISTENER_INTERVAL 1000000

Default listen interval in microseconds (1 second).

Resources

OpenThread API Reference topics originate from the source code, available on GitHub. For more information, or to contribute to our documentation, refer to Resources.