# ESP MODEM [![Component Registry](]( The `esp-modem` component is a managed component for `esp-idf` that is used for communication with GSM/LTE modems that support AT commands and PPP protocol as a network interface. ## Examples Get started with one of the examples: * `examples/pppos_client` -- simple client implemented in C * `examples/modem_console` -- C++ example implementing simple terminal console with DCE commands * `examples/ap_to_pppos` -- this example focuses on the network connectivity of the esp-modem and provides a WiFi AP that forwards packets (and uses NAT) to and from the PPPoS connection. * `examples/simple_cmux_client` -- this example sets up the CMUX mode to talk to the modem using AT commands with simultaneously maintaining active network connection. ## Documentation * Continue with esp-modem [brief overview]( * View the full [html documentation](


# Changelog ## [1.0.4]( ### Bug Fixes - Added USB runner with ESP32S2 with A7670 ([edeb936]( - Extend docs on AT client example ([1f2ceed]( - Fix pytest exclusion, gitignore, and changelog checks ([2696221]( - Fix DTE to post fragments to parsers for USB term ([1db1e15]( - Fix DUAL_MODE regression from cb6e03ac ([2aada0f]( - Fix AT client example to use custom AT processing ([1a5ba98](, [#352]( ## [1.0.3]( ### Bug Fixes - Fix to allow MSC frame (SIM800 CMUX) after v1.0.2 ([8d5947e](, [#366]( - Add CMUX example to target tests ([4f2ebaa]( ## [1.0.2]( ### Features - Add factory method for simple creation of custom DCEs ([4cf9e50]( - Support custom transport in AT TCP client example ([ae629ed]( ### Bug Fixes - Fix host test race with async read and d'structor ([c89d42f]( - More error handling in cmux protocol ([8edbac6]( - Fix netif to set PPP config in C++ way ([5287432]( - Fix vfs terminal not to reset read_cb() automatically ([25a35e2]( - Fix netif data race causing PPP startup delays ([c8c0507](, [#308]( - Added support for inflatable buffer ([cb6e03a](, [#272]( - Fix LoadProhibited after failed CMUX initialization (IDFGH-10845) ([60c87dd]( ## [1.0.1]( ### Bug Fixes - Support UART clean build with IDF v5.2 ([e620eb5]( - enable code coverage publishing to github pages ([4910e89]( - fix esp_modem build issue ([ab94566]( - Example to use 1.0.0 ([afb6930]( - Changelog to correctly pick references ([423e965]( ### Updated - docs(esp_modem): updated documents to show missed topics ([0534853]( - docs(common): improving documentation ([ca3fce0]( ## [1.0.0]( ### Major changes - Enable DTE to redefine on_read() and write(cmd) directly ([DTE to support sending and receiving raw data]( ### Features - Add mqtt example in AT-only mode ([7547267]( - DTE to support sending and receiving raw data ([bf114d3]( ### Bug Fixes - Changelog to correctly pick references ([c59e330]( - AT-only example: support MQTT over TLS on BG96 ([31d4323]( - AT-only example: initial adaptation to BG96 ([ceedcfc]( - warning in ap-2-pppos example when using lwip/napt ([bf32e45]( - trigger PR jobs based on labels ([13eca12]( - Reintroduce missing CHANGELOGs ([200cbb3](, [#235]( - Use default UART CLK source ([d0814bf](, [#241]( - run CI build job for all targets ([a089e0d]( ### Updated - Update examples for USB v1.1 ([610372f]( ## [0.1.28]( ### Updated - Dual DTE support ([01c26c8]( ## [0.1.27]( ### Updated - Return true from on_data callback in data mode ([44bae24]( ## [0.1.26]( ### Features - Added target test ([4314c78]( - Add support for manual CMUX operations ([ac5d438](, [#168]( ### Bug Fixes - Example to use variable mqtt topic/data ([8958d5e]( - Fix cmux client compilation issue ([f71192b]( - Exit data mode only after state change ([9a7bd90]( - Support AT with callback in C-API ([2180ab1](, [#143]( ### Updated - update(esp_modem): Bump component version to 0.1.26 ([05fff94](, [#213]( - Added the missing definition for the esp_modem_set_baud function (IDFGH-9181) (#209) ([0e215b1]( - CI: Added coverage analyzer for esp_modem host tests ([6b684ce]( - Update esp_modem_command_library.cpp ([5304a6e]( - Added badges with version of components to the respective README files ([e4c8a59]( - esp_modem/examples: Add an example to synchronise PSM sleep in Sim70XX modem and esp32. ([1ca1391]( ## [0.1.25]( ### Bug Fixes - Cleanup custom lib-commands and factory ([65c0e0e]( - Examples to configure MQTT Broker ([71a2388]( - Extend pppos example project config ([ebc36a3]( - Uart Terminal read_cb race ([a02bf05]( ### Updated - update(esp_modem): Bump component version ([f1ae14f]( - fix(esp_modem) Add example that reads GNSS info ([652314e]( - CI: fixing the files to be complient with pre-commit hooks ([945bd17]( - Quick fix esp_modem: Added modem_console commands for deep-sleep and modem PSM. ([cf504ec]( - fix(esp-modem) Make simple_cmux_client example configurable ([511ed54]( - Added modem_console commands for deep-sleep and modem PSM. ([85a2e25]( - ci: Compile esp_modem examples with USB support ([988b3f9]( - Expand PPPoS example with USB DTE ([53b5933]( - Allow USB DTE reconnection ([bf84ae9]( - Add ConsoleCommand destructor ([a89a0ab]( - esp_modem_get_gnss_power_mode (#136) ([fe536e4]( - remove unused Config Parameters ! ([55b4775]( ## [0.1.24]( ### Features - Make some CMUX params compile-time configurable ([25ac2d9]( ### Bug Fixes - CMUX to ignore MSC frames ([ce175df](, [#140]( - Fix CRLF endlines in examples ([07a347f]( - Console example to use configurable flow-ctrl ([d9c9681]( ### Updated - update(esp_modem): Bump component version ([9b48b0a]( - Allow error handler register in C ([62cb235]( ## [0.1.23]( ### Features - Add exit PPP in example ([290197c]( ### Updated - Move common C definitions in to separate header ([04c711f]( - Minor formatting fix and spelling ([accf924]( - extended the modem_console example. (#120) ([ef0e48a]( ## [0.1.22]( ### Bug Fixes - DTE command race of timeout vs reply's signal ([a871473](, [#110]( - Correct timeouts for certain commands ([1029078](, [#129]( - Make get_operator_name() return also ACT value ([0015e54](, [#128]( ### Updated - update(esp_modem): Bump component version ([187ef76]( ## [0.1.21]( ### Updated - Fix IDF version resolution ([d07237b]( - Fix format warnings ([98bf3ef](, [#79]( ## [0.1.20]( ### Bug Fixes - Correct exit of CMUX mode ([2099434](, [#103]( - Add filename/line info to exception message ([89e1bd2]( ### Updated - Expose set_error_cb method ([ae8479c]( ## [0.1.19]( ### Features - Add optional ACT to operator-name ([a286634](, [#80]( ### Bug Fixes - Add missing set_pdp_context() to C-API ([4980ac8]( ### Updated - updated package version to 0.1.19 ([469f953]( - CI: Fix build issues ([6e4e4fa]( - esp_err_to_name (IDFGH-7793) (#78) ([d1129f3]( ## [0.1.18]( ### Features - Add CMUX mode to C-API ([3fd4391](, [#41]( - Add support to CMUX exit ([a16aab6](, [#37]( ### Bug Fixes - Update ap2ppp example to recover network on disconnection ([a243d7e](, [#44]( - Implement movable unique_buffer to bundle data, size, ptr ([66e6d4c]( - DTE should own both command and data terminal ([f3ff98b]( - Update CMUX example to use CMUX mode automatically ([58a0b57]( - Improve PPP exit sequence ([1e0aefd](, [#47]( ### Updated - Ignore format warnings ([e8145fc]( - Allow to customize uart source_clk ([d723fb7]( - Add "at" api for custom commands ([0cf08fb]( ## [0.1.17]( ### Features - Bumped version number to 0.1.17 ([5addf9e]( ### Bug Fixes - Support 2 byte size packets ([128c0a2](, [#46]( - Correction of switching to CMUX ([503218b](, [#33]( ### Updated - Fix param description for get_operator_name() ([a661e51]( - Update: Removed stringstream to decrease static sizes ([3ced2d9]( - Update: Renamed list_in to be type-specific Update: Removed modem-specific comment ([ba88d7f]( - Update: Changed tests to coincide with new initial esp_modem mode ([4f3c429]( - typo ([52de8f1]( - Update: Removed duplicate power down function Add: gnss power mode function ([e98cf16]( - Update: Formatting ([be3d2ec]( - Add: Sim7600 extended support ([15ed885]( - Add: Support for SIM7000 modules ([0733ea8]( - Update: modem_mode::UNDEF initially ([15cbc9b]( - Add: sim7070 support ([bb7f198]( - Add: Expanded modem_command_library with more "standard" commands ([d3f7ea6]( - Fix DCE selection in ‘pppos_client’ example ([d191a72]( - Fix AT command in ‘set_data_mode_sim8xx()’ for SIM800 modem device ([cc0d527]( ## [0.1.16]( ### Updated - Extend modem_console example with USB DTE ([74040cf]( ## [0.1.15]( ### Updated - Fix IDFv5.0 include paths ([1f5eb39]( ## [0.1.14]( ### Bug Fixes - missing default statement in a switch in the modem_console example ([325a193]( - add virtual destructors to ModuleIf and CommandableIf ([face03e]( ### Updated - build: fix issue with passing cxx_std option, a common workaround ([745201b]( - add(esp_modem): Add unit test to check polymorphic delete ([e54b240]( - Implement esp_modem_sync for the C API ([8b3d420]( ## [0.1.13]( ### Bug Fixes - Update the test to exersise CBC parser ([d879e82]( - Fix battery status parse ([4f1d31f]( - Read module name with AT commands ([8417e23]( - linux port to work with lwip-2.1.2 ([8465b14]( ### Updated - Update(esp_modem): Bump component version ([2cb74cf]( ## [0.1.12]( ### Updated - Update FreeRTOS EventQueueHandle_t forward declaration ([5d9ad9c]( ## [0.1.11]( ### Updated - New version to publish to component registry ([9649876]( - Docs: Add links to GitHub pages ([cf990d1]( - Add missing AT commands to plain C-API ([5299b42]( - CI/Docs: Generate docs locally before uploading to registry ([2c21aa1]( - CI/Docs: Add jobs to deploy component docs ([b9ff1e4]( - Update Task handle and Event Group handle to match freertos v10.4.3 ([5888717]( - Examples: Fix print format for http_client() API ([01e2a9c]( - Examples: Fix build error when SIM needs no PIN ([c8c24ed]( - Examples: Use bigger 4M flash for OTA example ([b380ded]( ## [0.1.9]( ### Updated - Fix CMake3.5 build with no cxx_std_17 feature ([2a2d270]( ## [0.1.8]( ### Updated - 0.1.8: Update comonent version ([9dd1bd5]( - Add pre upload script to deploy the docs before component upload ([918db0d]( - Minor correction of the docs ([c1b1330]( - Examples/console: Remove unnecessary event-base check on IP handler ([fb7295e]( - Examples: Extend CMux client default stack size for the main task ([8236b3d]( - CMUX: Refactor the protocol decoder to multiple methods per cmux state ([fb6029b]( - Factory: Rename Builder class to Creator, since it's not 100% builder pattern ([6e34954]( - Formal updates per code review ([148a930]( - Docs: Update CMux collaboration diagram to resemble composite ([1fb9150]( - Applied astyle code formatting ([a61e9e2]( - Minor corrections per code review ([dc64f86]( - Bulk replace header guards to use ([3332c27]( - Host test fix: renamed Loopback inherited member ([84b0dcf]( - Update documentation and minor fixes ([e0e6585]( ## [0.1.7]( ### Updated - Update version to 0.1.7 -- support socket VFS ([28433de]( - Reworked decouple resources from the file system ([8f17a90]( - Make the component compatible with IDFv4.1, v4.2, v4.3 ([69ad3ea]( ## [0.1.6]( ### Updated - Bump the version and upload the component ([a67d749]( - Updated per review comments ([ab93c13]( ## [0.1.5]( ### Updated - Moved to component folder ([90641c8](

