doc: document switching protocol options

Document the behavior of `CONFIG_ZIGBEE_MATTER_PROTOCOL_STATE_DEFAULT_PROTOCOL`
and `CONFIG_ZIGBEE_MATTER_COEXISTENCE_BUTTON_SWITCH`.

Signed-off-by: Eduardo Montoya <eduardo.montoya@nordicsemi.no>

Author: edmont

docs/architectures.rst

@@ -90,7 +90,10 @@ Single-chip, combined Matter + Zigbee (SoC)
 ===========================================
 
 In this design, the Zigbee (ZBOSS) and Matter over Thread (OpenThread) stacks run on the same nRF SoC and share the single 802.15.4 radio through a coexistence layer, while a `SoftDevice Controller`_ instance handles Bluetooth LE (CHIPoBLE) commissioning.
-Radio ownership is time-separated and persisted across reboots: the device boots as a Zigbee node, advertises for Matter commissioning over Bluetooth LE in parallel, and hands the 802.15.4 radio over to OpenThread once the first Matter CASE session is established.
+Radio ownership is time-separated and persists across reboots. 
+The device boots on the configured default protocol (Zigbee by default).
+While Zigbee is active, Matter advertises for commissioning over Bluetooth LE in parallel.
+The 802.15.4 radio is handed over to OpenThread once Matter commissioning completes or you request a protocol switch.
 
 .. list-table::
    :header-rows: 1
@@ -100,8 +103,8 @@ Radio ownership is time-separated and persisted across reboots: the device boots
      - Advantage
      - Trade-off
    * - Deployment model
-     - A single firmware image can start as Zigbee and migrate to Matter after commissioning, without reflashing.
-     - Switching back to Zigbee requires a Matter factory reset, which clears Matter commissioning data.
+     - A single firmware image can start as Zigbee and migrate to Matter after commissioning or a button-triggered switch, without reflashing.
+     - Switching back to Zigbee is supported by a long button press. Removing the last Matter fabric or triggering a Matter factory reset clears Matter commissioning data and resets the persisted protocol to the configured default.
    * - Radio usage
      - Bluetooth LE commissioning (CHIPoBLE) runs concurrently with Zigbee operation, so no separate commissioning device is needed.
      - The 802.15.4 radio is used by one stack at a time. Zigbee operation pauses once the device switches to Matter.

docs/includes/matter_extension_limitations.txt

@@ -1,6 +1,7 @@
 As a proof of concept, the Matter extension has the following limitations:
 
-* The 802.15.4 radio is time-shared, never concurrent: once the device is provisioned to Matter, Zigbee is torn down, and returning to Zigbee requires a Matter factory reset (which also wipes Matter storage).
-* The Matter extension cannot be combined with the :ref:`Multiprotocol Bluetooth LE extension <zigbee_light_switch_sample_nus>` (``overlay-multiprotocol_ble.conf``) or with the Zigbee-only FOTA build (``FILE_SUFFIX=fota``).
-* The Matter shell (``CONFIG_CHIP_LIB_SHELL``) and the Matter test shell are disabled to avoid option-parsing conflicts with the Zigbee shell.
+* The 802.15.4 radio is time-shared, never concurrent: once the device runs on Matter, Zigbee is torn down until the active protocol changes again.
+  To switch back to Zigbee, ensure the ``CONFIG_ZIGBEE_MATTER_COEXISTENCE_BUTTON_SWITCH`` Kconfig option is enabled, then long-press the button.
+  Removing all Matter fabrics or triggering a Matter factory reset wipes Matter storage and resets the persisted protocol to the value selected by the ``CONFIG_ZIGBEE_MATTER_PROTOCOL_STATE_DEFAULT_PROTOCOL`` Kconfig option.* The Matter extension cannot be combined with the :ref:`Multiprotocol Bluetooth LE extension <zigbee_light_switch_sample_nus>` (``overlay-multiprotocol_ble.conf``) or with the Zigbee-only FOTA build (``FILE_SUFFIX=fota``).
+* You cannot combine the Matter extension with the :ref:`Multiprotocol Bluetooth LE extension <zigbee_light_switch_sample_nus>` (``overlay-multiprotocol_ble.conf``) or with the Zigbee-only FOTA build (``FILE_SUFFIX=fota``).
 * The memory footprint is tuned empirically for ``nrf54lm20dk/nrf54lm20a/cpuapp`` and ``nrf54lm20dk/nrf54lm20b/cpuapp``; porting to other targets requires revisiting the libc heap, ZBOSS thread, system work queue and partition sizes used by :file:`prj_matter_fota.conf`.

