Merge pull request #700 from david-cermak/feat/modem_pause_network

[modem]: Add support for pausing netif

components/esp_modem/Kconfig

@@ -85,4 +85,11 @@ menu "esp-modem"
             mode more robust for some devices (e.g. Quectel), but might cause
             trouble for other devices (e.g. SIMCOM).
 
+    config ESP_MODEM_ADD_DEBUG_LOGS
+        bool "Add UART Tx/Rx logs"
+        default n
+        help
+            If enabled, the library dumps all transmitted and received data.
+            This option is only used for debugging.
+
 endmenu

components/esp_modem/examples/modem_console/main/modem_console_main.cpp

@@ -385,6 +385,17 @@ extern "C" void app_main(void)
         return 0;
     });
 #endif
+    const ConsoleCommand PauseNetwork("pause_net", "toggle network pause", no_args, [&](ConsoleCommand * c) {
+        static int cnt = 0;
+        if (++cnt % 2) {
+            ESP_LOGI(TAG, "Pausing netif");
+            dce->pause_netif(true);
+        } else {
+            ESP_LOGI(TAG, "Unpausing netif");
+            dce->pause_netif(false);
+        }
+        return 0;
+    });
 
     const struct SetApn {
         SetApn(): apn(STR1, nullptr, nullptr, "<apn>", "APN (Access Point Name)") {}

components/esp_modem/examples/pppos_client/main/Kconfig.projbuild

@@ -201,4 +201,23 @@ menu "Example Configuration"
         help
             MQTT data message, which we publish and expect to receive.
 
+    config EXAMPLE_PAUSE_NETIF_TO_CHECK_SIGNAL
+        bool "Demonstrate netif pause"
+        default n
+        help
+            Set this to true to demonstrate network pausing.
+            If enabled, the example waits for an MQTT data, then temporarily
+            drops network to check signal quality, resumes networking and
+            publishes another MQTT message.
+            Connection to the MQTT broker should be kept.
+
+    config EXAMPLE_DETECT_MODE_BEFORE_CONNECT
+        bool "Detect mode before connect"
+        default n
+        help
+            Set this to true to demonstrate mode auto-detection.
+            If enabled, the example tries to recognize the actual mode.
+            If mode is detected correctly and it is not a command mode,
+            then the example switches to command mode.
+
 endmenu

components/esp_modem/examples/pppos_client/main/pppos_client_main.c

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2022-2023 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2022-2024 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Unlicense OR CC0-1.0
  */
@@ -34,6 +34,7 @@
 static const char *TAG = "pppos_example";
 static EventGroupHandle_t event_group = NULL;
 static const int CONNECT_BIT = BIT0;
+static const int DISCONNECT_BIT = BIT1;
 static const int GOT_DATA_BIT = BIT2;
 static const int USB_DISCONNECTED_BIT = BIT3; // Used only with USB DTE but we define it unconditionally, to avoid too many #ifdefs in the code
 
@@ -55,6 +56,7 @@ static void usb_terminal_error_handler(esp_modem_terminal_error_t err)
 }
 #define CHECK_USB_DISCONNECTION(event_group) \
 if ((xEventGroupGetBits(event_group) & USB_DISCONNECTED_BIT) == USB_DISCONNECTED_BIT) { \
+    ESP_LOGE(TAG, "USB_DISCONNECTED_BIT destroying modem dce");                                            \
     esp_modem_destroy(dce); \
     continue; \
 }
