TREL - Platform#

This module includes the platform abstraction for Thread Radio Encapsulation Link (TREL) using DNS-SD and UDP/IPv6.

Modules#

otPlatTrelPeerInfo

otPlatTrelCounters

Typedefs#

typedef struct otPlatTrelPeerInfo

Represents a TREL peer info discovered using DNS-SD browse on the service name "_trel._udp".

typedef struct otPlatTrelCounters

Represents a group of TREL related counters in the platform layer.

Functions#

void
otPlatTrelEnable(otInstance *aInstance, uint16_t *aUdpPort)

Initializes and enables TREL platform layer.

void
otPlatTrelDisable(otInstance *aInstance)

Disables TREL platform layer.

void
otPlatTrelHandleDiscoveredPeerInfo(otInstance *aInstance, const otPlatTrelPeerInfo *aInfo)

This is a callback function from platform layer to report a discovered TREL peer info.

void
otPlatTrelRegisterService(otInstance *aInstance, uint16_t aPort, const uint8_t *aTxtData, uint8_t aTxtLength)

Registers a new service to be advertised using DNS-SD [RFC6763].

void
otPlatTrelSend(otInstance *aInstance, const uint8_t *aUdpPayload, uint16_t aUdpPayloadLen, const otSockAddr *aDestSockAddr)

Requests a TREL UDP packet to be sent to a given destination.

void
otPlatTrelHandleReceived(otInstance *aInstance, uint8_t *aBuffer, uint16_t aLength)

Is a callback from platform to notify of a received TREL UDP packet.

otPlatTrelGetCounters(otInstance *aInstance)

Gets the pointer to the TREL counters in the platform layer.

void
otPlatTrelResetCounters(otInstance *aInstance)

Resets the TREL counters in the platform layer.

Typedef Documentation#

otPlatTrelPeerInfo#

typedef struct otPlatTrelPeerInfo otPlatTrelPeerInfo

Represents a TREL peer info discovered using DNS-SD browse on the service name "_trel._udp".


Definition at line 125 of file include/openthread/platform/trel.h

otPlatTrelCounters#

typedef struct otPlatTrelCounters otPlatTrelCounters

Represents a group of TREL related counters in the platform layer.


Definition at line 197 of file include/openthread/platform/trel.h

Function Documentation#

otPlatTrelEnable#

void otPlatTrelEnable (otInstance * aInstance, uint16_t * aUdpPort)

Initializes and enables TREL platform layer.

Parameters
[in]aInstance

The OpenThread instance.

[out]aUdpPort

A pointer to return the selected port number by platform layer.

Upon this call, the platform layer MUST perform the following:

1) TREL platform layer MUST open a UDP socket to listen for and receive TREL messages from peers. The socket is bound to an ephemeral port number chosen by the platform layer. The port number MUST be returned in aUdpPort. The socket is also bound to network interface(s) on which TREL is to be supported. The socket and the chosen port should stay valid while TREL is enabled.

2) Platform layer MUST initiate an ongoing DNS-SD browse on the service name "_trel._udp" within the local browsing domain to discover other devices supporting TREL. The ongoing browse will produce two different types of events: "add" events and "remove" events. When the browse is started, it should produce an "add" event for every TREL peer currently present on the network. Whenever a TREL peer goes offline, a "remove" event should be produced. "remove" events are not guaranteed, however. When a TREL service instance is discovered, a new ongoing DNS-SD query for an AAAA record should be started on the hostname indicated in the SRV record of the discovered instance. If multiple host IPv6 addressees are discovered for a peer, one with highest scope among all addresses MUST be reported (if there are multiple address at same scope, one must be selected randomly).

TREL platform MUST signal back the discovered peer info using otPlatTrelHandleDiscoveredPeerInfo() callback. This callback MUST be invoked when a new peer is discovered, when there is a change in an existing entry (e.g., new TXT record or new port number or new IPv6 address), or when the peer is removed.


Definition at line 84 of file include/openthread/platform/trel.h

