# TREL - Thread Stack

# TREL - Thread Stack

This module defines Thread Radio Encapsulation Link (TREL) APIs for Thread Over Infrastructure.

## Summary

The functions in this module require `OPENTHREAD_CONFIG_RADIO_LINK_TREL_ENABLE` to be enabled.

| ### Typedefs ||
|---|---|
| `https://openthread.io/reference/group/api-trel#group__api-trel_1ga97fe12cedfc71b04e076d729a42ae9b3` | typedef `https://openthread.io/reference/struct/ot-plat-trel-counters` Represents a group of TREL related counters. |
| `https://openthread.io/reference/group/api-trel#group__api-trel_1ga20933d230924ac8681e6995b8264b8c0` | typedef `struct https://openthread.io/reference/struct/ot-trel-peer` Represents a TREL peer. |
| `https://openthread.io/reference/group/api-trel#group__api-trel_1ga10531a1d3231cbf07515605ae70c121c` | typedef `const void *` Represents an iterator for iterating over TREL peer table entries. |

| ### Functions ||
|---|---|
| `https://openthread.io/reference/group/api-trel#group__api-trel_1ga6427b5c7b23e16647e5a851e33992f01(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance)` | `const https://openthread.io/reference/group/api-trel#group__api-trel_1ga97fe12cedfc71b04e076d729a42ae9b3 *` Gets the TREL counters. |
| `https://openthread.io/reference/group/api-trel#group__api-trel_1ga5ccfef74cd4ec1930caad23c499e171c(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, https://openthread.io/reference/group/api-trel#group__api-trel_1ga10531a1d3231cbf07515605ae70c121c *aIterator)` | `const https://openthread.io/reference/struct/ot-trel-peer *` Iterates over the peer table entries and get the next entry from the table. |
| `https://openthread.io/reference/group/api-trel#group__api-trel_1ga9163281b99310ce7b5815c5a6c06cab4(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance)` | `uint16_t` Returns the number of TREL peers. |
| `https://openthread.io/reference/group/api-trel#group__api-trel_1ga37fab774d6ed41a1c4606dc3ca160839(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance)` | `uint16_t` Gets the UDP port of the TREL interface. |
| `https://openthread.io/reference/group/api-trel#group__api-trel_1ga89f9dab5b50618e1af42b21061531d05(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, https://openthread.io/reference/group/api-trel#group__api-trel_1ga10531a1d3231cbf07515605ae70c121c *aIterator)` | `void` Initializes a peer table iterator. |
| `https://openthread.io/reference/group/api-trel#group__api-trel_1ga1fde90a5e911984fcc680eb43e9f2ecd(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance)` | `bool` Indicates whether the TREL operation is enabled. |
| `https://openthread.io/reference/group/api-trel#group__api-trel_1ga88d844c58924f3355dfd2507d86d843f(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance)` | `bool` Indicates whether or not the filter mode is enabled. |
| `https://openthread.io/reference/group/api-trel#group__api-trel_1gabf5acb581ed772a9efcabd2a1c3f843e(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance)` | `void` Resets the TREL counters. |
| `https://openthread.io/reference/group/api-trel#group__api-trel_1ga92b941e985fe2e14803d8e5a8acc7b3b(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, bool aEnable)` | `void` Sets the user's preference to enable or disable the TREL operation. |
| `https://openthread.io/reference/group/api-trel#group__api-trel_1ga74ea7c348942eda1c7ba7a68cae0cb83(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, bool aEnable)` | `void` Sets the filter mode (enables/disables filtering). |

