docs(esp_modem): updated documents to show missed topics

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

docs/esp_modem/README.md

@@ -1,92 +0,0 @@
-# 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/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``

docs/esp_modem/en/internal_design.md

@@ -1,36 +0,0 @@
-# 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
-
-![DCE_architecture](DCE_DTE_collaboration.png)
-
-## 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.
-
-![CMUX Terminal](CMux_collaboration.png)

docs/esp_modem/en/internal_design.rst

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

docs/esp_modem/generate_docs

@@ -1,21 +1,72 @@
+# Cleanup the generated html
+rm -rf html
+
+# Generate C++ API header of the DCE
+cat esp_modem_command_declare.inc | clang++ -E -P -CC  -xc++ -I../../components/esp_modem/include -DGENERATE_DOCS  - | sed -n '1,/DCE command documentation/!p' > en/esp_modem_dce.hpp
+
+# Generate C API header of the modem_api.h
+cat esp_modem_command_declare.inc | clang -E -P -CC  -xc -I../../components/esp_modem/include -DGENERATE_DOCS  - | sed -n '1,/DCE command documentation/!p' > en/esp_modem_api_commands.h
+
+
+# RST with links to C++ API
+cat esp_modem_command_declare.inc | clang -E -P  -xc -I../../components/esp_modem/include -DGENERATE_DOCS -DGENERATE_RST_LINKS - | sed 's/NL/\n/g' > en/cxx_api_links.rst
+
 build-docs --target esp32 --language en
 
 cp -rf _build/en/esp32/html .
 rm -rf _build __pycache__
 
+## Modifes some version and target fields of index.html
+#echo "<script type="text/javascript">
+#window.onload =(function() {
+#    var myAnchor = document.getElementById('version-select');
+#    var mySpan = document.createElement('input');
+#    mySpan.setAttribute('type', 'text');
+#    mySpan.setAttribute('maxLength', '10');
+#    mySpan.value = 'latest';
+#    mySpan.setAttribute('disabled', true);
+#    myAnchor.parentNode.replaceChild(mySpan, myAnchor);
+#
+#    var myAnchor = document.getElementById('target-select');
+#    var mySpan = document.createElement('input');
+#    mySpan.setAttribute('type', 'text');
+#    mySpan.setAttribute('maxLength', '10');
+#    mySpan.value = 'all targets';
+#    mySpan.setAttribute('disabled', true);
+#    myAnchor.parentNode.replaceChild(mySpan, myAnchor);
+#
+#})();
+#</script>" >> html/index.html
+
 # Modifes some version and target fields of index.html
-echo "<script type="text/javascript">
+echo "<script type='text/javascript'>
 window.onload =(function() {
     var myAnchor = document.getElementById('version-select');
-    var mySpan = document.createElement('input');
+    var mySpan = document.createElement('select');
-    mySpan.setAttribute('type', 'text');
+    mySpan.style.float = 'left';
-    mySpan.setAttribute('maxLength', '10');
+
-    mySpan.value = 'latest';
+    latest_ver = document.createElement('option');
-    mySpan.setAttribute('disabled', true);
+    latest_ver.value = 'latest';
+    latest_ver.textContent = 'latest(master)';
+    mySpan.append(latest_ver);
+
+    var myArray = ['v1.0.0''];
+    for (var i = myArray.length - 1; i >= 0; i--) {
+      current_ver = document.createElement('option');
+      current_ver.value = myArray[i];
+      current_ver.textContent = 'release-'+myArray[i];
+      mySpan.append(current_ver);
+    }
+
+
     myAnchor.parentNode.replaceChild(mySpan, myAnchor);
+    mySpan.addEventListener('change', function() {
+      window.location.href='https://docs.espressif.com/projects/esp-protocols/esp_modem/docs/'+event.target.value+'/index.html'
+    });
 
     var myAnchor = document.getElementById('target-select');
     var mySpan = document.createElement('input');
+    mySpan.style.float = 'left';
     mySpan.setAttribute('type', 'text');
     mySpan.setAttribute('maxLength', '10');
     mySpan.value = 'all targets';
@@ -23,4 +74,4 @@ window.onload =(function() {
     myAnchor.parentNode.replaceChild(mySpan, myAnchor);
 
 })();
-</script>" >> html/index.html
+</script>"  >> html/index.html