DTR/RI virtual UART implementation

This is very much work in progress. Draft created, so that we can
discuss the approach.

Terms:

Data Terminal Equipment (DTE), AKA. host.
Data Communication Equipment (DCE), AKA. SLM.
Data Terminal Ready (DTR)
Ring Indicate (RI)

DTR operation:

When DTE is ready to communicate with DCE, it resumes it's UART,
enables RX, sets DTR low and waits for DTC to activate before
sending possibly pending TX data.

When DCE notices DTR down, it resumes UART, enables RX and sends
any possibly pending TX data.

When DTE wants to stop communicating with DCE, it sets DTR UP,
aborts possible TX, disables RX and suspends UART.

When DCE notices DTR up, it aborts possible TX, disables RX and
suspends UART.

RI operation:

When DCE observes DTR up and it needs to send data, it sets RI
up to notify DTE.

When DTE notices RI up, it initializes communication with DCE.

Application integration:

uart_rx_enable is used as indicator that application is ready.
It can also be used by DTE, together with uart_rx_disable, to
manage the state of the UART's.

UART_RX_BUF_REQUEST is sent by virtual UART to application to
request a buffer. This means that we want to communicate, so
DCE received DTR down or DTE received RI.

uart_tx causes DCE to send RI. For DTE, it starts communication
with DCE.

Author: MarkusLassila

applications/serial_lte_modem/boards/nrf9151dk_nrf9151_ns.conf

@@ -9,7 +9,7 @@
 # set here will take precedence if they are present in both files.
 
 # When working with PC terminal, unmask the following config.
-CONFIG_SLM_POWER_PIN=8
+CONFIG_SLM_POWER_PIN=-1
 CONFIG_SLM_INDICATE_PIN=0
 
 # When working with external MCU, unmask the following config.

applications/serial_lte_modem/boards/nrf9151dk_nrf9151_ns.overlay

@@ -6,13 +6,51 @@
 
  / {
 	chosen {
-		ncs,slm-uart = &uart0;
+		ncs,slm-uart = &dtr_uart;
 	};
 };
 
