Seeker

This module includes functions for the Thread Seeker role.

Summary

Note: The functions in this module require OPENTHREAD_CONFIG_SEEKER_ENABLE.

Enumerations
otSeekerVerdict{   OT_SEEKER_ACCEPT,   OT_SEEKER_ACCEPT_PREFERRED,   OT_SEEKER_IGNORE }	enum Represents a verdict returned from the otSeekerScanEvaluator callback when evaluating a Discover Scan result.

Typedefs
otSeekerScanEvaluator)(void *aContext, const otSeekerScanResult *aResult)	typedef otSeekerVerdict(* Represents the callback function type used to evaluate a scan result or report the end of a scan.
otSeekerScanResult	typedef otActiveScanResult Represents a Discover Scan result.
otSeekerVerdict	typedef enum otSeekerVerdict Represents a verdict returned from the otSeekerScanEvaluator callback when evaluating a Discover Scan result.

Functions
otSeekerGetUdpPort(otInstance *aInstance)	uint16_t Gets the Seeker UDP port (unsecure port).
otSeekerIsRunning(otInstance *aInstance)	bool Indicates whether or not the Seeker is running.
otSeekerSetUdpPort(otInstance *aInstance, uint16_t aUdpPort)	otError Sets the Seeker UDP port (unsecure port).
otSeekerSetUpNextConnection(otInstance *aInstance, otSockAddr *aSockAddr)	otError Selects the next best candidate and prepares the connection.
otSeekerStart(otInstance *aInstance, otSeekerScanEvaluator aScanEvaluator, void *aContext)	otError Starts the Seeker operation.
otSeekerStop(otInstance *aInstance)	void Stops the Seeker operation.

Enumerations

otSeekerVerdict

 otSeekerVerdict

Represents a verdict returned from the otSeekerScanEvaluator callback when evaluating a Discover Scan result.

Properties
OT_SEEKER_ACCEPT	The scan result is acceptable.
OT_SEEKER_ACCEPT_PREFERRED	The scan result is acceptable and preferred.
OT_SEEKER_IGNORE	The scan result should be ignored.

Typedefs

otSeekerScanEvaluator

otSeekerVerdict(* otSeekerScanEvaluator)(void *aContext, const otSeekerScanResult *aResult)

Represents the callback function type used to evaluate a scan result or report the end of a scan.

Details
Parameters	[in] aContext A pointer to the callback context. [in] aResult A pointer to the scan result to evaluate, or NULL to indicate scan completion.
Returns	The verdict for the scan result (Accept, AcceptPreferred, or Ignore). If aResult is NULL (scan complete), the return value is ignored.

otSeekerScanResult

otActiveScanResult otSeekerScanResult

Represents a Discover Scan result.

otSeekerVerdict

enum otSeekerVerdict otSeekerVerdict

Represents a verdict returned from the otSeekerScanEvaluator callback when evaluating a Discover Scan result.

Functions

otSeekerGetUdpPort

uint16_t otSeekerGetUdpPort(
  otInstance *aInstance
)

Gets the Seeker UDP port (unsecure port).

Details
Parameters	[in] aInstance The OpenThread instance.
Returns	The Seeker UDP port.

otSeekerIsRunning

bool otSeekerIsRunning(
  otInstance *aInstance
)

Indicates whether or not the Seeker is running.

Details
Parameters	[in] aInstance The OpenThread instance.
Return Values	TRUE The Seeker is active and running. FALSE The Seeker is stopped.

otSeekerSetUdpPort

otError otSeekerSetUdpPort(
  otInstance *aInstance,
  uint16_t aUdpPort
)

Sets the Seeker UDP port (unsecure port).

This UDP port can only be changed when the Seeker is not running.

Details
Parameters	[in] aInstance The OpenThread instance. [in] aUdpPort The Seeker UDP port.
Return Values	OT_ERROR_NONE Successfully set the Joiner/Seeker UDP port. OT_ERROR_INVALID_STATE The Seeker is already running.

otSeekerSetUpNextConnection

otError otSeekerSetUpNextConnection(
  otInstance *aInstance,
  otSockAddr *aSockAddr
)

Selects the next best candidate and prepares the connection.

This function MUST be called after the discovery scan has completed (indicated by the otSeekerScanEvaluator callback receiving NULL). Calling it before scan completion will result in OT_ERROR_INVALID_STATE.

This function iterates through the discovered Joiner Router candidates in order of priority. For the selected candidate, it configures the radio channel and PAN ID, and populates aSockAddr with the candidate's address. It also registers the Seeker UDP port otSeekerGetUdpPort() as an unsecure port to allow a UDP connection to the candidate. The next layer code can start sending UDP messages to the given otSockAddr ensuring to use the unsecure Seeker UDP port as the source port. These messages are then forwarded by the Joiner Router onward to a Commissioner/Enroller connected via a Border Agent/Admitter.

If the list is exhausted, this function returns OT_ERROR_NOT_FOUND and automatically calls otSeekerStop(), which removes the unsecure port and clears internal state.

Details
Parameters	[out] aSockAddr A pointer to a socket address to output the candidate's address.
Return Values	OT_ERROR_NONE Successfully set up the connection to the next candidate. OT_ERROR_NOT_FOUND No more candidates are available (list exhausted). OT_ERROR_INVALID_STATE The Seeker is not in a valid state (e.g. scan not yet completed).

otSeekerStart

otError otSeekerStart(
  otInstance *aInstance,
  otSeekerScanEvaluator aScanEvaluator,
  void *aContext
)

Starts the Seeker operation.

The Seeker generates and sets a random MAC address for anonymity, then initiates an MLE Discover Scan to find Joiner Router candidates.

Found candidates are reported to the aScanEvaluator callback. Based on the returned otSeekerVerdict, the Seeker maintains a prioritized list of candidates for future connection attempts.

Details
Parameters	[in] aInstance The OpenThread instance. [in] aScanEvaluator The callback function to evaluate scan results. [in] aContext An arbitrary context pointer to use with aScanEvaluator.
Return Values	OT_ERROR_NONE Successfully started the Seeker. OT_ERROR_BUSY The Seeker is already active (scanning or connecting). OT_ERROR_INVALID_STATE The IPv6 interface is not enabled, or MLE is enabled.

otSeekerStop

void otSeekerStop(
  otInstance *aInstance
)

Stops the Seeker operation.

This function stops any ongoing discovery or connection process, unregisters the unsecure Joiner/Seeker UDP port, and clears internal state. If the Seeker is already stopped, this method has no effect.

If the join process succeeds after a call to otSeekerSetUpNextConnection(), the caller MUST call this method to stop the Seeker and, importantly, unregister the Seeker UDP port as an unsecure port.

Note: If otSeekerSetUpNextConnection() returns OT_ERROR_NOT_FOUND (indicating the candidate list is exhausted), the Seeker stops automatically.

Details
Parameters	[in] aInstance The OpenThread instance.

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.