lib: modem_slm: Rename "wakeup" config and API to "power pin"

Renamed CONFIG_MODEM_SLM_WAKEUP_PIN and CONFIG_MODEM_SLM_WAKEUP_TIME
to CONFIG_MODEM_SLM_POWER_PIN and CONFIG_MODEM_SLM_POWER_PIN_TIME,
respectively.
Renamed modem_slm_wake_up() function to modem_slm_power_pin_toggle().
These backwards incompatible changes are done because
wakeup pin is not just for wake up after PR #14112.

Jira: LRCS-87

Signed-off-by: Tommi Rantanen <[email protected]>

Author: trantanen

doc/nrf/libraries/modem/modem_slm.rst

@@ -16,7 +16,7 @@ Overview
 The Modem SLM library allows you to perform the following functions:
 
 * Manage the serial interface so that the application only decides which UART device to use and configures its DTS.
-* Manage the GPIO pins, with support for bidirectional indication and wakeup.
+* Manage the GPIO pins, with support for bidirectional indication and power pin.
 * Send modem or SLM proprietary AT commands, receive responses and notifications, similar to the :ref:`lib_at_host` library.
   Received AT responses or notifications can be parsed by the :ref:`at_parser_readme` library.
 * Send raw data in SLM data mode.
@@ -33,8 +33,8 @@ Configure the following Kconfig options to enable this library:
 
 * :kconfig:option:`CONFIG_MODEM_SLM` - Enables the Modem SLM library.
 * :kconfig:option:`CONFIG_MODEM_SLM_DMA_MAXLEN` - Configures UART RX EasyDMA buffer size, which is configured to 1024 bytes by default.
-* :kconfig:option:`CONFIG_MODEM_SLM_WAKEUP_PIN` - Configures the mandatory wake-up GPIO, which is not configured by default.
-* :kconfig:option:`CONFIG_MODEM_SLM_WAKEUP_TIME` - Sets the toggle time value in milliseconds for wake-up GPIO, by default 100 ms.
+* :kconfig:option:`CONFIG_MODEM_SLM_POWER_PIN` - Configures the mandatory power pin GPIO, which is not configured by default.
+* :kconfig:option:`CONFIG_MODEM_SLM_POWER_PIN_TIME` - Sets the toggle time value in milliseconds for power pin GPIO, by default 100 ms.
 
 Optionally configure the following Kconfig options based on need:
 

doc/nrf/releases_and_maturity/migration/migration_guide_3.0.rst

@@ -367,6 +367,17 @@ Download client
 
            err = downloader_deinit(&dl);
 
+Modem SLM
+---------
+
+.. toggle::
+
+   For applications and samples using the :ref:`lib_modem_slm` library:
+
+    * Replace the ``CONFIG_MODEM_SLM_WAKEUP_PIN`` Kconfig option with :kconfig:option:`CONFIG_MODEM_SLM_POWER_PIN`.
+    * Replace the ``CONFIG_MODEM_SLM_WAKEUP_TIME`` Kconfig option with :kconfig:option:`CONFIG_MODEM_SLM_POWER_PIN_TIME`.
+    * Replace the :c:func:`modem_slm_wake_up` function with :c:func:`modem_slm_power_pin_toggle`.
+
 Protocols
 =========
 

doc/nrf/releases_and_maturity/releases/release-notes-changelog.rst

@@ -976,6 +976,14 @@ Modem libraries
 
   * Deprecated the :c:func:`modem_info_type_get` function in favor of the :c:func:`modem_info_data_type_get` function.
 
+* :ref:`lib_modem_slm` library:
+
+  * Updated:
+
+    * By renaming the ``CONFIG_MODEM_SLM_WAKEUP_PIN`` and ``CONFIG_MODEM_SLM_WAKEUP_TIME`` Kconfig options to
+      :kconfig:option:`CONFIG_MODEM_SLM_POWER_PIN` and :kconfig:option:`CONFIG_MODEM_SLM_POWER_PIN_TIME`, respectively.
+    * By renaming the :c:func:`modem_slm_wake_up` function to :c:func:`modem_slm_power_pin_toggle`.
+
 Multiprotocol Service Layer libraries
 -------------------------------------
 

include/modem/modem_slm.h

