[modem]: Support for URC handler in C-API -> v1.2.1

.github/workflows/modem__build-host-tests.yml

@@ -13,11 +13,8 @@ jobs:
     name: Build examples
     strategy:
       matrix:
-        idf_ver: ["latest", "release-v4.4", "release-v5.0", "release-v5.1", "release-v5.2", "release-v5.3"]
+        idf_ver: ["latest", "release-v5.0", "release-v5.1", "release-v5.2", "release-v5.3", "release-v5.4"]
         example: ["pppos_client", "modem_console", "modem_tcp_client", "ap_to_pppos", "simple_cmux_client"]
-        exclude:
-          - idf_ver: "release-v4.4"
-            example: modem_tcp_client
         include:
           - idf_ver: "release-v5.0"
             example: "simple_cmux_client"
@@ -26,13 +23,7 @@ jobs:
     runs-on: ubuntu-22.04
     container: espressif/idf:${{ matrix.idf_ver }}
     steps:
-      - name: Check out code (v3) # @v4 failed due to Node 20's requirement, incompatible with older IDF versions
-        if: matrix.idf_ver != 'latest' && matrix.idf_ver < 'release-v5.0'
-        uses: actions/checkout@v3
-        with:
-          path: protocols
-      - name: Check out code (v4)
-        if: matrix.idf_ver == 'latest' || matrix.idf_ver >= 'release-v5.0'
+      - name: Check out code
         uses: actions/checkout@v4
         with:
           path: protocols
@@ -53,7 +44,7 @@ jobs:
     name: Build tests
     strategy:
       matrix:
-        idf_ver: ["release-v5.0", "release-v5.1", "release-v5.2", "release-v5.3", "latest"]
+        idf_ver: ["release-v5.0", "release-v5.1", "release-v5.2", "release-v5.3", "release-v5.4", "latest"]
         test: ["target", "target_ota", "target_iperf"]
 
     runs-on: ubuntu-22.04

components/esp_modem/.cz.yaml

@@ -3,6 +3,6 @@ commitizen:
   bump_message: 'bump(modem): $current_version -> $new_version'
   pre_bump_hooks: python ../../ci/changelog.py esp_modem
   tag_format: modem-v$version
-  version: 1.2.0
+  version: 1.2.1
   version_files:
   - idf_component.yml

