Merge pull request #275 from gabsuren/docs/esp_modem_docs

docs(esp_modem): updated documents to show missed topics

Author: gabsuren

components/esp_modem/README.md

@@ -17,5 +17,5 @@ Get started with one of the examples:
 
 ## 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)
+* Continue with esp-modem [brief overview](https://github.com/espressif/esp-protocols/tree/master/docs/esp_modem/en/README.rst)
+* View the full [html documentation](https://docs.espressif.com/projects/esp-protocols/esp_modem/docs/latest/index.html)

docs/esp_modem/README.md

@@ -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``

docs/esp_modem/CMux_collaboration.png docs/esp_modem/en/CMux_collaboration.pngdocs/esp_modem/CMux_collaboration.png renamed to docs/esp_modem/en/CMux_collaboration.png

@@ -0,0 +1,63 @@
+Internal design
+===============
+
+Design decisions
+----------------
+
+-  Use C++ with additional C API
+
+-  Use exceptions
+
+   -  Use macro wrapper over ``try-catch`` blocks when exceptions off
+      (use ``abort()`` if ``THROW()``)
+
+-  Initializes and allocates in the constructor (might throw)
+
+   -  easier code with exceptions ON, with exceptions OFF alloc/init
+      failures are not treated as runtime error (program aborts)
+   -  break down long initialization in constructor into more private
+      methods
+
+-  Implements different devices using inheritance from
+   ``GenericModule``, which is the most general implementation of a
+   common modem
+
+   -  Internally uses templates with device specialization (modeled as
+      ``DCE<SpecificModule>``) which could be used as well for some
+      special cases, such as implantation of a minimal device
+      (ModuleIf), add new AT commands (oOnly in compile time), or using
+      the Module with DTE only (no DCE, no Netif) for sending AT
+      commands without network
+
+DCE collaboration model
+-----------------------
+
+The diagram describes how the DCE class collaborates with DTE, PPP and
+the device abstraction
+
+.. figure:: DCE_DTE_collaboration.png
+   :alt: DCE_architecture
+
+   DCE_architecture
+
+Terminal inheritance
+--------------------
+
+Terminal is a class which can read or write data, and can handle
+callbacks when data are available. UART specialization is provided
+implementing these method using the uart driver.
+
+CMUX terminal
+-------------
+
+The below diagram depicts the idea of using CMUX terminal mode using the
+CMuxInstance class which is a terminal (it implements the basic
+read/write methods) interfacing arbitrary number of virtual terminals,
+but at the same time it is also composed of CMux class, which consumes
+the original terminal and uses its read/write methods to multiplex the
+terminal.
+
+.. figure:: CMux_collaboration.png
+   :alt: CMUX Terminal
+
+   CMUX Terminal