@@ -59,7 +59,7 @@ typedef void (*slm_data_handler_t)(const uint8_t *data, size_t datalen);
 /**
  * @typedef slm_ind_handler_t
  *
- * Handler to handle MODEM_SLM_INDICATE_PIN signal from SLM.
+ * Handler to handle @kconfig{CONFIG_MODEM_SLM_INDICATE_PIN} signal from SLM.
  */
 typedef void (*slm_ind_handler_t)(void);
 
@@ -77,22 +77,26 @@ int modem_slm_init(slm_data_handler_t handler);
 int modem_slm_uninit(void);
 
 /**
- * @brief Register callback for MODEM_SLM_INDICATE_PIN indication
+ * @brief Register callback for @kconfig{CONFIG_MODEM_SLM_INDICATE_PIN} indication
  *
  * @param handler Pointer to a handler function of type @ref slm_ind_handler_t.
  * @param wakeup  Enable/disable System Off wakeup by GPIO Sense.
  *
  * @retval Zero    Success.
- * @retval -EFAULT if MODEM_SLM_INDICATE_PIN is not defined.
+ * @retval -EFAULT if @kconfig{CONFIG_MODEM_SLM_INDICATE_PIN} is not defined.
  */
 int modem_slm_register_ind(slm_ind_handler_t handler, bool wakeup);
 
 /**
- * @brief Wakeup nRF9160 SiP via MODEM_SLM_WAKEUP_PIN
+ * @brief Toggle power pin of the nRF91 Series device configured with
+ * @kconfig{CONFIG_MODEM_SLM_POWER_PIN}.
+ *
+ * The pin is enabled for the time specified in @kconfig{CONFIG_MODEM_SLM_POWER_PIN_TIME}
+ * and then disabled.
  *
  * @return Zero on success, non-zero otherwise.
  */
-int modem_slm_wake_up(void);
+int modem_slm_power_pin_toggle(void);
 
 /**
  * @brief Reset the RX function of the serial interface

lib/modem_slm/Kconfig

@@ -24,7 +24,7 @@ config MODEM_SLM_SHELL
 	bool "SLM Shell"
 	depends on SHELL
 	help
-	  Adds AT command capability to shell. The shell command is "slm"
+	  Adds AT command capability to shell. The shell command is "slm".
 
 choice
 	prompt "AT command terminator"
@@ -44,23 +44,23 @@ choice
 		bool "CR+LF Termination"
 endchoice
 
-config MODEM_SLM_WAKEUP_PIN
-	int "Wakeup pin"
+config MODEM_SLM_POWER_PIN
+	int "Power pin"
 	default -1
 	help
-	  Interface GPIO to wake up nRF9160 from sleep or exit SLM idle
+	  Interface GPIO to toggle power pin of the nRF91 Series device.
 
-config MODEM_SLM_WAKEUP_TIME
-	int "wakeup period"
+config MODEM_SLM_POWER_PIN_TIME
+	int "Power pin active time"
 	default 100
 	help
-	  GPIO active time in milliseconds. This setting specify the period length for the pin to be active
+	  GPIO active time in milliseconds. This setting specifies the period length for the pin to be active.
 
 config MODEM_SLM_INDICATE_PIN
 	int "Indicate pin"
 	default -1
 	help
-	  Interface GPIO pin used by SLM to indicate that data is available or an unexpected reset has occurred
+	  Interface GPIO pin used by SLM to indicate that data is available or an unexpected reset has occurred.
 
 module = MODEM_SLM
 module-str = Modem SLM

lib/modem_slm/modem_slm.c

@@ -15,7 +15,7 @@
 
 LOG_MODULE_REGISTER(mdm_slm, CONFIG_MODEM_SLM_LOG_LEVEL);
 
-BUILD_ASSERT(CONFIG_MODEM_SLM_WAKEUP_PIN >= 0, "Wake up pin not configured");
+BUILD_ASSERT(CONFIG_MODEM_SLM_POWER_PIN >= 0, "Power pin not configured");
 
 #define UART_RX_BUF_NUM         2
 #define UART_RX_LEN             CONFIG_MODEM_SLM_DMA_MAXLEN
@@ -49,7 +49,7 @@ static const struct device *gpio_dev = DEVICE_DT_GET(DT_CHOSEN(ncs_slm_gpio));
 #else
 static const struct device *gpio_dev = DEVICE_DT_GET(DT_NODELABEL(gpio0));
 #endif
-static struct k_work_delayable gpio_wakeup_work;
+static struct k_work_delayable gpio_power_pin_disable_work;
 static slm_ind_handler_t ind_handler;
 
 #if defined(CONFIG_MODEM_SLM_SHELL)
@@ -111,17 +111,17 @@ static void indicate_pin_disable(void)
 #endif
 }
 
-static void gpio_wakeup_wk(struct k_work *work)
+static void gpio_power_pin_disable_work_fn(struct k_work *work)
 {
 	ARG_UNUSED(work);
 
-	if (gpio_pin_set(gpio_dev, CONFIG_MODEM_SLM_WAKEUP_PIN, 0) != 0) {
+	if (gpio_pin_set(gpio_dev, CONFIG_MODEM_SLM_POWER_PIN, 0) != 0) {
 		LOG_WRN("GPIO set error");
 	}
 	/* When SLM is woken up, indicate pin must be enabled */
 	(void)indicate_pin_enable();
 