@@ -140,6 +142,7 @@ static void on_ip_event(void *arg, esp_event_base_t event_base,
         ESP_LOGI(TAG, "GOT ip event!!!");
     } else if (event_id == IP_EVENT_PPP_LOST_IP) {
         ESP_LOGI(TAG, "Modem Disconnect from PPP Server");
+        xEventGroupSetBits(event_group, DISCONNECT_BIT);
     } else if (event_id == IP_EVENT_GOT_IP6) {
         ESP_LOGI(TAG, "GOT IPv6 event!");
 
@@ -158,6 +161,7 @@ void app_main(void)
     ESP_ERROR_CHECK(esp_event_handler_register(NETIF_PPP_STATUS, ESP_EVENT_ANY_ID, &on_ppp_changed, NULL));
 
     /* Configure the PPP netif */
+    esp_err_t err;
     esp_modem_dce_config_t dce_config = ESP_MODEM_DCE_DEFAULT_CONFIG(CONFIG_EXAMPLE_MODEM_PPP_APN);
     esp_netif_config_t netif_ppp_config = ESP_NETIF_DEFAULT_PPP();
     esp_netif_t *esp_netif = esp_netif_new(&netif_ppp_config);
@@ -205,7 +209,7 @@ void app_main(void)
 #endif
     assert(dce);
     if (dte_config.uart_config.flow_control == ESP_MODEM_FLOW_CONTROL_HW) {
-        esp_err_t err = esp_modem_set_flow_control(dce, 2, 2);  //2/2 means HW Flow Control.
+        err = esp_modem_set_flow_control(dce, 2, 2);  //2/2 means HW Flow Control.
         if (err != ESP_OK) {
             ESP_LOGE(TAG, "Failed to set the set_flow_control mode");
             return;
@@ -246,7 +250,27 @@ void app_main(void)
 #error Invalid serial connection to modem.
 #endif
 
-    xEventGroupClearBits(event_group, CONNECT_BIT | GOT_DATA_BIT | USB_DISCONNECTED_BIT);
+#if CONFIG_EXAMPLE_DETECT_MODE_BEFORE_CONNECT
+    xEventGroupClearBits(event_group, CONNECT_BIT | GOT_DATA_BIT | USB_DISCONNECTED_BIT | DISCONNECT_BIT);
+
+    err = esp_modem_set_mode(dce, ESP_MODEM_MODE_DETECT);
+    if (err != ESP_OK) {
+        ESP_LOGE(TAG, "esp_modem_set_mode(ESP_MODEM_MODE_DETECT) failed with %d", err);
+        return;
+    }
+    esp_modem_dce_mode_t mode = esp_modem_get_mode(dce);
+    ESP_LOGI(TAG, "Mode detection completed: current mode is: %d", mode);
+    if (mode == ESP_MODEM_MODE_DATA) {  // set back to command mode
+        err = esp_modem_set_mode(dce, ESP_MODEM_MODE_COMMAND);
+        if (err != ESP_OK) {
+            ESP_LOGE(TAG, "esp_modem_set_mode(ESP_MODEM_MODE_COMMAND) failed with %d", err);
+            return;
+        }
+        ESP_LOGI(TAG, "Command mode restored");
+    }
+#endif // CONFIG_EXAMPLE_DETECT_MODE_BEFORE_CONNECT
+
+    xEventGroupClearBits(event_group, CONNECT_BIT | GOT_DATA_BIT | USB_DISCONNECTED_BIT | DISCONNECT_BIT);
 
     /* Run the modem demo app */
 #if CONFIG_EXAMPLE_NEED_SIM_PIN == 1
@@ -262,7 +286,7 @@ void app_main(void)
 #endif
 
     int rssi, ber;
-    esp_err_t err = esp_modem_get_signal_quality(dce, &rssi, &ber);
+    err = esp_modem_get_signal_quality(dce, &rssi, &ber);
     if (err != ESP_OK) {
         ESP_LOGE(TAG, "esp_modem_get_signal_quality failed with %d %s", err, esp_err_to_name(err));
         return;
@@ -301,22 +325,41 @@ void app_main(void)
     }
     /* Wait for IP address */
     ESP_LOGI(TAG, "Waiting for IP address");
-    xEventGroupWaitBits(event_group, CONNECT_BIT | USB_DISCONNECTED_BIT, pdFALSE, pdFALSE, portMAX_DELAY);
+    xEventGroupWaitBits(event_group, CONNECT_BIT | USB_DISCONNECTED_BIT | DISCONNECT_BIT, pdFALSE, pdFALSE,
+                        pdMS_TO_TICKS(60000));
     CHECK_USB_DISCONNECTION(event_group);
+    if ((xEventGroupGetBits(event_group) & CONNECT_BIT) != CONNECT_BIT) {
+        ESP_LOGW(TAG, "Modem not connected, switching back to the command mode");
+        err = esp_modem_set_mode(dce, ESP_MODEM_MODE_COMMAND);
+        if (err != ESP_OK) {
+            ESP_LOGE(TAG, "esp_modem_set_mode(ESP_MODEM_MODE_COMMAND) failed with %d", err);
+            return;
+        }
+        ESP_LOGI(TAG, "Command mode restored");
+        return;
+    }
 
     /* Config MQTT */
-#if ESP_IDF_VERSION >= ESP_IDF_VERSION_VAL(5, 0, 0)
     esp_mqtt_client_config_t mqtt_config = {
         .broker.address.uri = CONFIG_EXAMPLE_MQTT_BROKER_URI,
     };
-#else
-    esp_mqtt_client_config_t mqtt_config = {
-        .uri = CONFIG_EXAMPLE_MQTT_BROKER_URI,
-    };
-#endif
     esp_mqtt_client_handle_t mqtt_client = esp_mqtt_client_init(&mqtt_config);
     esp_mqtt_client_register_event(mqtt_client, ESP_EVENT_ANY_ID, mqtt_event_handler, NULL);
     esp_mqtt_client_start(mqtt_client);
+
+#if CONFIG_EXAMPLE_PAUSE_NETIF_TO_CHECK_SIGNAL
+    xEventGroupWaitBits(event_group, GOT_DATA_BIT, pdTRUE, pdFALSE, portMAX_DELAY);
+    esp_modem_pause_net(dce, true);
+    err = esp_modem_get_signal_quality(dce, &rssi, &ber);
+    if (err != ESP_OK) {
+        ESP_LOGE(TAG, "esp_modem_get_signal_quality failed with %d", err);
+        return;
+    }
+    ESP_LOGI(TAG, "Signal quality: rssi=%d, ber=%d", rssi, ber);
+    esp_modem_pause_net(dce, false);
+    esp_mqtt_client_publish(mqtt_client, CONFIG_EXAMPLE_MQTT_TEST_TOPIC, CONFIG_EXAMPLE_MQTT_TEST_DATA, 0, 0, 0);
+#endif // CONFIG_EXAMPLE_PAUSE_NETIF_TO_CHECK_SIGNAL
+
     ESP_LOGI(TAG, "Waiting for MQTT data");
     xEventGroupWaitBits(event_group, GOT_DATA_BIT | USB_DISCONNECTED_BIT, pdFALSE, pdFALSE, portMAX_DELAY);
     CHECK_USB_DISCONNECTION(event_group);

components/esp_modem/examples/pppos_client/pytest_pppos_client.py

@@ -12,7 +12,7 @@ def test_pppos_connect(dut):
       4. checks that the client cleanly disconnects
     """
     # Check the sequence of connecting, publishing, disconnecting
-    dut.expect('Modem Connect to PPP Server')
+    dut.expect('Modem Connect to PPP Server', timeout=90)
     # Check for MQTT connection and the data event
     dut.expect('MQTT_EVENT_CONNECTED')
     dut.expect('MQTT_EVENT_DATA')

components/esp_modem/examples/pppos_client/sdkconfig.ci.sim800_c3

@@ -11,5 +11,7 @@ CONFIG_EXAMPLE_MODEM_DEVICE_SIM800=y
 CONFIG_EXAMPLE_MODEM_DEVICE_BG96=n
 CONFIG_EXAMPLE_MODEM_PPP_APN="lpwa.vodafone.com"
 CONFIG_EXAMPLE_MQTT_TEST_TOPIC="/ci/esp-modem/pppos-client"
+CONFIG_EXAMPLE_PAUSE_NETIF_TO_CHECK_SIGNAL=y
 CONFIG_ESP_SYSTEM_PANIC_PRINT_HALT=y
 CONFIG_ESP32_PANIC_PRINT_HALT=y
+CONFIG_EXAMPLE_DETECT_MODE_BEFORE_CONNECT=y

components/esp_modem/examples/simple_cmux_client/sdkconfig.ci.sim800_cmux

@@ -16,3 +16,4 @@ CONFIG_COMPILER_CXX_EXCEPTIONS=y
 CONFIG_ESP_MAIN_TASK_STACK_SIZE=8192
 CONFIG_EXAMPLE_CLOSE_CMUX_AT_END=y
 CONFIG_EXAMPLE_MQTT_TEST_TOPIC="/ci/esp-modem/pppos-client"
+CONFIG_BROKER_URI="mqtt://mqtt.eclipseprojects.io"

components/esp_modem/include/cxx_include/esp_modem_dce.hpp

@@ -91,6 +91,11 @@ class DCE_T {
         return mode.set(dte.get(), device.get(), netif, m);
     }
 
+    modem_mode get_mode()
+    {
+        return mode.get();
+    }
+
     bool recover()
     {
         return dte->recover();
@@ -103,6 +108,29 @@ class DCE_T {
     }
 #endif
 
+    /**
+     * @brief Pauses/Unpauses network temporarily
+     * @param do_pause true to pause, false to unpause
+     * @param force true to ignore command failures and continue
+     * @return command_result of the underlying commands
+     */
+    command_result pause_netif(bool do_pause, bool force = false, int delay = 1000)
+    {
+        command_result result;
+        if (do_pause) {
+            netif.pause();
+            Task::Delay(delay); // Mandatory 1s pause before
+            dte->set_command_callbacks();
+            result = device->set_command_mode();
+        } else {
+            result = device->resume_data_mode();
+            if (result == command_result::OK || force) {
+                netif.resume();
+            }
+        }
+        return result;
+    }
+
 protected:
     std::shared_ptr<DTE> dte;
     std::shared_ptr<SpecificModule> device;

components/esp_modem/include/cxx_include/esp_modem_dte.hpp

@@ -145,6 +145,12 @@ class DTE : public CommandableIf {
      */
     bool recover();
 
+    /**
+     * @brief Set internal command callbacks to the underlying terminal.
+     * Here we capture command replies to be processed by supplied command callbacks in  struct command_cb.
+     */
+    void set_command_callbacks();
+
 protected:
     /**
      * @brief Allows for locking the DTE
@@ -204,12 +210,6 @@ class DTE : public CommandableIf {
     } inflatable;
 #endif // CONFIG_ESP_MODEM_USE_INFLATABLE_BUFFER_IF_NEEDED
 
-    /**
-     * @brief Set internal command callbacks to the underlying terminal.
-     * Here we capture command replies to be processed by supplied command callbacks in  struct command_cb.
-     */
-    void set_command_callbacks();
-
     /**
      * @brief This abstracts command callback processing and implements its locking, signaling of completion and timeouts.
      */

components/esp_modem/include/cxx_include/esp_modem_netif.hpp

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2021-2022 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2021-2024 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -54,6 +54,16 @@ class Netif {
      */
     void stop();
 
+    /**
+     * @brief Pause the network interface
+     */
+    void pause();
+
+    /**
+     * @brief Resume the network interface
+     */
+    void resume();
+
     void receive(uint8_t *data, size_t len);
 
 private:

components/esp_modem/include/esp_modem_c_api_types.h

@@ -45,6 +45,8 @@ typedef enum esp_modem_dce_mode {
     ESP_MODEM_MODE_CMUX_MANUAL_SWAP,    /**< Swap terminals in CMUX manual mode */
     ESP_MODEM_MODE_CMUX_MANUAL_DATA,    /**< Set DATA mode in CMUX manual mode */
     ESP_MODEM_MODE_CMUX_MANUAL_COMMAND, /**< Set COMMAND mode in CMUX manual mode */
+    ESP_MODEM_MODE_DETECT,              /**< Detect the mode and resume it (if sucessfully detected) */
+    ESP_MODEM_MODE_UNDEF,
 } esp_modem_dce_mode_t;
 
 /**
@@ -160,6 +162,18 @@ esp_err_t esp_modem_set_apn(esp_modem_dce_t *dce, const char *apn);
 esp_err_t esp_modem_set_urc(esp_modem_dce_t *dce, esp_err_t(*got_line_cb)(uint8_t *data, size_t len));
 #endif
 
+/**
+ * @brief This API provides support for temporarily pausing networking in order
+ * to send/receive AT commands and resume networking afterwards.
+ * @note This function does not switch modes, the modem is still in data mode.
+ *
+ * @param dce Modem DCE handle
+ * @param pause true to pause the network interface, false to resume networking
+ * @return ESP_OK on success
+ */
+esp_err_t esp_modem_pause_net(esp_modem_dce_t *dce, bool pause);
+
+esp_modem_dce_mode_t esp_modem_get_mode(esp_modem_dce_t *dce);
 /**
  * @}
  */