docs/includes/matter_extension_protocol_switch.txt

@@ -0,0 +1,16 @@
+The default protocol on a factory-fresh device is selected by the ``CONFIG_ZIGBEE_MATTER_PROTOCOL_STATE_DEFAULT_PROTOCOL`` Kconfig choice (Zigbee by default).
+A Matter factory reset (including last-fabric removal when ``CONFIG_CHIP_LAST_FABRIC_REMOVED_ERASE_AND_REBOOT`` is enabled) applies the same default again and wipes Matter commissioning data.
+After the first run, the persisted protocol state in settings takes precedence until a factory reset or explicit protocol switch changes it.
+
+When ``CONFIG_ZIGBEE_MATTER_COEXISTENCE_BUTTON_SWITCH`` is enabled (the default), you can long-press the selected button to switch the active protocol.
+Configure the required hold time by setting the ``CONFIG_ZIGBEE_MATTER_COEXISTENCE_SWITCH_BUTTON_PRESS_TIME_SECONDS`` Kconfig option. 
+By default, this option is set to 5 seconds.
+From Zigbee, the coexistence layer stops the ZBOSS stack and hands the 802.15.4 radio to OpenThread for Matter.
+From Matter, the device persists Zigbee as the active protocol and reboots.
+The protocol switch is ignored while the device is joining a Zigbee network or undergoing Matter commissioning.
+
+Other Kconfig options in the coexistence layer:
+
+* ``CONFIG_ZIGBEE_MATTER_COEXISTENCE_BT_ADV_WHILE_ZIGBEE`` (default enabled) — Matter may advertise for commissioning over Bluetooth LE while Zigbee owns the 802.15.4 radio.
+  When disabled, the sample must call ``zigbee_matter_coexistence_signal_matter_board_init()`` after Matter server init, and the Zigbee worker proceeds without waiting for CHIPoBLE advertising.
+* ``CONFIG_ZIGBEE_MATTER_COEXISTENCE_BUTTON_SWITCH`` — Enable or disable the button-triggered protocol switch.

samples/light_bulb/README.rst

@@ -46,13 +46,15 @@ It is supported only on the ``nrf54lm20dk/nrf54lm20a/cpuapp`` and ``nrf54lm20dk/
 
 The sample-specific behavior is:
 
-* On first boot, the device is a standard :ref:`Zigbee Router <zigbee_roles>` exposing the Dimmable Light device, while the Matter stack advertises for commissioning over Bluetooth LE (CHIPoBLE).
+* On first boot, the device starts on the protocol selected by ``CONFIG_ZIGBEE_MATTER_PROTOCOL_STATE_DEFAULT_PROTOCOL`` (Zigbee by default).
+  When Zigbee is active, it is a standard :ref:`Zigbee Router <zigbee_roles>` exposing the Dimmable Light device, while the Matter stack advertises for commissioning over Bluetooth LE (CHIPoBLE).
 * After successful Matter commissioning, the device is converted to a Matter Dimmable Light endpoint that serves the On/Off and Level Control clusters and drives the same LED through PWM.
   It can then be controlled by any device on the Matter fabric bound to it (for example, the :ref:`zigbee_light_switch_sample` built with the :ref:`zigbee_light_switch_sample_matter`).
-* On subsequent boots, the device starts directly as a Matter Dimmable Light. 
-  A Matter factory reset reverts it to a fresh Zigbee Router.
+* On subsequent boots, the device resumes the persisted protocol.
+  When Matter was selected, it starts directly as a Matter Dimmable Light.
+  A Matter factory reset resets the persisted protocol to the configured default and wipes Matter commissioning data.
 