-	LOG_INF("Stop wake-up");
+	LOG_INF("Disable power pin");
 }
 
 static void slm_data_wk(struct k_work *work)
@@ -374,9 +374,9 @@ static void gpio_cb_func(const struct device *dev, struct gpio_callback *gpio_cb
 		return;
 	}
 
-	if (k_work_delayable_is_pending(&gpio_wakeup_work)) {
-		(void)k_work_cancel_delayable(&gpio_wakeup_work);
-		(void)gpio_pin_set(gpio_dev, CONFIG_MODEM_SLM_WAKEUP_PIN, 0);
+	if (k_work_delayable_is_pending(&gpio_power_pin_disable_work)) {
+		(void)k_work_cancel_delayable(&gpio_power_pin_disable_work);
+		(void)gpio_pin_set(gpio_dev, CONFIG_MODEM_SLM_POWER_PIN, 0);
 	} else {
 		/* Disable indicate pin so that callbacks doesn't keep on coming. */
 		indicate_pin_disable();
@@ -400,7 +400,7 @@ static int gpio_init(void)
 		return -ENODEV;
 	}
 
-	err = gpio_pin_configure(gpio_dev, CONFIG_MODEM_SLM_WAKEUP_PIN,
+	err = gpio_pin_configure(gpio_dev, CONFIG_MODEM_SLM_POWER_PIN,
 				 GPIO_OUTPUT_INACTIVE | GPIO_ACTIVE_LOW);
 	if (err) {
 		LOG_ERR("GPIO config error: %d", err);
@@ -437,7 +437,7 @@ int modem_slm_init(slm_data_handler_t handler)
 		return -EFAULT;
 	}
 
-	k_work_init_delayable(&gpio_wakeup_work, gpio_wakeup_wk);
+	k_work_init_delayable(&gpio_power_pin_disable_work, gpio_power_pin_disable_work_fn);
 	k_work_init(&slm_data_work, slm_data_wk);
 	k_work_init_delayable(&uart_recovery_work, uart_recovery_wk);
 
@@ -455,7 +455,7 @@ int modem_slm_uninit(void)
 	uart_rx_disable(uart_dev);
 	k_sleep(K_MSEC(10));
 
-	gpio_pin_configure(gpio_dev, CONFIG_MODEM_SLM_WAKEUP_PIN, GPIO_DISCONNECTED);
+	gpio_pin_configure(gpio_dev, CONFIG_MODEM_SLM_POWER_PIN, GPIO_DISCONNECTED);
 
 	indicate_pin_disable();
 
@@ -474,7 +474,7 @@ int modem_slm_register_ind(slm_ind_handler_t handler, bool wakeup)
 	if (wakeup) {
 		/*
 		 * Due to errata 4, Always configure PIN_CNF[n].INPUT before PIN_CNF[n].SENSE.
-		 * At this moment WAKEUP_PIN has already been configured as INPUT at init_gpio().
+		 * At this moment indicate pin has already been configured as INPUT at init_gpio().
 		 */
 		nrf_gpio_cfg_sense_set(CONFIG_MODEM_SLM_INDICATE_PIN, NRF_GPIO_PIN_SENSE_LOW);
 	}
@@ -485,21 +485,23 @@ int modem_slm_register_ind(slm_ind_handler_t handler, bool wakeup)
 #endif
 }
 
-int modem_slm_wake_up(void)
+int modem_slm_power_pin_toggle(void)
 {
 	int err;
 
-	if (k_work_delayable_is_pending(&gpio_wakeup_work)) {
+	if (k_work_delayable_is_pending(&gpio_power_pin_disable_work)) {
 		return 0;
 	}
 
-	LOG_INF("Start wake-up");
+	LOG_INF("Enable power pin");
 
-	err = gpio_pin_set(gpio_dev, CONFIG_MODEM_SLM_WAKEUP_PIN, 1);
+	err = gpio_pin_set(gpio_dev, CONFIG_MODEM_SLM_POWER_PIN, 1);
 	if (err) {
 		LOG_ERR("GPIO set error: %d", err);
 	} else {
-		k_work_reschedule(&gpio_wakeup_work, K_MSEC(CONFIG_MODEM_SLM_WAKEUP_TIME));
+		k_work_reschedule(
+			&gpio_power_pin_disable_work,
+			K_MSEC(CONFIG_MODEM_SLM_POWER_PIN_TIME));
 	}
 
 	return 0;
@@ -578,7 +580,7 @@ int modem_slm_shell_slmsh_powerpin(const struct shell *shell, size_t argc, char
 {
 	int err;
 
-	err = modem_slm_wake_up();
+	err = modem_slm_power_pin_toggle();
 	if (err) {
 		LOG_ERR("Failed to toggle power pin");
 	}
@@ -589,7 +591,7 @@ SHELL_CMD_REGISTER(slm, NULL, "Send AT commands to SLM device", modem_slm_shell)
 
 SHELL_STATIC_SUBCMD_SET_CREATE(
 	sub_slmsh,
-	SHELL_CMD(powerpin, NULL, "Toggle power pin configured with CONFIG_SLM_POWER_PIN",
+	SHELL_CMD(powerpin, NULL, "Toggle power pin configured with CONFIG_MODEM_SLM_POWER_PIN",
 		  modem_slm_shell_slmsh_powerpin),
 	SHELL_SUBCMD_SET_END
 );

samples/cellular/slm_shell/boards/nrf52840dk_nrf52840.conf

@@ -11,5 +11,5 @@
 CONFIG_NRFX_UARTE1=y
 CONFIG_UART_1_INTERRUPT_DRIVEN=n
 CONFIG_UART_1_ASYNC=y
-CONFIG_MODEM_SLM_WAKEUP_PIN=11
+CONFIG_MODEM_SLM_POWER_PIN=11
 CONFIG_MODEM_SLM_INDICATE_PIN=13

samples/cellular/slm_shell/boards/nrf5340dk_nrf5340_cpuapp.conf

@@ -11,5 +11,5 @@
 CONFIG_NRFX_UARTE2=y
 CONFIG_UART_2_INTERRUPT_DRIVEN=n
 CONFIG_UART_2_ASYNC=y
-CONFIG_MODEM_SLM_WAKEUP_PIN=23
+CONFIG_MODEM_SLM_POWER_PIN=23
 CONFIG_MODEM_SLM_INDICATE_PIN=28

samples/cellular/slm_shell/boards/nrf7002dk_nrf5340_cpuapp.conf

@@ -11,5 +11,5 @@
 CONFIG_NRFX_UARTE2=y
 CONFIG_UART_2_INTERRUPT_DRIVEN=n
 CONFIG_UART_2_ASYNC=y
-CONFIG_MODEM_SLM_WAKEUP_PIN=30
+CONFIG_MODEM_SLM_POWER_PIN=30
 CONFIG_MODEM_SLM_INDICATE_PIN=31

samples/cellular/slm_shell/src/main.c

@@ -32,7 +32,7 @@ void slm_shell_indication_handler(void)
 	int err;
 
 	LOG_INF("SLM indicate pin triggered");
-	err = modem_slm_wake_up();
+	err = modem_slm_power_pin_toggle();
 	if (err) {
 		LOG_ERR("Failed to toggle power pin");
 	}