diff --git a/doc/app/sm_dtr_ri.rst b/doc/app/sm_dtr_ri.rst index 664b2d8f..e2e9f699 100644 --- a/doc/app/sm_dtr_ri.rst +++ b/doc/app/sm_dtr_ri.rst @@ -61,4 +61,4 @@ The following image illustrates the DTR and RI signal behavior in relation to th DTR/RI signal diagram -The :ref:`sm_at_client_shell_sample` sample and :ref:`lib_sm_at_client` library show an example of how to use DTR and RI signals in an external MCU application. +The :ref:`sm_samples` and :ref:`lib_sm_at_client` library show an example of how to use DTR and RI signals in an external MCU application. diff --git a/doc/images/samples_overview.svg b/doc/images/samples_overview.svg new file mode 100644 index 00000000..c2ba70cb --- /dev/null +++ b/doc/images/samples_overview.svg @@ -0,0 +1,327 @@ + + + + + + + + + + + + + + Serial Modem Host Sample Setup + + + nRF91 Series DK + (nRF9151) + + + Serial Modem + Application + (AT command interface) + + + Cellular Modem + (LTE-M / NB-IoT) + + + + Host MCU + (nRF54L15) + + + Host Sample + Application + (AT commands or Zephyr stack) + + + Application Logic + (Shell / Network services) + + + + + + + UARTTX/RX + + + Cellular Network + + + + DTR + + + RING + + CTS/RTS + diff --git a/doc/index.rst b/doc/index.rst index e949c438..a98ca7bf 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -13,7 +13,7 @@ It includes host examples in the form of the |SM| AT Client library and the |SM| gsg_guide app/README - samples/sm_at_client_shell + samples/README drivers/dtr_uart lib/sm_at_client migration_notes diff --git a/doc/links.txt b/doc/links.txt index 36d7099c..4726cb13 100644 --- a/doc/links.txt +++ b/doc/links.txt @@ -77,6 +77,13 @@ .. _`Serial Terminal app`: https://docs.nordicsemi.com/bundle/nrf-connect-serial-terminal/page/index.html .. _`Board Configurator app`: https://docs.nordicsemi.com/bundle/nrf-connect-board-configurator/page/index.html +.. ### docs.zephyrproject.org/ + +.. _`Zephyr Networking`: https://docs.zephyrproject.org/latest/connectivity/networking/index.html +.. _`Zephyr Network APIs`: https://docs.zephyrproject.org/latest/connectivity/networking/api/apis.html +.. _`Zephyr Modem modules`: https://docs.zephyrproject.org/latest/services/modem/index.html +.. _`zperf: Network Traffic Generator`: https://docs.zephyrproject.org/latest/connectivity/networking/api/zperf.html + .. ### github.com .. _`github_release`: https://github.com/nrfconnect/ncs-serial-modem/releases @@ -86,7 +93,6 @@ .. ### others .. _`Private addresses`: https://en.wikipedia.org/wiki/IP_address#Private_addresses -.. _`Zephyr Network APIs`: https://docs.zephyrproject.org/latest/connectivity/networking/api/apis.html#network-apis .. _`3GPP TS 27.010`: https://www.etsi.org/deliver/etsi_ts/127000_127099/127010/18.00.00_60/ts_127010v180000p.pdf .. _`3GPP TS 27.007`: https://www.etsi.org/deliver/etsi_ts/127000_127099/127007/18.06.00_60/ts_127007v180600p.pdf diff --git a/doc/samples/README.rst b/doc/samples/README.rst new file mode 100644 index 00000000..297bdb7b --- /dev/null +++ b/doc/samples/README.rst @@ -0,0 +1,37 @@ +.. _sm_samples: + +|SM| host samples +################# + +The |SM| includes sample applications that demonstrate how to interact with the |SM| application running on an nRF91 Series device. +These samples showcase different integration approaches for controlling the nRF91 Series SiP as a cellular modem. + +.. figure:: ../images/samples_overview.svg + :alt: Serial Modem samples overview + + |SM| running on nRF91 Series DK with a host sample application on an external MCU + +Use the :ref:`sm_at_client_shell_sample` when: + +* You need direct AT command control +* Your application uses offloaded sockets +* You want to use the |SM| Host library +* You're working with resource-constrained MCUs +* You need to send both standard and proprietary AT commands + +Use the :ref:`sm_ppp_shell` when: + +* You want to use Zephyr's native networking stack +* You prefer standard POSIX socket APIs +* You need to test network performance +* You're developing on Linux with the native simulator +* You want seamless integration with Zephyr network services + +Both samples require the |SM| application to be running on an nRF91 Series device. + +.. toctree:: + :maxdepth: 2 + :caption: Sample applications: + + sm_at_client_shell + sm_ppp_shell diff --git a/doc/samples/sm_ppp_shell.rst b/doc/samples/sm_ppp_shell.rst new file mode 100644 index 00000000..c997cc3a --- /dev/null +++ b/doc/samples/sm_ppp_shell.rst @@ -0,0 +1,249 @@ +.. _sm_ppp_shell: + +|SM| PPP shell sample +##################### + +.. contents:: + :local: + :depth: 2 + +The |SM| PPP shell sample demonstrates how to use the nRF91 Series SiP as a Zephyr-compatible cellular modem through a PPP (Point-to-Point Protocol) interface. +This sample enables an external MCU or Linux host to use Zephyr's native networking stack and shell commands to control the cellular modem, test network connectivity, and measure network performance. + +Overview +******** + +This sample showcases the integration between Zephyr's cellular modem driver and the |SM| application running on an nRF91 Series SiP. +Instead of using AT commands directly, the controlling device can use Zephyr's standard networking APIs and shell commands to interact with the modem. + +The sample provides: + +* Full Zephyr networking stack (IPv4 and IPv6 support) +* Network shell commands for interface management +* Network performance testing using zperf +* DNS resolution support +* Automatic modem connection management +* CMUX (GSM 07.10) multiplexing support +* Power management with runtime power saving + +For more information about using the nRF91 Series SiP as a Zephyr-compatible modem, see :ref:`sm_as_zephyr_modem`. + +Requirements +************ + +The |SM| application must be built with the following overlays: + +* :file:`app/overlay-cmux.conf` - To enable CMUX support +* :file:`app/overlay-ppp.conf` - To enable PPP support + +If using an external MCU as the controlling device, also include: + +* :file:`app/overlay-external-mcu.overlay` - To configure UART pins, DTR, and RI signals + +The sample supports the following development kits: + +.. list-table:: + :widths: auto + :header-rows: 1 + + * - Hardware platforms + - PCA + - Board name + - Board target + * - `nRF54L15 DK `_ + - PCA10156 + - `nrf54l15dk`_ + - ``nrf54l15dk/nrf54l15/cpuapp`` + * - `nRF54L15 DK `_ (TrustZone) + - PCA10156 + - `nrf54l15dk`_ + - ``nrf54l15dk/nrf54l15/cpuapp/ns`` + * - Native simulator + - N/A + - ``native_sim`` + - ``native_sim`` + +Hardware setup for nRF54L15 DK +============================== + +When using the nRF54L15 DK as the controlling device, connect the DK pins to the corresponding pins on the nRF91 Series DK as follows: + +.. list-table:: + :header-rows: 1 + + * - nRF54L15 DK + - nRF91 Series DK + * - UART TX P0.00 + - UART RX P0.11 + * - UART RX P0.01 + - UART TX P0.10 + * - UART CTS P0.03 + - UART RTS P0.12 + * - UART RTS P0.02 + - UART CTS P0.13 + * - DTR OUT P1.11 + - DTR IN P0.31 + * - RI IN P1.12 + - RI OUT P0.30 + * - GPIO GND + - GPIO GND + +.. note:: + You must disable the VCOM0 on the nRF54L15 DK to release the UART GPIO pins for communication with the |SM|. + + * Use the `Board Configurator app`_ to disable the ``Connect port VCOM0`` setting. + +.. note:: + The GPIO output levels on the nRF91 Series device and nRF54L15 DK must be the same. + + * Set the VDD voltages for both devices using the `Board Configurator app`_. + +Native simulator setup +====================== + +When running on the native simulator, the sample expects the |SM| to be available at ``/dev/ttyACM0`` on the Linux host system. +Connect the nRF91 Series DK running |SM| to your Linux host via USB. + +Building and running +******************** + +nRF54L15 DK +=========== + +To build the sample for the nRF54L15 DK: + +.. code-block:: bash + + west build -b nrf54l15dk/nrf54l15/cpuapp + +For the TrustZone-enabled variant: + +.. code-block:: bash + + west build -b nrf54l15dk/nrf54l15/cpuapp/ns + +Flash the sample to your board and open a serial terminal to view the shell interface. + +For nRF54L15 DK, the shell is available on UART1 (VCOM1). + +Native simulator +================ + +To build the sample for the native simulator: + +.. code-block:: bash + + west build -b native_sim + +For native simulator, run the executable with the ``-attach_uart`` option: + +.. code-block:: bash + + build/zephyr/zephyr.exe -attach_uart + +Testing +******* + +After the sample starts, you will see the Zephyr shell prompt. +The PPP network interface is configured to start the modem automatically when requested. + +Bringing up the network interface +================================= + +To start the cellular modem and establish a network connection: + +.. code-block:: console + + uart:~$ net iface up 1 + +The modem will begin the network registration process. +You can monitor the connection status with: + +.. code-block:: console + + uart:~$ net iface + +The network management event monitor (enabled by default) will also display connection events automatically. + +Once connected, the interface will show as "UP" and you will see an assigned IP address. + +Testing network connectivity +============================ + +After the network interface is up, you can test basic connectivity. + +To ping a (DNS) server: + +.. code-block:: console + + uart:~$ net ping 8.8.8.8 + +To perform DNS resolution: + +.. code-block:: console + + uart:~$ net dns google.com + +Performance testing with zperf +============================== + +The sample includes the zperf tool for network performance measurements: + +To run a UDP upload test: + +.. code-block:: console + + uart:~$ zperf udp upload + +See the `zperf: Network Traffic Generator`_ for more details on using zperf. + +Shutting down the network interface +=================================== + +To shut down the cellular connection and power off the modem: + +.. code-block:: console + + uart:~$ net iface down 1 + +Configuration +************* + +The sample is configured with the following key features: + +* PPP Layer 2 networking +* IPv4 and IPv6 support +* TCP and UDP protocols +* DNS resolver with automatic DNS server configuration from PPP +* Network connection manager for automatic reconnection +* Zephyr cellular modem driver with CMUX support +* Runtime power management with automatic power saving +* Network shell commands +* Zperf for network performance testing + +The CMUX configuration enables: + +* Power save mode that closes CMUX pipes when idle +* 5-second idle timeout before entering power save +* MTU size of 127 bytes for optimal performance + +Dependencies +************ + +The sample enables the following key features: + +* Networking stack (``CONFIG_NETWORKING``) +* PPP L2 layer (``CONFIG_NET_L2_PPP``) +* Cellular modem driver (``CONFIG_MODEM_CELLULAR``) +* Network shell (``CONFIG_NET_SHELL``) +* Zperf (``CONFIG_NET_ZPERF``) +* Power management (``CONFIG_PM_DEVICE``) + +References +********** + +* :ref:`sm_as_zephyr_modem` +* :ref:`sm_description` +* `Zephyr Networking`_ +* `Zephyr Network APIs`_ +* `Zephyr Modem modules`_ diff --git a/samples/sm_ppp_shell/CMakeLists.txt b/samples/sm_ppp_shell/CMakeLists.txt new file mode 100644 index 00000000..622b2ae2 --- /dev/null +++ b/samples/sm_ppp_shell/CMakeLists.txt @@ -0,0 +1,12 @@ +# +# Copyright (c) 2025 Nordic Semiconductor ASA +# +# SPDX-License-Identifier: LicenseRef-Nordic-5-Clause +# + +cmake_minimum_required(VERSION 3.20.0) + +find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE}) +project(app) + +target_sources(app PRIVATE src/main.c) diff --git a/samples/sm_ppp_shell/boards/native_sim.conf b/samples/sm_ppp_shell/boards/native_sim.conf new file mode 100644 index 00000000..3bab2d30 --- /dev/null +++ b/samples/sm_ppp_shell/boards/native_sim.conf @@ -0,0 +1,14 @@ +# +# Copyright (c) 2025 Nordic Semiconductor ASA +# +# SPDX-License-Identifier: LicenseRef-Nordic-5-Clause +# + +# Run Native sim in real-time mode. +CONFIG_NATIVE_SIM_SLOWDOWN_TO_REAL_TIME=y + +# As of today, native_sim does not properly support UART async API with PM_RUNTIME. +#CONFIG_UART_ASYNC_API=y +CONFIG_UART_INTERRUPT_DRIVEN=y +CONFIG_SHELL_BACKEND_SERIAL_API_POLLING=y +CONFIG_SHELL_BACKEND_SERIAL_INTERRUPT_DRIVEN=n diff --git a/samples/sm_ppp_shell/boards/native_sim.overlay b/samples/sm_ppp_shell/boards/native_sim.overlay new file mode 100644 index 00000000..9c693d5f --- /dev/null +++ b/samples/sm_ppp_shell/boards/native_sim.overlay @@ -0,0 +1,20 @@ +/ { + /* + * Enable UART2 as the serial interface to the nRF91 Serial Modem application. + * Assume that the UART which receives modem AT-commands is available at /dev/ttyACM0 on the host system. + */ + uart2: uart2 { + status = "okay"; + compatible = "zephyr,native-tty-uart"; + serial-port = "/dev/ttyACM0"; + current-speed = <115200>; + hw-flow-control; + + modem: modem { + compatible = "nordic,nrf91-slm"; + status = "okay"; + zephyr,pm-device-runtime-auto; + }; + }; + +}; diff --git a/samples/sm_ppp_shell/boards/nrf54l15dk_nrf54l15_cpuapp.conf b/samples/sm_ppp_shell/boards/nrf54l15dk_nrf54l15_cpuapp.conf new file mode 100644 index 00000000..5ef8fa11 --- /dev/null +++ b/samples/sm_ppp_shell/boards/nrf54l15dk_nrf54l15_cpuapp.conf @@ -0,0 +1,14 @@ +# +# Copyright (c) 2025 Nordic Semiconductor ASA +# +# SPDX-License-Identifier: LicenseRef-Nordic-5-Clause +# + +# Use UART async API with PM_RUNTIME. +CONFIG_UART_INTERRUPT_DRIVEN=n +CONFIG_UART_ASYNC_API=y +CONFIG_SHELL_BACKEND_SERIAL_API_ASYNC=y + +# For debugging purposes, enable GPIO shell commands. +CONFIG_GPIO=y +CONFIG_GPIO_SHELL=y diff --git a/samples/sm_ppp_shell/boards/nrf54l15dk_nrf54l15_cpuapp.overlay b/samples/sm_ppp_shell/boards/nrf54l15dk_nrf54l15_cpuapp.overlay new file mode 100644 index 00000000..ff077173 --- /dev/null +++ b/samples/sm_ppp_shell/boards/nrf54l15dk_nrf54l15_cpuapp.overlay @@ -0,0 +1,51 @@ +/* + * Copyright (c) 2025 Nordic Semiconductor ASA + * + * SPDX-License-Identifier: LicenseRef-Nordic-5-Clause + */ + + +/* + * See nRF54L15DK GPIO documentation from + * https://docs.nordicsemi.com/bundle/ug_nrf54l15_dk/page/UG/nRF54L15_DK/hw_desription/connector_if.html + * + * UART0 is used for Serial Modem communication and UART1 is used for console/shell. + * + * Note: Disable VCOM0 from Board Configurator to release UART0 for Serial Modem. + * + * UART0 located on the P0 connector is the "uart30" instance in the device tree. + * UART1 is "uart20" in the device tree and it is routed to the VCOM1 on the interface chip. + * RING and DTR signals are located on P1 connector. + */ + +/ { + chosen { + /* Switch console to uart20 */ + zephyr,console = &uart20; + zephyr,shell-uart = &uart20; + }; +}; + +/* Zephyr modem UART <-> nRF91 Serial Modem UART */ +&uart30 { + status = "okay"; + current-speed = <115200>; + hw-flow-control; + zephyr,pm-device-runtime-auto; + + /* Nordic nRF91 Serial Modem configuration */ + modem: modem { + compatible = "nordic,nrf91-slm"; + status = "okay"; + mdm-ring-gpios = <&gpio1 12 (GPIO_ACTIVE_LOW | GPIO_PULL_UP)>; + mdm-dtr-gpios = <&gpio1 11 GPIO_ACTIVE_LOW>; + zephyr,pm-device-runtime-auto; + cmux-enable-runtime-power-save; + cmux-close-pipe-on-power-save; + cmux-idle-timeout-ms = <5000>; + }; +}; + +&gpio1 { + status = "okay"; +}; diff --git a/samples/sm_ppp_shell/boards/nrf54l15dk_nrf54l15_cpuapp_ns.conf b/samples/sm_ppp_shell/boards/nrf54l15dk_nrf54l15_cpuapp_ns.conf new file mode 100644 index 00000000..b0e984d4 --- /dev/null +++ b/samples/sm_ppp_shell/boards/nrf54l15dk_nrf54l15_cpuapp_ns.conf @@ -0,0 +1,17 @@ +# +# Copyright (c) 2025 Nordic Semiconductor ASA +# +# SPDX-License-Identifier: LicenseRef-Nordic-5-Clause +# + +# Use UART async API with PM_RUNTIME. +CONFIG_UART_INTERRUPT_DRIVEN=n +CONFIG_UART_ASYNC_API=y +CONFIG_SHELL_BACKEND_SERIAL_API_ASYNC=y + +# For debugging purposes, enable GPIO shell commands. +CONFIG_GPIO=y +CONFIG_GPIO_SHELL=y + +# When building for /NS, silence TFM logs to avoid conflicts with modem UART. +CONFIG_TFM_LOG_LEVEL_SILENCE=y diff --git a/samples/sm_ppp_shell/boards/nrf54l15dk_nrf54l15_cpuapp_ns.overlay b/samples/sm_ppp_shell/boards/nrf54l15dk_nrf54l15_cpuapp_ns.overlay new file mode 100644 index 00000000..ff077173 --- /dev/null +++ b/samples/sm_ppp_shell/boards/nrf54l15dk_nrf54l15_cpuapp_ns.overlay @@ -0,0 +1,51 @@ +/* + * Copyright (c) 2025 Nordic Semiconductor ASA + * + * SPDX-License-Identifier: LicenseRef-Nordic-5-Clause + */ + + +/* + * See nRF54L15DK GPIO documentation from + * https://docs.nordicsemi.com/bundle/ug_nrf54l15_dk/page/UG/nRF54L15_DK/hw_desription/connector_if.html + * + * UART0 is used for Serial Modem communication and UART1 is used for console/shell. + * + * Note: Disable VCOM0 from Board Configurator to release UART0 for Serial Modem. + * + * UART0 located on the P0 connector is the "uart30" instance in the device tree. + * UART1 is "uart20" in the device tree and it is routed to the VCOM1 on the interface chip. + * RING and DTR signals are located on P1 connector. + */ + +/ { + chosen { + /* Switch console to uart20 */ + zephyr,console = &uart20; + zephyr,shell-uart = &uart20; + }; +}; + +/* Zephyr modem UART <-> nRF91 Serial Modem UART */ +&uart30 { + status = "okay"; + current-speed = <115200>; + hw-flow-control; + zephyr,pm-device-runtime-auto; + + /* Nordic nRF91 Serial Modem configuration */ + modem: modem { + compatible = "nordic,nrf91-slm"; + status = "okay"; + mdm-ring-gpios = <&gpio1 12 (GPIO_ACTIVE_LOW | GPIO_PULL_UP)>; + mdm-dtr-gpios = <&gpio1 11 GPIO_ACTIVE_LOW>; + zephyr,pm-device-runtime-auto; + cmux-enable-runtime-power-save; + cmux-close-pipe-on-power-save; + cmux-idle-timeout-ms = <5000>; + }; +}; + +&gpio1 { + status = "okay"; +}; diff --git a/samples/sm_ppp_shell/prj.conf b/samples/sm_ppp_shell/prj.conf new file mode 100644 index 00000000..cef9f5e3 --- /dev/null +++ b/samples/sm_ppp_shell/prj.conf @@ -0,0 +1,59 @@ +# +# Copyright (c) 2025 Nordic Semiconductor ASA +# +# SPDX-License-Identifier: LicenseRef-Nordic-5-Clause +# + +# Networking +CONFIG_NETWORKING=y +CONFIG_NET_NATIVE=y +CONFIG_NET_L2_PPP=y +CONFIG_NET_L2_ETHERNET=n +CONFIG_NET_IPV4=y +CONFIG_NET_IPV6=y +CONFIG_NET_UDP=y +CONFIG_NET_TCP=y +CONFIG_NET_SOCKETS=y +CONFIG_NET_CONTEXT_RCVTIMEO=y +CONFIG_ZVFS_POLL_MAX=20 +CONFIG_ZVFS_OPEN_MAX=20 +CONFIG_POSIX_API=y +CONFIG_TEST_RANDOM_GENERATOR=y +CONFIG_NET_ZPERF=y +CONFIG_NET_PKT_RX_COUNT=40 +CONFIG_NET_PKT_TX_COUNT=40 +CONFIG_NET_BUF_RX_COUNT=80 +CONFIG_NET_BUF_TX_COUNT=80 +CONFIG_NET_BUF_DATA_SIZE=256 + +# DNS +CONFIG_DNS_RESOLVER=y +CONFIG_DNS_RESOLVER_MAX_SERVERS=4 +CONFIG_NET_L2_PPP_OPTION_DNS_USE=y + +# Network management +CONFIG_NET_MGMT=y +CONFIG_NET_MGMT_EVENT=y +CONFIG_NET_CONNECTION_MANAGER=y + +# Modem driver +CONFIG_MODEM=y +CONFIG_MODEM_CELLULAR=y +CONFIG_PM_DEVICE=y +CONFIG_PM_DEVICE_RUNTIME=y +CONFIG_PM_DEVICE_RUNTIME_USE_DEDICATED_WQ=y +CONFIG_MODEM_CMUX_MTU=127 +CONFIG_MODEM_CMUX_WORK_BUFFER_SIZE_EXTRA=532 +CONFIG_MODEM_CELLULAR_UART_BUFFER_SIZES=532 + +# Shell utilities +CONFIG_SHELL=y +CONFIG_NET_SHELL=y +CONFIG_PM_DEVICE_SHELL=y +CONFIG_NET_MGMT_EVENT_MONITOR=y +CONFIG_NET_MGMT_EVENT_MONITOR_AUTO_START=y + +# Logging +CONFIG_LOG=y +CONFIG_MODEM_LOG_LEVEL_DBG=y +CONFIG_MODEM_CMUX_LOG_LEVEL_DBG=y diff --git a/samples/sm_ppp_shell/sample.yaml b/samples/sm_ppp_shell/sample.yaml new file mode 100644 index 00000000..dd41e3b5 --- /dev/null +++ b/samples/sm_ppp_shell/sample.yaml @@ -0,0 +1,13 @@ +sample: + description: Serial Modem PPP example with shell interface + name: PPP shell +tests: + sample.sm_ppp_shell: + sysbuild: true + build_only: true + platform_allow: + - nrf54l15dk/nrf54l15/cpuapp + - nrf54l15dk/nrf54l15/cpuapp/ns + - native_sim + integration_platforms: + - nrf54l15dk/nrf54l15/cpuapp diff --git a/samples/sm_ppp_shell/src/main.c b/samples/sm_ppp_shell/src/main.c new file mode 100644 index 00000000..54f99a54 --- /dev/null +++ b/samples/sm_ppp_shell/src/main.c @@ -0,0 +1,10 @@ +/* + * Copyright (c) 2025 Nordic Semiconductor ASA + * + * SPDX-License-Identifier: LicenseRef-Nordic-5-Clause + */ + +int main(void) +{ + return 0; +}