doc: Add DTR/RI documentation

Add documentation for DTR/RI usage.

Remove documentation from power and indicate pins.

Signed-off-by: Markus Lassila <markus.lassila@nordicsemi.no>

Author: MarkusLassila

doc/app/CMUX_AT_commands.rst

@@ -20,18 +20,6 @@ For example, it can be used to exchange AT data and have a :ref:`Point-to-Point
 CMUX is enabled in |SM| by compiling it with the appropriate configuration files, depending on your use case.
 See the :ref:`sm_config_files` section for more information.
 
-.. sm_cmux_baud_rate_note_start
-
-.. note::
-
-   The maximum recommended baud rate is 460 800.
-   At higher baud rates (921 600, 1 000 000), it is possible for bytes to come in faster than the chip is able to handle, which causes the buffer space to run out if it goes on for too long.
-   UART RX is not disabled in that case, which results in data loss and communication failures.
-
-   At a baud rate of 460 800, the maximum throughput is slightly below that of the nRF91 Series modem when using LTE-M.
-
-.. sm_cmux_baud_rate_note_end
-
 .. note::
 
    |SM| does not have an equivalent to the ``AT+CMUX`` command described in 3GPP TS 27.007.

doc/app/Generic_AT_commands.rst

@@ -125,14 +125,24 @@ The test command is not supported.
 Power saving #XSLEEP
 ====================
 
-The ``#XSLEEP`` command makes the nRF91 Series System in Package (SiP) enter idle or sleep mode.
+The ``#XSLEEP`` command makes the |SM| application to enter idle or sleep mode.
+
+.. note::
+
+   The ``#XSLEEP`` command is intended for experimentation and power consumption measurements and must not be used in production.
+
+   You can use the DTR (Data Terminal Ready) and RI (Ring Indicator) signals to control the power state of the UART between the |SM| and the host.
+   See the :ref:`sm_dtr_ri` section for more information about DTR and RI.
+
+.. note::
+
+   If you want to do power measurements on the nRF91 Series development kit while running the |SM| application, remember to disable unused peripherals.
 
-If you want to do power measurements on the nRF91 Series development kit while running the |SM| application, disable unused peripherals.
 
 Set command
 -----------
 
-The set command makes the nRF91 Series SiP enter either Idle or Sleep mode.
+The set command makes the |SM| application enter either Idle or Sleep mode.
 
 Syntax
 ~~~~~~
@@ -146,15 +156,17 @@ The ``<sleep_mode>`` parameter accepts only the following integer values:
 * ``1`` - Enter Sleep.
   In this mode, both the |SM| service and the LTE connection are terminated.
 
-  The nRF91 Series SiP can be woken up using the pin specified with the :ref:`CONFIG_SM_POWER_PIN <CONFIG_SM_POWER_PIN>` Kconfig option.
+  |SM| can be woken up using the DTR pin (``dtr-gpios``).
 
 * ``2`` - Enter Idle.
-  In this mode, both the |SM| service and the LTE connection are maintained.
+  In this mode, both the |SM| service and the LTE connection are maintained, but the UART is disabled to save power.
+  Received data is buffered and sent to the host after idle mode is exited.
+
+  |SM| can exit the idle mode using the DTR pin (``dtr-gpios``).
+  When the |SM| is in idle mode, and there is data to be read by the host, the RI pin (``ri-gpios``) is asserted for a short period of time to notify the host.
+  The host can then deassert and assert DTR to exit idle mode and read the data.
 
-  The nRF91 Series SiP can be made to exit idle using the pin specified with the :ref:`CONFIG_SM_POWER_PIN <CONFIG_SM_POWER_PIN>` Kconfig option.
-  If the :ref:`CONFIG_SM_INDICATE_PIN <CONFIG_SM_INDICATE_PIN>` Kconfig option is defined, |SM| toggles the specified pin when there is data for the MCU to read.
-  The MCU can in turn make |SM| exit idle by toggling the pin specified with the :ref:`CONFIG_SM_POWER_PIN <CONFIG_SM_POWER_PIN>` Kconfig option.
-  The data is buffered when |SM| is idle and sent to the MCU after having exited idle.
+The DTR pin is defined either in the :file:`boards/*_ns.overlay` overlay file matching your board or in the :file:`overlay-external-mcu.overlay` overlay file, if it is included.
 
 .. note::
 
@@ -240,7 +252,7 @@ Syntax
 
 .. note::
 
-   In this case the nRF91 Series SiP cannot be woken up using the pin specified with the :ref:`CONFIG_SM_POWER_PIN <CONFIG_SM_POWER_PIN>` Kconfig option.
+   In this case the nRF91 Series SiP cannot be woken up using the DTR pin (``dtr-gpios``).
 
 Example
 ~~~~~~~~

doc/app/README.rst

@@ -22,4 +22,5 @@ See the subpages for how to use the application, how to extend it, and informati
    sm_testing
    sm_extending
    sm_data_mode
+   sm_dtr_ri
    AT_commands

doc/app/nRF91_as_Zephyr_modem.rst

@@ -10,7 +10,7 @@ nRF91 Series as a Zephyr-compatible modem
 Overview
 ********
 
-Starting with |NCS| v2.6.0, the |SM| (SM) application can be used to turn an nRF91 Series SiP into a standalone modem that can be used through Zephyr's cellular modem driver.
+The |SM| application can be used to turn an nRF91 Series SiP into a standalone modem that can be used through Zephyr's cellular modem driver.
 This means that the controlling chip can run a Zephyr application that seamlessly uses Zephyr's IP stack instead of offloaded sockets through AT commands.
 
 This is made possible by |SM|'s support of CMUX and PPP and Zephyr's cellular modem driver.
@@ -32,10 +32,6 @@ For that, Kconfig fragments and devicetree overlays must be added to the compila
 
 See the :ref:`sm_config_files` section for information on how to compile with additional configuration files and a description of some of the mentioned Kconfig fragments.
 
-.. include:: CMUX_AT_commands.rst
-   :start-after: sm_cmux_baud_rate_note_start
-   :end-before: sm_cmux_baud_rate_note_end
-
 nRF91 Series SiP running |SM|
 =============================
 
@@ -44,20 +40,20 @@ The following configuration files must be included:
 * :file:`overlay-cmux.conf` - To enable CMUX.
 * :file:`overlay-ppp.conf` - To enable PPP.
 * :file:`overlay-zephyr-modem.conf` - To tailor |SM| to how Zephyr's cellular modem driver works.
-  This enables the :ref:`CONFIG_SM_START_SLEEP <CONFIG_SM_START_SLEEP>` Kconfig option, which makes the nRF91 Series SiP start only when the :ref:`power pin <CONFIG_SM_POWER_PIN>` is toggled.
 
 In addition, if the controlling chip is an external MCU, the following configurations must also be included:
 
-* :ref:`CONFIG_SM_POWER_PIN <CONFIG_SM_POWER_PIN>` Kconfig option - To define the power pin so that it matches your setup.
-* :file:`overlay-external-mcu.overlay` - To configure which UART |SM| will use.
-  The actual configuration of the UART is defined in the :file:`*_ns.overlay` overlay file matching your board in the :file:`boards` directory.
+* :file:`overlay-external-mcu.overlay` - To configure UART (pins, baud rate), DTR and RI pins that |SM| will use.
   Make sure to update the UART configuration (pins, baud rate) so that it matches your setup.
-  You can do this by modifying the properties of the node of the UART to be used, by editing either :file:`overlay-external-mcu.overlay` or the overlay file matching your board in the :file:`boards` directory.
+* :file:`overlay-zephyr-modem-external-mcu.overlay` - To define the power GPIO with ``sm-power-key``. If ``sm-power-key`` is configured, the nRF91 Series SIP will start only when the pin in ``sm-power-key`` is toggled by the controlling chip.
+  On the controlling chip, running Zephyr, the power GPIO is configured with the ``mdm-power-gpios``.
+  This overlay also sets the DTR pin to be always asserted, as the Zephyr's cellular modem driver does not currently manage it.
 
 Or, if the controlling chip is the nRF52840 of the nRF9160 DK, the following files must also be included:
 
-* :file:`overlay-zephyr-modem-nrf9160dk-nrf52840.conf` - To define the power pin.
-* :file:`overlay-zephyr-modem-nrf9160dk-nrf52840.overlay` - To configure the UART to be routed between the nRF9160 and the nRF52840 of the DK.
+* :file:`overlay-zephyr-modem-nrf9160dk-nrf52840.overlay` - To configure the UART, DTR, and RI pins, to be routed between the nRF9160 and the nRF52840 of the DK.
+  This overlay also sets the DTR pin to be always asserted, as the Zephyr's cellular modem driver does not currently manage it.
+  Note that there is no power pin as there are not enough GPIOs available to use it.
 
 Finally, if you want more verbose logging that includes the AT commands and responses, you can enable debug logging by uncommenting ``CONFIG_SM_LOG_LEVEL_DBG=y`` in the :file:`prj.conf` configuration file.
 
@@ -69,7 +65,7 @@ Configuration files found in `Zephyr’s Cellular modem`_ sample are a good star
 Specifically, regardless of what the controlling chip is, the Kconfig options found in the following files are needed:
 
 * :file:`prj.conf` - This file enables various Zephyr APIs, most of which are needed for proper functioning of the application.
-* :file:`boards/nrf9160dk_nrf52840.conf` - This file tailors the configuration of the modem subsystem and driver to the |SM|.
+* :file:`boards/nrf9160dk_nrf9160_ns.conf` (or :file:`boards/nrf9160dk_nrf52840.conf`) - This file tailors the configuration of the modem subsystem and driver to the |SM|.
   It makes the application's logs be output on UART 0 and also enables the debug logs of the cellular modem driver.
   If you do not want the debug logs output by the driver, you may turn them off by removing ``CONFIG_MODEM_LOG_LEVEL_DBG=y``.
 
@@ -93,7 +89,7 @@ You can even compile, flash and run the sample to verify proper operation of the
 Flashing and running
 ********************
 
-When built with the Zephyr-compatible modem configuration, |SM| will put the nRF91 Series SiP to deep sleep when powered on.
+When built with the Zephyr-compatible modem configuration, and :file:`overlay-zephyr-modem-external-mcu.overlay` is used, |SM| will put the nRF91 Series SiP to deep sleep when powered on.
 Zephyr's cellular modem driver running on the controlling chip will take care of waking up the nRF91 Series SiP, so it is advised to first flash |SM| to the nRF91 Series SiP.
 
 However, before flashing the |SM| built with the Zephyr-compatible modem configuration, make sure that the nRF91 Series modem has been set to the desired system mode.
@@ -126,10 +122,9 @@ Under Linux, if the controlling chip is the nRF52840 of the nRF9160 DK, the devi
 After both applications have been flashed to their respective chips and you are connected to receive logs, you can reset the controlling chip.
 When the Zephyr application starts up, the following happens:
 
-* If power management is enabled (the ``CONFIG_PM_DEVICE`` Kconfig option is set to ``y``): when the application powers on the modem (by calling ``pm_device_action_run(<dev>, PM_DEVICE_ACTION_RESUME)`` as the sample does), the cellular modem driver will toggle the modem's power pin to wake it up.
+* If power management is enabled (the :file:`overlay-zephyr-modem-external-mcu.overlay` is included): when the application powers on the modem (by calling ``pm_device_action_run(<dev>, PM_DEVICE_ACTION_RESUME)`` as the sample does), the cellular modem driver will toggle the modem's power pin to wake it up.
 
   If power management is not enabled, the cellular modem driver will automatically proceed and expect |SM| to already be started and in a pristine state.
-  In this case, |SM| should be compiled with the :ref:`CONFIG_SM_START_SLEEP <CONFIG_SM_START_SLEEP>` Kconfig option set to ``n``, and :ref:`CONFIG_SM_POWER_PIN <CONFIG_SM_POWER_PIN>` can be left undefined.
 
 * The cellular modem driver will start sending AT commands to |SM|.
   It will enable the network status notifications, gather some information from the modem, enable CMUX, and set the modem to normal mode (with an ``AT+CFUN=1`` command).