readme of ap_to_pppos example

# AP to PPPoS example ## Overview This example focuses on the networking part, enables forwarding packets between network interfaces. It creates a WiFi soft AP, which uses NAT to forward packets to and from the PPP network interface. ### Specific network DCE Note, that this example could use of a minimal Network DCE, defined in the `network_dce.cpp` file. Please set `EXAMPLE_USE_MINIMAL_DCE` to `y` in order to demonstrate this functionality. By default, this example simply connects to the PPP server using a supported device with C-API modem interface. 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.

readme of linux_modem example

# Linux modem example This is an experimental port of the esp_modem to linux. It mocks some IDF functionality with `port/linux` layers (used for modem host test suite) and implements `esp_netif`, which supports `tun` interface and uses lwIP `ppp` implementation to parse or wrap IP packets to be send/receive over PPPoS, i.e. over the modem serial line. ## Configuration * Set path to the lwip and lwip_contrib repositories as environmental variables: - `LWIP_PATH`: path to the lwip repository - `LWIP_CONTRIB_PATH`: path to the lwip_contrib repository * Create a `tun` interface using `make_tun_netif` script. * Set SIO dev name directly in the code: This is the serial port which is the modem connected to * (Set the tun device na interface name in the code: Not needed if the device was created using the script above.) * Build and run the example (no elevated privileges needed) * 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 ``'s linux target.