| ### Structs ||
|---|---|
| [otTrelPeer](https://openthread.io/reference/struct/ot-trel-peer) | Represents a TREL peer. |

## Typedefs

### otTrelCounters

```
otPlatTrelCounters otTrelCounters
```
Represents a group of TREL related counters.

### otTrelPeer

```
struct otTrelPeer otTrelPeer
```
Represents a TREL peer.

### otTrelPeerIterator

```
const void * otTrelPeerIterator
```
Represents an iterator for iterating over TREL peer table entries.

## Functions

### otTrelGetCounters

```
const otTrelCounters * otTrelGetCounters(
  otInstance *aInstance
)
```
Gets the TREL counters.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | A pointer to an OpenThread instance. | |
| **Returns** | A pointer to the TREL counters. |

### otTrelGetNextPeer

```
const otTrelPeer * otTrelGetNextPeer(
  otInstance *aInstance,
  otTrelPeerIterator *aIterator
)
```
Iterates over the peer table entries and get the next entry from the table.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | The OpenThread instance. | | `[in] aIterator` | The iterator. MUST be initialized. | |
| **Returns** | A pointer to the next `https://openthread.io/reference/struct/ot-trel-peer` entry or `NULL` if no more entries in the table. |

### otTrelGetNumberOfPeers

```
uint16_t otTrelGetNumberOfPeers(
  otInstance *aInstance
)
```
Returns the number of TREL peers.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | A pointer to an OpenThread instance. | |
| **Returns** | The number of TREL peers. |

### otTrelGetUdpPort

```
uint16_t otTrelGetUdpPort(
  otInstance *aInstance
)
```
Gets the UDP port of the TREL interface.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | A pointer to an OpenThread instance. | |
| **Returns** | UDP port of the TREL interface. |

### otTrelInitPeerIterator

```
void otTrelInitPeerIterator(
  otInstance *aInstance,
  otTrelPeerIterator *aIterator
)
```
Initializes a peer table iterator.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | The OpenThread instance. | | `[in] aIterator` | The iterator to initialize. | |

### otTrelIsEnabled

```
bool otTrelIsEnabled(
  otInstance *aInstance
)
```
Indicates whether the TREL operation is enabled.

The TREL operation is enabled if and only if it is enabled by both the user (see `https://openthread.io/reference/group/api-trel#group__api-trel_1ga92b941e985fe2e14803d8e5a8acc7b3b`) and the OpenThread stack.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | The OpenThread instance. | |
| Return Values | |---|---| | `TRUE` | if the TREL operation is enabled. | | `FALSE` | if the TREL operation is disabled. | |

### otTrelIsFilterEnabled

```
bool otTrelIsFilterEnabled(
  otInstance *aInstance
)
```
Indicates whether or not the filter mode is enabled.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | The OpenThread instance. | |
| Return Values | |---|---| | `TRUE` | if the TREL filter mode is enabled. | | `FALSE` | if the TREL filter mode is disabled. | |

### otTrelResetCounters

```
void otTrelResetCounters(
  otInstance *aInstance
)
```
Resets the TREL counters.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | A pointer to an OpenThread instance. | |

### otTrelSetEnabled

```
void otTrelSetEnabled(
  otInstance *aInstance,
  bool aEnable
)
```
Sets the user's preference to enable or disable the TREL operation.

The TREL interface's operational state is determined by two factors: the user's preference (set by this function) and the OpenThread stack's internal state. The TREL interface is enabled only when both the user and the OpenThread stack have it enabled. Otherwise, it is disabled.

Upon OpenThread initialization, the user's preference is set to enabled by default. This allows the stack to control the TREL interface state automatically (e.g., enabling it when radio links are enabled and disabling it when radio links are disabled).

If the user explicitly disables the TREL operation by calling this function with `aEnable` as `false`, it will remain disabled until the user explicitly re-enables it by calling this function with `aEnable` as `true`. This ensures the user's 'disable' request persists across other OpenThread stack state changes (which may trigger disabling/enabling of all radio links, including the TREL link).

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | A pointer to an OpenThread instance. | | `[in] aEnable` | A boolean to enable/disable the TREL operation. | |

### otTrelSetFilterEnabled

```
void otTrelSetFilterEnabled(
  otInstance *aInstance,
  bool aEnable
)
```
Sets the filter mode (enables/disables filtering).

When filter mode is enabled, any rx and tx traffic through TREL interface is silently dropped. This is mainly intended for use during testing.

Unlike `otTrel{Enable/Disable}()` which fully starts/stops the TREL operation, when filter mode is enabled the TREL interface continues to be enabled.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | The OpenThread instance. | | `[in] aFiltered` | TRUE to enable filter mode, FALSE to disable filter mode. | |

## Resources

OpenThread API Reference topics originate from the source code, available
on [GitHub](https://github.com/openthread/openthread/tree/main/include/openthread).
For more information, or to contribute to our documentation, refer to
[Resources](https://openthread.io/resources).