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

• callbackName: 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.

callbackArgs determines the operation:

callbackArgs	Operation
Omitted	Read the current Matter transport and runtime mode.
[0]	Select Matter-over-Wi-Fi.
[1]	Select Matter-over-Thread.

Changing transport can erase the current Matter commissioning state.

Read Current Mode

Request

• packetID: Any six-digit packet identifier without leading zeros.

• payload:

  • callbackName: 32

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

Response

• sn: Device serial number.

• packetID: Matches the request packet ID.

• PUBACK: 1 when the mode was read successfully; otherwise 0.

  • callbackName: 32

  • callbackArgs:

    • matter_transport: Desired Matter transport.

    • runtime_mode: Current runtime mode.

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

Matter Transport Values

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

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.

runtime_mode is read-only. The firmware derives it from the selected transport, Wi-Fi service state, and OTA state.

Select Matter-over-Wi-Fi

Request

Set callbackArgs to [0]:

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

Behavior

• 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

Request

Set callbackArgs to [1]:

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

Behavior

• 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

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

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

• PUBACK: 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 PUBACK = 1 is expected because the device reboots.

• Do not repeatedly resend the command after receiving PUBACK = 1.

Validation

For a mode-change request, callbackArgs must be an array containing exactly one numeric value:

• Valid: [0], [1]

• Invalid: [], [0, 1], [2], ["1"], null

Invalid requests return:

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

Recovering TCP Access From Matter-over-Thread

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:

{
  "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.