readme of modem_console example

# Modem console example ## Overview This example is mainly targets experimenting with a modem device, sending custom commands and switching to PPP mode using esp-console, command line API. Please check the list of supported commands using `help` command. This example implements two very simple network commands to demonstrate and test basic network functionality. * `httpget`: Connect and get http content * `ping`: Send ICMP pings To demonstrate creating custom modem devices, this example creates a DCE object using a locally defined create method, that sets up the DCE based on a custom module implemented in the `my_module_dce.hpp` file. The module class only overrides `get_module_name()` method supplying a user defined name, but keeps all other commands the same as defined in the `GenericModule` class. ### USB DTE support For USB enabled targets (ESP32-S2 and ESP32-S3), it is possible to connect to the modem device via USB. 1. In menuconfig, navigate to `Example Configuration->Type of serial connection to the modem` and choose `USB`. 2. Connect the modem USB signals to pin 19 (DATA-) and 20 (DATA+) on your ESP chip. 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. 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 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`.

readme of modem_psm example

# Modem Power Saving Mode, sleep modes example ## Overview This example demonstrates Power Saving Mode(PSM) in Sim70XX modems along with Deep sleep and Light Sleep modes in esp32. This example enables Power saving mode in Sim70XX modem and tries to synchronise the sleep cycle of the modem with esp32. When the modem wakes up from PSM sleep it wakes up the esp32. While the modem is awake esp32 goes to light sleep. This example is tested on a SIM7080 modem. ## Supported devices This example is supported only on ESP32, ESP32-S2 and ESP32-S3. ## Configuration * EXAMPLE_MODEM_UART_TX_PIN: Connect this pin to the UART Tx pin of the modem. * EXAMPLE_MODEM_UART_RX_PIN: Connect this pin to the UART Rx pin of the modem. * EXAMPLE_MODEM_PWRKEY_PIN: Connect this pin to the PWRKEY pin of the modem. * EXAMPLE_MODEM_STATUS_PIN: Connect this pin to the Status pin of the modem. The status pin might not be exposed on a modem. It needs to tapped out from the LED indicator marked as STS. * EXAMPLE_MODEM_LIGHT_SLEEP_DURATION: Duration for which the esp32 will go into light sleep, while the modem is awake. If the esp32 goes into deep sleep while the modem is awake, esp32 will be awaken by the STATUS pin. So it's recommended to go to light sleep while the modem is awake. * EXAMPLE_MODEM_T3412_PERIODIC_TAU: T3412 timer is the duration of one awake and sleep cycle of the modem in PSM. * EXAMPLE_MODEM_T3324_ACTIVE_TIME: T3324 timer is the duration for which the modem stays PSM. The timeout information is coded in bit format for T3412 and T3324 timer.

