> For the complete documentation index, see [llms.txt](https://api.intecular.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://api.intecular.com/invisoutlet-c-pro/device-management/invisoutlet/matter-mode-switching.md).

# Matter Mode Switching

\[TCP <--> InvisOutlet]

> Read the device's current Matter network mode or request a transition between Matter-over-Wi-Fi and Matter-over-Thread.

### Callback <a href="#callback" id="callback"></a>

* <mark style="color:red;">`callbackName`</mark>: 32
* Availability: Read requests are available whenever the TCP service is running. Mode changes are accepted only in Matter-over-Wi-Fi or Wi-Fi service mode. TCP is unavailable while the device is operating in Matter-over-Thread mode.

<mark style="color:red;">`callbackArgs`</mark> determines the operation:

| <mark style="color:red;">`callbackArgs`</mark> | Operation                                           |
| ---------------------------------------------- | --------------------------------------------------- |
| Omitted                                        | Read the current Matter transport and runtime mode. |
| `[0]`                                          | Select Matter-over-Wi-Fi.                           |
| `[1]`                                          | Select Matter-over-Thread.                          |

{% hint style="warning" %}
Changing transport can erase the current Matter commissioning state.
{% endhint %}

### Read Current Mode <a href="#read-current-mode" id="read-current-mode"></a>

#### Request <a href="#request" id="request"></a>

* <mark style="color:red;">`packetID`</mark>: Any six-digit packet identifier without leading zeros.
* <mark style="color:red;">`payload`</mark>:&#x20;
  * <mark style="color:red;">`callbackName`</mark>: 32

```json
{
  "packetID": 123456,
  "payload": 
  {
    "callbackName": 32
  }
}
```

#### Response <a href="#response" id="response"></a>

* <mark style="color:red;">`sn`</mark>: Device serial number.
* <mark style="color:red;">`packetID`</mark>: Matches the request packet ID.
* <mark style="color:red;">`PUBACK`</mark>: 1 when the mode was read successfully; otherwise 0.
  * <mark style="color:red;">`callbackName`</mark>: 32
  * <mark style="color:red;">`callbackArgs`</mark>:&#x20;
    * <mark style="color:red;">`matter_transport`</mark>: Desired Matter transport.
    * <mark style="color:red;">`runtime_mode`</mark>: Current runtime mode.

```json
{
  "sn": "12A3520006E",
  "packetID": 123456,
  "PUBACK": 1,
  "payload": 
  {
    "callbackName": 32,
    "callbackArgs": 
    {
      "matter_transport": 1,
      "runtime_mode": 2
    }
  }
}
```

#### Matter Transport Values <a href="#matter-transport-values" id="matter-transport-values"></a>

| Value | Name               | Description                             |
| ----- | ------------------ | --------------------------------------- |
| `0`   | Matter-over-Wi-Fi  | The desired Matter transport is Wi-Fi.  |
| `1`   | Matter-over-Thread | The desired Matter transport is Thread. |

#### Runtime Mode Values <a href="#runtime-mode-values" id="runtime-mode-values"></a>

| Value | Name               | Description                                                                                    |
| ----- | ------------------ | ---------------------------------------------------------------------------------------------- |
| `0`   | Matter-over-Wi-Fi  | Matter is running over Wi-Fi. Wi-Fi services are available.                                    |
| `1`   | Matter-over-Thread | Matter is running over Thread. Wi-Fi and TCP services are disabled.                            |
| `2`   | Wi-Fi service      | Matter is stopped temporarily while Wi-Fi service, TCP, AWS IoT, and OTA access are available. |
| `3`   | OTA update         | The device is running the Wi-Fi OTA flow and Matter is stopped.                                |

{% hint style="info" %} <mark style="color:red;">`runtime_mode`</mark> is read-only. The firmware derives it from the selected transport, Wi-Fi service state, and OTA state.
{% endhint %}

### Select Matter-over-Wi-Fi <a href="#select-matter-over-wi-fi" id="select-matter-over-wi-fi"></a>

#### Request <a href="#request-1" id="request-1"></a>

Set <mark style="color:red;">`callbackArgs`</mark> to `[0]`:

```json
{
  "packetID": 123457,
  "payload": {
    "callbackName": 32,
    "callbackArgs": [0]
  }
}
```

#### Behavior <a href="#behavior" id="behavior"></a>

* From Matter-over-Wi-Fi: clears Matter pairing and saved Wi-Fi credentials, then reboots into Matter-over-Wi-Fi commissioning.
* From Wi-Fi service: clears the preserved Thread Matter state and saved Wi-Fi credentials, then reboots into Matter-over-Wi-Fi commissioning.
* From OTA mode: rejects the request.
* From Matter-over-Thread: the command cannot be sent because TCP is disabled.

### Select Matter-over-Thread <a href="#select-matter-over-thread" id="select-matter-over-thread"></a>

#### Request <a href="#request-2" id="request-2"></a>

Set <mark style="color:red;">`callbackArgs`</mark> to `[1]`:

```json
{
  "packetID": 123458,
  "payload": {
    "callbackName": 32,
    "callbackArgs": [1]
  }
}
```

#### Behavior <a href="#behavior-1" id="behavior-1"></a>

* From Matter-over-Wi-Fi: clears the current Matter pairing, preserves saved Wi-Fi credentials for future service or OTA use, and reboots into Thread commissioning.
* From Wi-Fi service: preserves the existing Thread fabric and operational dataset, and reboots back into Matter Thread.
* From OTA mode: rejects the request.
* From Matter-over-Thread: the command cannot be sent because TCP is disabled.

### Command Response <a href="#command-response" id="command-response"></a>

The device acknowledges a valid mode-change request before starting the transition:

```json
{
  "sn": "12A3520006E",
  "packetID": 123458,
  "PUBACK": 1
}
```

* <mark style="color:red;">`PUBACK`</mark>: 1 - The transition task was accepted and queued; 0 - The request was malformed, unsupported in the current runtime mode, or another transition is already pending.
* A TCP disconnection shortly after <mark style="color:red;">`PUBACK`</mark> = `1` is expected because the device reboots.
* Do not repeatedly resend the command after receiving <mark style="color:red;">`PUBACK`</mark> = `1`.

### Validation <a href="#validation" id="validation"></a>

For a mode-change request, <mark style="color:red;">`callbackArgs`</mark> must be an array containing exactly one numeric value:

* Valid: `[0]`, `[1]`
* Invalid: `[]`, `[0, 1]`, `[2]`, `["1"]`, `null`

Invalid requests return:

```json
{
  "sn": "12A3520006E",
  "packetID": 123459,
  "PUBACK": 0
}
```

### Recovering TCP Access From Matter-over-Thread <a href="#recovering-tcp-access-from-matter-thread" id="recovering-tcp-access-from-matter-thread"></a>

TCP is unavailable in Matter-over-Thread mode because Wi-Fi is disabled. Hold the device button for at least 30 seconds and release it to enter Wi-Fi service mode. After Wi-Fi reconnects, read callback `32` again. The expected response is:

```json
{
  "matter_transport": 1,
  "runtime_mode": 2
}
```

From Wi-Fi service mode:

* Send `[1]` to return to the preserved Matter Thread commissioning.
* Send `[0]` to erase the Thread Matter state and begin Matter-over-Wi-Fi commissioning.