-The radio hand-over, persistent protocol state, factory-reset behavior and onboarding-data generation are common to both combined samples and are described in detail in the :ref:`zigbee_light_switch_sample_matter` section of the Light switch sample.
+The radio hand-over, persistent protocol state, user-triggered protocol switch, factory-reset behavior and onboarding-data generation are common to both combined samples and are described in detail in the :ref:`zigbee_light_switch_sample_matter` section of the Light switch sample.
 
 .. _zigbee_light_bulb_sample_touchlink:
 
@@ -115,6 +117,9 @@ User interface
       LED 2:
           Turns on when the light bulb joins the network.
 
+      Button 2:
+          If ``CONFIG_ZIGBEE_MATTER_COEXISTENCE_BUTTON_SWITCH`` is enabled (default), it triggers a protocol switch after a long press (``CONFIG_ZIGBEE_MATTER_COEXISTENCE_SWITCH_BUTTON_PRESS_TIME_SECONDS``, 5 s by default).
+          
       Button 3:
           Depending on how long the button is pressed:
 
@@ -241,15 +246,22 @@ Complete the following steps to exercise the full Zigbee-to-Matter flow:
         The two devices form a distributed-security Zigbee network without a Zigbee Coordinator, and the light switch finds and controls the light bulb.
 
    While the device is still a Zigbee Router, it also advertises for Matter commissioning over Bluetooth LE.
+#. Optionally, long-press Button 2 for ``CONFIG_ZIGBEE_MATTER_COEXISTENCE_SWITCH_BUTTON_PRESS_TIME_SECONDS`` to switch to Matter.
+   The Zigbee stack is stopped and the radio is handed to OpenThread.
+   Skip the next step if you use this path and Matter was already commissioned in a previous session.
 #. Commission the device using the onboarding payload produced by the Matter factory data build (QR code or manual pairing code).
    After the Matter CASE session is established, the light bulb hands the radio over to Thread and stops participating in the Zigbee network.
 #. Drive the light bulb from a Matter peer:
 
    * From the controller directly, with ``chip-tool onoff toggle …`` or ``chip-tool levelcontrol move-to-level …``.
    * Or by binding a Matter switch to the light bulb and using the switch's dimmer button.
 
-#. To return the device to Zigbee operation, trigger a Matter factory reset from the controller (for example, ``chip-tool pairing unpair …``).
-   The device reboots as a fresh Zigbee Router with Matter Bluetooth LE advertising active again.
+#. To return the device to Zigbee operation, use one of the following:
+
+   * Long-press Button 2 for ``CONFIG_ZIGBEE_MATTER_COEXISTENCE_SWITCH_BUTTON_PRESS_TIME_SECONDS``.
+     The device reboots and resumes as a Zigbee Router.
+   * Or trigger a Matter factory reset from the controller (for example, ``chip-tool pairing unpair …``).
+     The device reboots as a fresh Zigbee Router with Matter Bluetooth LE advertising active again, and Matter storage is cleared.
 
 Dependencies
 ************

samples/light_switch/README.rst

@@ -102,12 +102,15 @@ It is supported only on the ``nrf54lm20dk/nrf54lm20a/cpuapp`` and ``nrf54lm20dk/
 
 Protocol selection is time-separated and persisted across reboots:
 
-* On first boot, Zigbee owns the 802.15.4 radio and the device behaves as a standard :ref:`Zigbee End Device <zigbee_roles>` (Dimmer Switch).
+* On first boot, the device starts on the protocol selected by ``CONFIG_ZIGBEE_MATTER_PROTOCOL_STATE_DEFAULT_PROTOCOL`` (Zigbee by default) and behaves as a standard :ref:`Zigbee End Device <zigbee_roles>` (Dimmer Switch) when Zigbee is active.
   In parallel, the Matter stack advertises for commissioning over Bluetooth LE (CHIPoBLE) for the duration configured by ``CONFIG_CHIP_BLE_ADVERTISING_DURATION`` (60 s by default).
 * When a Matter commissioner completes commissioning (first CASE session established while Thread is not yet attached), the coexistence layer stops the Zigbee stack, hands the radio over to OpenThread, and persists the selected protocol.
   From this point on, the device operates as a Matter Dimmer Switch that controls remote Matter lights through the client-side binding cluster.