components/esp_modem/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## [1.2.1](https://github.com/espressif/esp-protocols/commits/modem-v1.2.1)
+
+### Bug Fixes
+
+- Use higher GPIO range to support new chips ([428fdbbd](https://github.com/espressif/esp-protocols/commit/428fdbbd), [#558](https://github.com/espressif/esp-protocols/issues/558))
+- Remove tests and support for IDFv4.4, added IDFv5.4 ([433a033f](https://github.com/espressif/esp-protocols/commit/433a033f))
+- Fix typo GENETIC -> GENERIC in mode types ([090b1ff8](https://github.com/espressif/esp-protocols/commit/090b1ff8), [#667](https://github.com/espressif/esp-protocols/issues/667))
+- Add support for URC handler into C-API ([295d99df](https://github.com/espressif/esp-protocols/commit/295d99df), [#180](https://github.com/espressif/esp-protocols/issues/180))
+
 ## [1.2.0](https://github.com/espressif/esp-protocols/commits/modem-v1.2.0)
 
 ### Features

components/esp_modem/examples/ap_to_pppos/README.md

@@ -15,7 +15,3 @@ By default, this example simply connects to the PPP server using a supported dev
 This example however, doesn't rely on sending specific AT commands, just the bare minimum to setup the cellular network.
 Thus, if the `EXAMPLE_USE_MINIMAL_DCE` option is enabled, we directly inherit from the `ModuleIf` and implement only the basic commands.
 Also, to demonstrate the dce_factory functionality, a new `NetDCE_Factory` is implemented for creating the network module and the DCE.
-
-### Supported IDF versions
-
-This example is only supported from `v4.2`, since is uses NAPT feature.

components/esp_modem/examples/linux_modem/README.md

@@ -17,7 +17,3 @@ over PPPoS, i.e. over the modem serial line.
 * Experiment with the network, after getting the IP from the modem device
     - directly in the code
     - in the system (need to set `tun` interface IP, dns servers, and routing the desired traffic over the tun interface)
-
-### Supported IDF versions
-
-This example (using the default CMake IDF build system) is only supported from `v4.4`, since is uses `idf.py`'s linux target.

components/esp_modem/examples/modem_console/README.md

@@ -25,9 +25,3 @@ USB example uses Quactel BG96 modem device. BG96 needs a positive pulse on its P
 This example supports USB modem hot-plugging and reconnection. There is one limitation coming from esp_console component:
 When esp_console REPL is being destroyed (after USB mode disconnection or after `exit` command), it will block on UART read.
 You must send a character to it (via idf.py monitor), so it unblocks and properly exits.
-
-### Supported IDF versions
-
-This example is only supported from `v4.2`, due to support of the console repl mode.
-
-USB example is supported from `v4.4`.

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

@@ -108,28 +108,28 @@ menu "Example Configuration"
         config EXAMPLE_MODEM_UART_TX_PIN
             int "TXD Pin Number"
             default 25
-            range 0 31
+            range 0 56
             help
                 Pin number of UART TX.
 
         config EXAMPLE_MODEM_UART_RX_PIN
             int "RXD Pin Number"
             default 26
-            range 0 31
+            range 0 56
             help
                 Pin number of UART RX.
 
         config EXAMPLE_MODEM_UART_RTS_PIN
             int "RTS Pin Number"
             default 27
-            range 0 31
+            range 0 56
             help
                 Pin number of UART RTS.
 
         config EXAMPLE_MODEM_UART_CTS_PIN
             int "CTS Pin Number"
             default 23
-            range 0 31
+            range 0 56
             help
                 Pin number of UART CTS.
 
@@ -179,7 +179,7 @@ menu "Example Configuration"
     config EXAMPLE_MODEM_PWRKEY_PIN
         int "PWRKEY Pin Number"
         default 18
-        range 0 31
+        range 0 56
         help
             Pin number connected to modem's power key pin.
 endmenu

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

@@ -20,14 +20,14 @@ menu "Example Configuration"
         config EXAMPLE_MODEM_UART_TX_PIN
             int "TXD Pin Number"
             default 4
-            range 0 31
+            range 0 56
             help
                 Pin number of UART TX.
 
         config EXAMPLE_MODEM_UART_RX_PIN
             int "RXD Pin Number"
             default 5
-            range 0 31
+            range 0 56
             help
                 Pin number of UART RX.
 
@@ -70,14 +70,14 @@ menu "Example Configuration"
     config EXAMPLE_MODEM_PWRKEY_PIN
         int "PWRKEY Pin Number"
         default 18
-        range 0 31
+        range 0 56
         help
             Pin number connected to modem's power key pin.
 
     config EXAMPLE_MODEM_STATUS_PIN
         int "STATUS Pin Number"
         default 19
-        range 0 31
+        range 0 56
         help
             Pin number connected to modem's status pin.
 

components/esp_modem/examples/modem_tcp_client/README.md

@@ -22,7 +22,3 @@ To enable this mode, please set `EXAMPLE_CUSTOM_TCP_TRANSPORT=y`
 This configuration could be used with any network library, which is connecting to a localhost endpoint instead of remote one. This example creates a localhost listener which basically mimics the remote endpoint by forwarding the traffic between the library and the TCP/socket layer of the modem (which is already secure if the TLS is used in the network library)
 
 ![with localhost listener](at_client_localhost.png)
-
-### Supported IDF versions
-
-This example is supported from IDF `v5.0`.

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

@@ -30,28 +30,28 @@ menu "Example Configuration"
         config EXAMPLE_MODEM_UART_TX_PIN
             int "TXD Pin Number"
             default 25
-            range 0 31
+            range 0 56
             help
                 Pin number of UART TX.
 
         config EXAMPLE_MODEM_UART_RX_PIN
             int "RXD Pin Number"
             default 26
-            range 0 31
+            range 0 56
             help
                 Pin number of UART RX.
 
         config EXAMPLE_MODEM_UART_RTS_PIN
             int "RTS Pin Number"
             default 27
-            range 0 31
+            range 0 56
             help
                 Pin number of UART RTS.
 
         config EXAMPLE_MODEM_UART_CTS_PIN
             int "CTS Pin Number"
             default 23
-            range 0 31
+            range 0 56
             help
                 Pin number of UART CTS.
 

components/esp_modem/examples/pppos_client/README.md

@@ -18,9 +18,3 @@ For USB enabled targets (ESP32-S2, ESP32-S3, or ESP32-P4), it is possible to con
 USB example uses Quactel BG96 modem device. BG96 needs a positive pulse on its PWK pin to boot-up.
 
 This example supports USB modem hot-plugging and reconnection.
-
-### Supported IDF versions
-
-This example is only supported from `v4.1`, as this is the default dependency of `esp-modem` component.
-
-USB example is supported from `v4.4`.

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

@@ -100,28 +100,28 @@ menu "Example Configuration"
         config EXAMPLE_MODEM_UART_TX_PIN
             int "TXD Pin Number"
             default 25
-            range 0 31
+            range 0 56
             help
                 Pin number of UART TX.
 
         config EXAMPLE_MODEM_UART_RX_PIN
             int "RXD Pin Number"
             default 26
-            range 0 31
+            range 0 56
             help
                 Pin number of UART RX.
 
         config EXAMPLE_MODEM_UART_RTS_PIN
             int "RTS Pin Number"
             default 27
-            range 0 31
+            range 0 56
             help
                 Pin number of UART RTS.
 
         config EXAMPLE_MODEM_UART_CTS_PIN
             int "CTS Pin Number"
             default 23
-            range 0 31
+            range 0 56
             help
                 Pin number of UART CTS.
 

components/esp_modem/examples/simple_cmux_client/README.md

@@ -11,11 +11,3 @@ The example uses the following configuration options to demonstrate basic esp-mo
 * `EXAMPLE_NEED_SIM_PIN`: To unlock the SIM card with a PIN code if needed
 * `EXAMPLE_PERFORM_OTA`: To start simple OTA at the end of the example to exercise basic CMUX/modem networking. Please note that the option `CONFIG_UART_ISR_IN_IRAM` is not enabled automatically, so that buffer overflows are expected and CMUX/PPP and networking should recover.
 * `EXAMPLE_USE_VFS_TERM`: To demonstrate using an abstract file descriptor to talk to the device (instead of the UART driver directly). This option could be used when implementing a custom VFS driver.
-
-## About the esp_modem
-
-Please check the component [README](../../README.md)
-
-### Supported IDF versions
-
-This example is only supported from `v4.3`, since is uses an experimental `esp_event_cxx` component.

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

@@ -69,28 +69,28 @@ menu "Example Configuration"
         config EXAMPLE_MODEM_UART_TX_PIN
             int "TXD Pin Number"
             default 25
-            range 0 31
+            range 0 56
             help
                 Pin number of UART TX.
 
         config EXAMPLE_MODEM_UART_RX_PIN
             int "RXD Pin Number"
             default 26
-            range 0 31
+            range 0 56
             help
                 Pin number of UART RX.
 
         config EXAMPLE_MODEM_UART_RTS_PIN
             int "RTS Pin Number"
             default 27
-            range 0 31
+            range 0 56
             help
                 Pin number of UART RTS.
 
         config EXAMPLE_MODEM_UART_CTS_PIN
             int "CTS Pin Number"
             default 23
-            range 0 31
+            range 0 56
             help
                 Pin number of UART CTS.
     endmenu

components/esp_modem/idf_component.yml

@@ -1,4 +1,4 @@
-version: "1.2.0"
+version: "1.2.1"
 description: Library for communicating with cellular modems in command and data modes
 url: https://github.com/espressif/esp-protocols/tree/master/components/esp_modem
 issues: https://github.com/espressif/esp-protocols/issues

components/esp_modem/include/esp_modem_c_api_types.h

@@ -13,6 +13,10 @@
 extern "C" {
 #endif
 
+/*  Compatibility macro to be removed in v2.0
+ */
+#define ESP_MODEM_DCE_GENETIC ESP_MODEM_DCE_GENERIC
+
 typedef struct esp_modem_dce_wrap esp_modem_dce_t;
 
 typedef struct esp_modem_PdpContext_t {
@@ -47,7 +51,7 @@ typedef enum esp_modem_dce_mode {
  * @brief DCE devices: Enum list of supported devices
  */
 typedef enum esp_modem_dce_device {
-    ESP_MODEM_DCE_GENETIC,  /**< The most generic device */
+    ESP_MODEM_DCE_GENERIC,  /**< The most generic device */
     ESP_MODEM_DCE_SIM7600,
     ESP_MODEM_DCE_SIM7070,
     ESP_MODEM_DCE_SIM7000,
@@ -141,6 +145,21 @@ esp_err_t esp_modem_command(esp_modem_dce_t *dce, const char *command, esp_err_t
  */
 esp_err_t esp_modem_set_apn(esp_modem_dce_t *dce, const char *apn);
 
+#ifdef CONFIG_ESP_MODEM_URC_HANDLER
+/**
+ * @brief Sets a handler for unsolicited result codes (URCs) from the modem
+ *
+ * This function registers a callback that is triggered whenever an unsolicited
+ * result code (URC) is received from the modem. URCs are typically sent by the
+ * modem without a prior command to notify the host about certain events or status changes.
+ *
+ * @param dce Modem DCE handle
+ * @param got_line_cb Callback function which is called whenever a URC line is received
+ * @return ESP_OK on success, ESP_FAIL on failure
+ */
+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
+
 /**
  * @}
  */

components/esp_modem/include/esp_private/c_api_wrapper.hpp

@@ -44,7 +44,7 @@ inline dce_factory::ModemType convert_modem_enum(esp_modem_dce_device_t module)
     case ESP_MODEM_DCE_SIM800:
         return esp_modem::dce_factory::ModemType::SIM800;
     default:
-    case ESP_MODEM_DCE_GENETIC:
+    case ESP_MODEM_DCE_GENERIC:
         return esp_modem::dce_factory::ModemType::GenericModule;
     }
 }

components/esp_modem/src/esp_modem_c_api.cpp

@@ -60,7 +60,7 @@ extern "C" esp_modem_dce_t *esp_modem_new_dev(esp_modem_dce_device_t module, con
 
 extern "C" esp_modem_dce_t *esp_modem_new(const esp_modem_dte_config_t *dte_config, const esp_modem_dce_config_t *dce_config, esp_netif_t *netif)
 {
-    return esp_modem_new_dev(ESP_MODEM_DCE_GENETIC, dte_config, dce_config, netif);
+    return esp_modem_new_dev(ESP_MODEM_DCE_GENERIC, dte_config, dce_config, netif);
 }
 
 extern "C" void esp_modem_destroy(esp_modem_dce_t *dce_wrap)
@@ -451,3 +451,27 @@ extern "C" esp_err_t esp_modem_set_apn(esp_modem_dce_t *dce_wrap, const char *ap
     dce_wrap->dce->get_module()->configure_pdp_context(std::move(new_pdp));
     return ESP_OK;
 }
+
+#ifdef CONFIG_ESP_MODEM_URC_HANDLER
+extern "C" esp_err_t esp_modem_set_urc(esp_modem_dce_t *dce_wrap, esp_err_t(*got_line_fn)(uint8_t *data, size_t len))
+{
+    if (dce_wrap == nullptr || dce_wrap->dce == nullptr) {
+        return ESP_ERR_INVALID_ARG;
+    }
+    if (got_line_fn == nullptr) {
+        dce_wrap->dce->set_urc(nullptr);
+        return ESP_OK;
+    }
+    dce_wrap->dce->set_urc([got_line_fn](uint8_t *data, size_t len) {
+        switch (got_line_fn(data, len)) {
+        case ESP_OK:
+            return command_result::OK;
+        case ESP_FAIL:
+            return command_result::FAIL;
+        default:
+            return command_result::TIMEOUT;
+        }
+    });
+    return ESP_OK;
+}
+#endif

components/esp_modem/src/esp_modem_uart.cpp

@@ -72,6 +72,7 @@ class UartTerminal : public Terminal {
     {
         auto t = static_cast<UartTerminal *>(task_param);
         t->task();
+        t->task_handle.task_handle = nullptr;
         vTaskDelete(nullptr);
     }