otPlatTrelDisable#

void otPlatTrelDisable (otInstance * aInstance)

Disables TREL platform layer.

Parameters
N/AaInstance

After this call, the platform layer MUST stop DNS-SD browse on the service name "_trel._udp", stop advertising the TREL DNS-SD service (from otPlatTrelRegisterService()) and MUST close the UDP socket used to receive TREL messages.

@pram[in] aInstance The OpenThread instance.


Definition at line 94 of file include/openthread/platform/trel.h

otPlatTrelHandleDiscoveredPeerInfo#

void otPlatTrelHandleDiscoveredPeerInfo (otInstance * aInstance, const otPlatTrelPeerInfo * aInfo)

This is a callback function from platform layer to report a discovered TREL peer info.

Parameters
[in]aInstance

The OpenThread instance.

[in]aInfo

A pointer to the TREL peer info.

Note

  • The aInfo structure and its content (e.g., the mTxtData buffer) does not need to persist after returning from this call. OpenThread code will make a copy of all the info it needs.


Definition at line 136 of file include/openthread/platform/trel.h

otPlatTrelRegisterService#

void otPlatTrelRegisterService (otInstance * aInstance, uint16_t aPort, const uint8_t * aTxtData, uint8_t aTxtLength)

Registers a new service to be advertised using DNS-SD [RFC6763].

Parameters
[in]aInstance

The OpenThread instance.

[in]aPort

The port number to include in the SRV record of the advertised service.

[in]aTxtData

A pointer to the TXT record data (encoded) to be include in the advertised service.

[in]aTxtLength

The length of aTxtData (number of bytes).

The service name is "_trel._udp". The platform should use its own hostname, which when combined with the service name and the local DNS-SD domain name will produce the full service instance name, for example "example-host._trel._udp.local.".

The domain under which the service instance name appears will be 'local' for mDNS, and will be whatever domain is used for service registration in the case of a non-mDNS local DNS-SD service.

A subsequent call to this function updates the previous service. It is used to update the TXT record data and/or the port number.

The aTxtData buffer is not persisted after the return from this function. The platform layer MUST NOT keep the pointer and instead copy the content if needed.


Definition at line 159 of file include/openthread/platform/trel.h

otPlatTrelSend#

void otPlatTrelSend (otInstance * aInstance, const uint8_t * aUdpPayload, uint16_t aUdpPayloadLen, const otSockAddr * aDestSockAddr)

Requests a TREL UDP packet to be sent to a given destination.

Parameters
[in]aInstance

The OpenThread instance structure.

[in]aUdpPayload

A pointer to UDP payload.

[in]aUdpPayloadLen

The payload length (number of bytes).

[in]aDestSockAddr

The destination socket address.


Definition at line 169 of file include/openthread/platform/trel.h

otPlatTrelHandleReceived#

void otPlatTrelHandleReceived (otInstance * aInstance, uint8_t * aBuffer, uint16_t aLength)

Is a callback from platform to notify of a received TREL UDP packet.

Parameters
[in]aInstance

The OpenThread instance structure.

[in]aBuffer

A buffer containing the received UDP payload.

[in]aLength

UDP payload length (number of bytes).

Note

  • The buffer content (up to its specified length) may get changed during processing by OpenThread core (e.g., decrypted in place), so the platform implementation should expect that after returning from this function the aBuffer content may have been altered.


Definition at line 185 of file include/openthread/platform/trel.h

otPlatTrelGetCounters#

const otPlatTrelCounters * otPlatTrelGetCounters (otInstance * aInstance)

Gets the pointer to the TREL counters in the platform layer.

Parameters
[in]aInstance

The OpenThread instance structure.


Definition at line 204 of file include/openthread/platform/trel.h

otPlatTrelResetCounters#

void otPlatTrelResetCounters (otInstance * aInstance)

Resets the TREL counters in the platform layer.

Parameters
[in]aInstance

The OpenThread instance structure.


Definition at line 211 of file include/openthread/platform/trel.h