+/*
+/ {
+	aliases {
+		/delete-property/ sw0;
+		/delete-property/ mcuboot-button0;
+	};
+};
+/delete-node/ &button0;
+*/
+
+/* DTR with DK */
+/*
 &uart0 {
 	status = "okay";
 	hw-flow-control;
+
+	lpuart: nrf-sw-lpuart {
+		compatible = "nordic,nrf-sw-lpuart";
+		dtr-pin = <8>;
+		dtr-pin-toggle;
+		dtr-pin-debounce = <50>;
+		ri-pin = <0>;
+		status = "okay";
+	};
+};
+*/
+
+/* DTR with external MCU */
+&uart1 {
+	status = "okay";
+	hw-flow-control;
+
+	dtr_uart: nrf-sw-dtr-uart {
+		compatible = "nordic,nrf-sw-dtr-uart";
+		dtr-pin = <31>;
+		ri-pin = <30>;
+		status = "okay";
+	};
+	pinctrl-0 = <&uart2_default_alt>;
+	pinctrl-1 = <&uart2_sleep_alt>;
+	pinctrl-names = "default", "sleep";
 };
 
 &uart2 {

applications/serial_lte_modem/prj.conf

@@ -15,14 +15,14 @@ CONFIG_REBOOT=y
 CONFIG_EVENTFD=y
 
 # Segger RTT
-CONFIG_USE_SEGGER_RTT=y
+CONFIG_USE_SEGGER_RTT=n
 # Where console messages (printk) are output.
 # By itself, SLM does not output any.
-CONFIG_RTT_CONSOLE=y
-CONFIG_UART_CONSOLE=n
+CONFIG_RTT_CONSOLE=n
+CONFIG_UART_CONSOLE=y
 # Where SLM logs are output.
-CONFIG_LOG_BACKEND_RTT=y
-CONFIG_LOG_BACKEND_UART=n
+CONFIG_LOG_BACKEND_RTT=n
+CONFIG_LOG_BACKEND_UART=y
 # Increase the buffer so that all SLM boot logs fit into the buffer.
 # Because J-Link RTT Viewer has to be connected after the bootup,
 # only logs that fit into the buffer are shown. This is especially useful in showing
@@ -133,7 +133,11 @@ CONFIG_SLM_EXTERNAL_XTAL=n
 #CONFIG_SLM_LOG_LEVEL_DBG=y
 #CONFIG_LOG_PRINTK=n
 #CONFIG_LOG_MODE_IMMEDIATE=y
+CONFIG_DEBUG_OPTIMIZATIONS=y
 
 # For using external GNSS antenna
 #CONFIG_MODEM_ANTENNA=y
 #CONFIG_MODEM_ANTENNA_GNSS_EXTERNAL=y
+
+CONFIG_NRF_SW_DTR_UART=y
+CONFIG_NRF_SW_DTR_UART_LOG_LEVEL_DBG=y

applications/serial_lte_modem/src/slm_at_commands.c

@@ -199,7 +199,6 @@ static int handle_at_shutdown(enum at_parser_cmd_type cmd_type, struct at_parser
 
 FUNC_NORETURN void slm_reset(void)
 {
-	slm_at_host_uninit();
 	slm_power_off_modem();
 	LOG_PANIC();
 	sys_reboot(SYS_REBOOT_COLD);
@@ -212,6 +211,7 @@ static int handle_at_reset(enum at_parser_cmd_type cmd_type, struct at_parser *,
 		return -EINVAL;
 	}
 
+	slm_at_host_uninit();
 	final_call(slm_reset);
 	return 0;
 }

applications/serial_lte_modem/src/slm_at_host.c

@@ -446,7 +446,7 @@ static void format_final_result(char *buf, size_t buf_len, size_t buf_max_len)
 }
 
 static int slm_at_send_indicate(const uint8_t *data, size_t len,
-				bool print_full_debug, bool indicate)
+				bool print_full_debug, bool)
 {
 	int ret;
 
@@ -455,15 +455,6 @@ static int slm_at_send_indicate(const uint8_t *data, size_t len,
 		return -EINTR;
 	}
 
-	if (indicate) {
-		enum pm_device_state state = PM_DEVICE_STATE_OFF;
-
-		pm_device_state_get(slm_uart_dev, &state);
-		if (state != PM_DEVICE_STATE_ACTIVE) {
-			slm_ctrl_pin_indicate();
-		}
-	}
-
 	ret = slm_tx_write(data, len);
 	if (!ret) {
 		LOG_HEXDUMP_DBG(data, print_full_debug ? len : MIN(HEXDUMP_LIMIT, len), "TX");
@@ -1019,7 +1010,7 @@ void slm_at_host_uninit(void)
 
 	slm_at_uninit();
 
-	at_host_power_off(true);
+	// at_host_power_off(true); MARKUS TODO
 
 	LOG_DBG("at_host uninit done");
 }

applications/serial_lte_modem/src/slm_ppp.c

@@ -705,7 +705,7 @@ static void ppp_data_passing_thread(void*, void*, void*)
 {
 	const size_t mtu = net_if_get_mtu(ppp_iface);
 	struct zsock_pollfd fds[PPP_FDS_COUNT];
-	enum pm_device_state state = PM_DEVICE_STATE_OFF;
+	// enum pm_device_state state = PM_DEVICE_STATE_OFF;
 
 	for (size_t i = 0; i != ARRAY_SIZE(fds); ++i) {
 		fds[i].fd = ppp_fds[i];
@@ -747,11 +747,11 @@ static void ppp_data_passing_thread(void*, void*, void*)
 
 			/* When DL data is received from the network, check if UART is suspended */
 			if (src == MODEM_FD_IDX) {
-				pm_device_state_get(ppp_uart_dev, &state);
-				if (state != PM_DEVICE_STATE_ACTIVE) {
-					LOG_DBG("PPP data received but UART not active");
-					slm_ctrl_pin_indicate();
-				}
+				// pm_device_state_get(ppp_uart_dev, &state);
+				// if (state != PM_DEVICE_STATE_ACTIVE) {
+				// 	LOG_DBG("PPP data received but UART not active");
+				// 	// slm_ctrl_pin_indicate();
+				// }
 			}
 			const ssize_t len =
 				zsock_recv(fds[src].fd, ppp_data_buf, mtu, ZSOCK_MSG_DONTWAIT);

applications/serial_lte_modem/src/slm_uart_handler.c

@@ -9,11 +9,14 @@
 #include <zephyr/drivers/uart.h>
 #include <hal/nrf_uarte.h>
 #include <hal/nrf_gpio.h>
+#include <assert.h>
 #include <zephyr/sys/ring_buffer.h>
 #include <zephyr/pm/device.h>
 #include <zephyr/modem/pipe.h>
 #include "slm_uart_handler.h"
 #include "slm_at_host.h"
+#include <hal/nrf_regulators.h>
+#include <zephyr/sys/reboot.h>
 
 #include <zephyr/logging/log.h>
 LOG_MODULE_REGISTER(slm_uart_handler, CONFIG_SLM_LOG_LEVEL);
@@ -27,6 +30,7 @@ const struct device *const slm_uart_dev = DEVICE_DT_GET(DT_CHOSEN(ncs_slm_uart))
 uint32_t slm_uart_baudrate;
 
 static struct k_work_delayable rx_process_work;
+static struct k_work sleep_work;
 
 struct rx_buf_t {
 	atomic_t ref_counter;
@@ -279,16 +283,12 @@ static int tx_start(void)
 	uint8_t *buf;
 	size_t len;
 	int err;
-	enum pm_device_state state = PM_DEVICE_STATE_OFF;
+	// enum pm_device_state state = PM_DEVICE_STATE_OFF;
 
-	if (!atomic_test_bit(&uart_state, SLM_TX_ENABLED_BIT)) {
-		return -EAGAIN;
-	}
-
-	pm_device_state_get(slm_uart_dev, &state);
-	if (state != PM_DEVICE_STATE_ACTIVE) {
-		return 1;
-	}
+	// pm_device_state_get(slm_uart_dev, &state);
+	// if (state != PM_DEVICE_STATE_ACTIVE) {
+	// 	return 1;
+	// }
 
 	len = ring_buf_get_claim(&tx_buf, &buf, ring_buf_capacity_get(&tx_buf));
 	err = uart_tx(slm_uart_dev, buf, len, SYS_FOREVER_US);
@@ -328,6 +328,7 @@ static void uart_callback(const struct device *dev, struct uart_event *evt, void
 	struct rx_buf_t *buf;
 	struct rx_event_t rx_event;
 	int err;
+	static bool hwfc_active;
 
 	ARG_UNUSED(dev);
 	ARG_UNUSED(user_data);
@@ -360,17 +361,20 @@ static void uart_callback(const struct device *dev, struct uart_event *evt, void
 		(void)k_work_submit((struct k_work *)&rx_process_work);
 		break;
 	case UART_RX_BUF_REQUEST:
+		hwfc_active = false;
 		if (k_msgq_num_free_get(&rx_event_queue) < UART_RX_EVENT_COUNT_FOR_BUF) {
 			LOG_WRN("Disabling UART RX: No event space.");
 			break;
 		}
 		buf = rx_buf_alloc();
 		if (!buf) {
+			hwfc_active = true;
 			LOG_WRN("Disabling UART RX: No free buffers.");
 			break;
 		}
 		err = uart_rx_buf_rsp(slm_uart_dev, buf->buf, sizeof(buf->buf));
 		if (err) {
+			hwfc_active = true;
 			LOG_WRN("Disabling UART RX: %d", err);
 			rx_buf_unref(buf);
 		}
@@ -381,8 +385,15 @@ static void uart_callback(const struct device *dev, struct uart_event *evt, void
 		}
 		break;
 	case UART_RX_DISABLED:
+		LOG_INF("UART RX disabled");
 		atomic_clear_bit(&uart_state, SLM_RX_ENABLED_BIT);
-		k_work_submit((struct k_work *)&rx_process_work);
+		if (hwfc_active) {
+			LOG_INF("UART RX disabled due to flow control");
+			k_work_submit((struct k_work *)&rx_process_work);
+		}
+		// MARKUS TODO: Whether we shutdown or go to sleep should
+		// be configurable with AT-commands.
+		// (void)k_work_submit((struct k_work *)&sleep_work);
 		break;
 	default:
 		break;
@@ -445,6 +456,35 @@ static int slm_uart_tx_write(const uint8_t *data, size_t len)
 	return 0;
 }
 
+static void sleep_work_fn(struct k_work *work)
+{
+	ARG_UNUSED(work);
+
+	// MARKUS TODO: Some of the cleanup code sends UART responses. Those should be handled properly.
+	// This is a problem with having the virtual uart driver. The API between that and the SLM is
+	// the default UART API, which does not allow for us to react to DTR before closing the UART.
+	//
+	// It is possible to remove the UART responses in cleanup code. But it would be better to have them.
+
+	slm_at_host_uninit();
+
+	/* Only power off the modem if it has not been put
+	 * in flight mode to allow reducing NVM wear.
+	 */
+	// if (!slm_is_modem_functional_mode(LTE_LC_FUNC_MODE_OFFLINE)) {
+	// 	slm_power_off_modem();
+	// }
+
+	LOG_INF("Entering sleep.");
+	// LOG_PANIC();
+	// nrf_gpio_cfg_sense_set(CONFIG_SLM_POWER_PIN, NRF_GPIO_PIN_SENSE_LOW);
+
+	k_sleep(K_MSEC(100));
+
+	nrf_regulators_system_off(NRF_REGULATORS_NS);
+	assert(false);
+}
+
 int slm_tx_write(const uint8_t *data, size_t len)
 {
 #if SLM_PIPE
@@ -505,6 +545,7 @@ int slm_uart_handler_enable(void)
 	}
 
 	k_work_init_delayable(&rx_process_work, rx_process);
+	k_work_init(&sleep_work, sleep_work_fn);
 
 
 	/* Flush possibly pending data in case SLM was idle. */

drivers/serial/CMakeLists.txt

@@ -7,3 +7,4 @@
 zephyr_library_amend()
 zephyr_library_sources_ifdef(CONFIG_NRF_SW_LPUART uart_nrf_sw_lpuart.c)
 zephyr_library_sources_ifdef(CONFIG_IPC_UART uart_ipc.c)
+zephyr_library_sources_ifdef(CONFIG_NRF_SW_DTR_UART uart_nrf_sw_dtr_uart.c)

drivers/serial/Kconfig

@@ -6,3 +6,4 @@
 
 rsource "Kconfig.nrf_sw_lpuart"
 rsource "Kconfig.ipc"
+rsource "Kconfig.nrf_sw_dtr_uart"

drivers/serial/Kconfig.nrf_sw_dtr_uart

@@ -0,0 +1,42 @@
+# UART configuration
+
+# Copyright (c) 2025, Nordic Semiconductor ASA
+# SPDX-License-Identifier: LicenseRef-Nordic-5-Clause
+
+config NRF_SW_DTR_UART
+	bool "Low Power UART using REQ/RDY lines"
+	select GPIO
+	select UART_ASYNC_API
+	select RING_BUFFER
+	select PM_DEVICE
+	help
+	  Low power UART implements UART API and extends standard UART
+	  communication with 2 pins protocol for receiver wake up and flow control.
+
+if NRF_SW_DTR_UART
+
+config NRF_SW_DTR_UART_DTE_IDLE
+	bool "Enable DTE idle detection"
+	help
+	  When DTE has not sent or received data for NRF_SW_DTR_UART_DTE_IDLE_TIMEOUT_MS period,
+	  it will pull up DTR to force DCE to disable UART and then disables own UART.
+
+config NRF_SW_DTR_UART_DTE_IDLE_TIMEOUT_MS
+	int "DTE UART Idle Timeout (ms)"
+	default 1000
+	range 100 600000
+	help
+	  Idle detection timeout in milliseconds.
+
+config NRF_SW_DTR_UART_INIT_PRIORITY
+	int "Initialization priority"
+	default 45
+	help
+	  Initialization priority within POST_KERNEL level.
+
+
+module = NRF_SW_DTR_UART
+module-str = dtr uart
+source "subsys/logging/Kconfig.template.log_config"
+
+endif