espressif/esp_modem

readme

# ESP MODEM

[![Component Registry](https://components.espressif.com/components/espressif/esp_modem/badge.svg)](https://components.espressif.com/components/espressif/esp_modem)

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](docs/README.md)
* View the full [html documentation](https://espressif.github.io/esp-protocols/esp_modem/index.html)

                                        
                                        # 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.

                                    

                                        
                                        # 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 `idf.py`'s linux target.

                                    

                                        
                                        # 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 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`.

                                    

                                        
                                        # 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.

                                    

                                        
                                        # PPPoS simple client example

(See the README.md 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](https://docs.espressif.com/projects/esp-idf/en/latest/api-reference/protocols/mqtt.html) APIs.

## How to use this example

See the README.md 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`.

                                    

                                        
                                        # Simple example of esp_modem component

(See the README.md file in the upper level 'examples' directory for more information about examples.)

## Overview

This example demonstrates the use of the [esp-modem component](https://components.espressif.com/component/espressif/esp_modem) 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](../../README.md)

### Supported IDF versions

This example is only supported from `v4.3`, since is uses an experimental `esp_event_cxx` component.