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.