docs(esp_modem): updated documents to show missed topics

2025-07-20 22:12:27 +02:00 · 2023-04-18 21:12:39 +04:00
parent 18ea910f02
commit 05348534a6
10 changed files with 255 additions and 137 deletions
--- a/docs/esp_modem/en/README.rst
+++ b/docs/esp_modem/en/README.rst
@ -0,0 +1,132 @@
+ESP MODEM
+=========
+
+This component is used to communicate with modems in the command mode
+(using AT commands), as well as the data mode (over PPPoS protocol). The
+modem device is modeled with a DCE (Data Communication Equipment)
+object, which is composed of:
+
+- DTE (Data Terminal Equipment), which abstracts the terminal (currently only UART implemented).
+- PPP Netif representing a network interface communicating with the DTE using PPP protocol.
+- Module abstracting the specific device model and its commands.
+
+::
+
+      +-----+
+      | DTE |--+
+      +-----+  |   +-------+
+               +-->|   DCE |
+      +-------+    |       |o--- set_mode(command/data)
+      | Module|--->|       |
+      +-------+    |       |o--- send_commands
+                +->|       |
+      +------+  |  +-------+
+      | PPP  |--+
+      | netif|------------------> network events
+      +------+
+
+Modem components
+----------------
+
+DCE
+~~~
+
+This is the basic operational unit of the esp_modem component,
+abstracting a specific module in software, which is basically configured
+by
+
+- the I/O communication media (UART), defined by the DTE configuration
+- the specific command library supported by the device  model, defined with the module type
+- network interface configuration (PPPoS config in lwip)
+
+After the object is created, the application interaction with the DCE is
+in
+
+- issuing specific commands to the modem
+- switching between data and command mode
+
+DTE
+~~~
+
+Is an abstraction of the physical interface connected to the modem.
+Current implementation supports only UART
+
+PPP netif
+~~~~~~~~~
+
+Is used to attach the specific network interface to a network
+communication protocol used by the modem. Currently implementation
+supports only PPPoS protocol.
+
+Module
+~~~~~~
+
+Abstraction of the specific modem device. Currently the component
+supports SIM800, BG96, SIM7600.
+
+Use cases
+---------
+
+Users interact with the esp-modem using the DCE’s interface, to
+basically
+
+- Switch between command and data mode to connect to the internet via cellular network.
+- Send various commands to the device (e.g. send SMS)
+
+The applications typically register handlers for network events to
+receive notification on the network availability and IP address changes.
+
+Common use cases of the esp-modem are also listed as the examples:
+
+- ``examples/pppos_client`` – simple client which reads some module properties and switches to the data mode to connect to a public mqtt broker.
+- ``examples/modem_console`` – is an example to exercise all possible module commands in a console application.
+- ``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.
+
+Extensibility
+-------------
+
+CMUX
+~~~~
+
+Implementation of virtual terminals is an experimental feature, which
+allows users to also issue commands in the data mode, after creating
+multiple virtual terminals, designating some of them solely to data
+mode, others solely to command mode.
+
+DTE’s
+~~~~~
+
+Currently, we support only UART (and USB as a preview feature), but
+modern modules support other communication interfaces, such as USB, SPI.
+
+Other devices
+~~~~~~~~~~~~~
+
+Adding a new device is a must-have requirement for the esp-modem
+component. Different modules support different commands, or some
+commands might have a different implementation. Adding a new device
+means to provide a new implementation as a class derived from
+``GenericModule``, where we could add new commands or modify the
+existing ones.
+
+Configuration
+-------------
+
+Modem abstraction is configurable both compile-time and run-time.
+
+Component Kconfig
+~~~~~~~~~~~~~~~~~
+
+Compile-time configuration is provided using menuconfig. Please check
+the description for the CMUX mode configuration options.
+
+Runtime configuration
+~~~~~~~~~~~~~~~~~~~~~
+
+Is defined using standard configuration structures for ``DTE`` and
+``DCE`` objects separately. Please find documentation of
+
+- :cpp:class:``esp_modem_dte_config_t``
+- :cpp:class:``esp_modem_dce_config_t``