-* On subsequent boots, if the persisted protocol is Matter, the Zigbee stack is skipped entirely and the radio goes directly to OpenThread.
-* A Matter factory reset wipes the Zigbee network information, resets the persisted protocol back to Zigbee, and reboots the device as a fresh, commissioning-ready Zigbee End Device.
+* On subsequent boots, the device resumes the persisted protocol.
+  If Matter was selected, the Zigbee stack is skipped entirely and the radio goes directly to OpenThread.
+* A Matter factory reset wipes the Zigbee network information when Zigbee was active, resets the persisted protocol to the value selected by ``CONFIG_ZIGBEE_MATTER_PROTOCOL_STATE_DEFAULT_PROTOCOL``, wipes Matter commissioning data, and reboots the device in that default state.
+
+.. include:: /includes/matter_extension_protocol_switch.txt
 
 Onboarding data (discriminator, passcode, QR code) is produced by the Matter factory data module (``CONFIG_CHIP_FACTORY_DATA_BUILD``) at build time.
 
@@ -345,6 +348,16 @@ Matter extension Touchlink assignments
           When you are building the sample with the Matter extension and press the button during normal operation (after boot), it starts Touchlink commissioning as initiator.
           See :ref:`zigbee_light_switch_sample_touchlink`.
 
+Matter extension protocol switch assignments
+============================================
+
+.. tabs::
+
+   .. group-tab:: nRF54 DKs
+
+      Button 2:
+          If ``CONFIG_ZIGBEE_MATTER_COEXISTENCE_BUTTON_SWITCH`` is enabled (default), it triggers a protocol switch after a long press (``CONFIG_ZIGBEE_MATTER_COEXISTENCE_SWITCH_BUTTON_PRESS_TIME_SECONDS``, 5 s by default).
+
 Multiprotocol Bluetooth LE extension assignments
 ================================================
 
@@ -531,12 +544,19 @@ Complete the following steps to exercise the full Zigbee-to-Matter flow:
      #. Power the light switch and press the Touchlink button (see :ref:`zigbee_light_switch_sample_touchlink`).
         The two devices form a distributed-security Zigbee network and the light switch finds the bulb to control, without a Zigbee Coordinator on the network.
 
-   While the device is still a Zigbee End Device, it also advertises for Matter commissioning over Bluetooth LE.
+   While the device is still a Zigbee End Device, it also advertises for Matter commissioning over Bluetooth LE if ``CONFIG_ZIGBEE_MATTER_COEXISTENCE_BT_ADV_WHILE_ZIGBEE`` is enabled.
+#. Optionally, long-press Button 2 for ``CONFIG_ZIGBEE_MATTER_COEXISTENCE_SWITCH_BUTTON_PRESS_TIME_SECONDS`` to switch to Matter.
+   The Zigbee stack is stopped and the radio is handed to OpenThread.
+   Skip the next step if you use this path and Matter was already commissioned in a previous session.
 #. Commission the device using the onboarding payload produced by the Matter factory data build (QR code or manual pairing code).
    After the Matter CASE session is established, the light switch hands the radio over to Thread and stops participating in the Zigbee network.
 #. Bind the light switch to a Matter light (for example, with ``chip-tool binding write binding …``) and use the dimmer button to toggle or dim the bound light over Thread.
-#. To return the device to Zigbee operation, trigger a Matter factory reset from the controller (for example, ``chip-tool pairing unpair …``).
-   The device reboots as a fresh Zigbee End Device with Matter Bluetooth LE advertising active again.
+#. To return the device to Zigbee operation, use one of the following:
+
+   * Long-press Button 2 for ``CONFIG_ZIGBEE_MATTER_COEXISTENCE_SWITCH_BUTTON_PRESS_TIME_SECONDS``.
+     The device reboots and resumes as a Zigbee End Device.
+   * Or trigger a Matter factory reset from the controller (for example, ``chip-tool pairing unpair …``).
+     The device reboots as a fresh Zigbee End Device with Matter Bluetooth LE advertising active again, and Matter storage is cleared.
 
 Sample output
 -------------