readme of modem_tcp_client example

# Modem TCP client (See the file in the upper level 'examples' directory for more information about examples.) ## Overview This example demonstrates how to act as a MQTT client using modem's TCP commands (provided, the device supports "socket" related commands) This example could be used in two different configurations: 1) Custom TCP transport: Implements a TCP transport in form of AT commands and uses it as custom transport for mqtt client. 2) Localhost listener: Uses standard transports to connect and forwards socket layer data from the client to the modem using AT commands. ### Custom TCP transport This configuration expects that the network library, that is used to communicate with the endpoint uses `tcp_transport` component. In this example, we use `esp-mqtt` which supports custom transports so that we can implement a transport layer that communicate on TCP layer using AT commands. If we want to use TLS, we could add an SSL layer on top of this TCP layer. To enable this mode, please set `EXAMPLE_CUSTOM_TCP_TRANSPORT=y` ![with custom tcp transport](at_client_tcp_transport.png) ### Localhost listener 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`.

readme of pppos_client example

# PPPoS simple client example (See the file in the upper level 'examples' directory for more information about examples.) ## Overview This example shows how to act as a MQTT client after the PPPoS channel created by using [ESP-MQTT]( APIs. ## How to use this example See the file in the upper level `pppos` directory for more information about the PPPoS examples. ### USB DTE support For USB enabled targets (ESP32-S2 and ESP32-S3), it is possible to connect to the modem device via USB. 1. In menuconfig, navigate to `Example Configuration->Type of serial connection to the modem` and choose `USB`. 2. Connect the modem USB signals to pin 19 (DATA-) and 20 (DATA+) on your ESP chip. 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`.

readme of simple_cmux_client example

# Simple example of esp_modem component (See the file in the upper level 'examples' directory for more information about examples.) ## Overview This example demonstrates the use of the [esp-modem component]( to connect to a network and send some AT commands. It uses modem CMUX mode so that commands and network could be used at the same time. The example uses the following configuration options to demonstrate basic esp-modem capabilities: * `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](../../ ### Supported IDF versions This example is only supported from `v4.3`, since is uses an experimental `esp_event_cxx` component.


Supports all targets

License: Apache-2.0

To add this component to your project, run: add-dependency "espressif/esp_modem^1.0.4"

or download archive


  • ESP-IDF >=4.1
  • Examples:


    more details


    more details


    more details


    more details


    more details


    more details


    more details


    • Downloaded in total
      Downloaded in total 72.7k times
    • Downloaded this version
      This version: 1.7k times


    espressif/esp_modem version: 1.0.4 |