Documentaton generation completed

esp_modem/docs/Doxyfile

@@ -829,10 +829,23 @@ WARN_LOGFILE           =
 # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING
 # Note: If this tag is empty the current directory is searched.
 
-INPUT                  = c_api.h cpp_api.h ../include/esp_modem_api.h \
+INPUT                  =                 ../include/esp_modem_api.h \
                                          ../include/esp_modem_c_api_types.h \
                                          ../include/cxx_include/esp_modem_api.hpp \
-                                         ../include/cxx_include/esp_modem_dce.hpp
+                                         ../include/cxx_include/esp_modem_dce.hpp \
+                                         ../include/esp_modem_config.h \
+                                         ../include/esp_modem_dce_config.h \
+                                         ../include/cxx_include/esp_modem_dce_factory.hpp \
+                                         ../include/cxx_include/esp_modem_command_library.hpp \
+                                         ../include/cxx_include/esp_modem_dce_module.hpp \
+                                         ../include/cxx_include/esp_modem_dte.hpp \
+                                         ../include/cxx_include/esp_modem_netif.hpp \
+                                         ../include/cxx_include/esp_modem_types.hpp \
+                                         ../include/cxx_include/esp_modem_terminal.hpp \
+                                         ../include/cxx_include/esp_modem_cmux.hpp \
+                                         esp_modem_api_commands.h \
+                                         esp_modem_dce.hpp
+# The last two are generated
 
 # This tag can be used to specify the character encoding of the source files
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses
@@ -947,7 +960,7 @@ IMAGE_PATH             =
 # need to set EXTENSION_MAPPING for the extension otherwise the files are not
 # properly processed by doxygen.
 
-INPUT_FILTER           = "sed 's/std::unique_ptr<\(.*\)>/\1*/;s/std::shared_ptr<\(.*\)>/\1*/'"
+#INPUT_FILTER           = "sed 's/std::unique_ptr<\(.*\)>/\1*/;s/std::shared_ptr<\(.*\)>/\1*/'"
 
 # The FILTER_PATTERNS tag can be used to specify filters on a per file pattern
 # basis. Doxygen will compare the file name with each pattern and apply the
@@ -1103,7 +1116,7 @@ IGNORE_PREFIX          =
 # If the GENERATE_HTML tag is set to YES, doxygen will generate HTML output
 # The default value is: YES.
 
-GENERATE_HTML          = YES
+GENERATE_HTML          = NO
 
 # The HTML_OUTPUT tag is used to specify where the HTML docs will be put. If a
 # relative path is entered the value of OUTPUT_DIRECTORY will be put in front of
@@ -1658,7 +1671,7 @@ EXTRA_SEARCH_MAPPINGS  =
 # If the GENERATE_LATEX tag is set to YES, doxygen will generate LaTeX output.
 # The default value is: YES.
 
-GENERATE_LATEX         = YES
+GENERATE_LATEX         = NO
 
 # The LATEX_OUTPUT tag is used to specify where the LaTeX docs will be put. If a
 # relative path is entered the value of OUTPUT_DIRECTORY will be put in front of
@@ -2459,7 +2472,7 @@ DOT_GRAPH_MAX_NODES    = 250
 # Minimum value: 0, maximum value: 1000, default value: 0.
 # This tag requires that the tag HAVE_DOT is set to YES.
 
-MAX_DOT_GRAPH_DEPTH    = 10
+MAX_DOT_GRAPH_DEPTH    = 3
 
 # Set the DOT_TRANSPARENT tag to YES to generate images with a transparent
 # background. This is disabled by default, because dot on Windows does not seem
@@ -2508,4 +2521,5 @@ DOT_CLEANUP            = YES
 #TEMPLATE_RELATIONS   = YES
 #DOT_GRAPH_MAX_NODES  = 100
 #MAX_DOT_GRAPH_DEPTH  = 0
-#DOT_TRANSPARENT      = YES
+#DOT_TRANSPARENT      = YES
+

esp_modem/docs/advanced_api.rst

@@ -1,15 +1,45 @@
 Advanced esp-modem use cases
 ============================
 
-Create custom modem instance with DCE factory
----------------------------------------------
+This chapter outlines basic extensibility of the esp-modem component.
+
+.. _dce_factory:
+
+Custom instantiation with DCE factory
+--------------------------------------
+
+It is possible to create a modem handle in many different ways:
+
+- Build a DCE on top a generic module, user defined module or build the module only (in case the application will only use AT command interface)
+- Create the DCE as a shared, unique or a vanilla pointer
+- Create a generic DCE or a templated DCE_T of a specific module (this could be one of the supported modules or a user defined module)
+
+All the functionality is provided by the DCE factory
+
+.. doxygengroup:: ESP_MODEM_DCE_FACTORY
+   :members:
 
 
 Create custom module
 --------------------
 
+Creating a custom module is necessary if the application needs to use a specific device that is not supported
+and their commands differ from any of the supported devices. In this case it is recommended to define a new class
+representing this specific device and derive from the :cpp:class:`GenericModule`. In order to instantiate
+the appropriate DCE of this module, application could use :ref:`the DCE factory<dce_factory>`, but build the DCE with
+the specific module, using :cpp:func:`esp_modem::dce_factory::Factory::build`.
+
+Please refer to the implementation of the existing modules.
+
 
 Create new communication interface
 ----------------------------------
 
+In order to connect to a device using an unsuppoeted interface (e.g. SPI or I2C), it is necessary to implement
+a custom DTE object and supply it into :ref:`the DCE factory<dce_factory>`. The DCE is typically created in two steps:
+
+- Define and create the corresponding terminal, which can communicate on the custom interface. This terminal should support basic IO methods defined in :cpp:class:`esp_modem::Terminal` and derive from it.
+- Create the DTE which uses the custom Terminal
+
+Please refer to the implementation of the existing UART DTE.
 

esp_modem/docs/api_docs.rst

@@ -18,6 +18,7 @@ Typical application workflow is to:
 - Optionally switch back to command mode (again :cpp:func:`esp_modem_set_mode`)
 - Destroy the DCE handle (sing :cpp:func:`esp_modem_destroy`)
 
+Note the configuration structures for DTE and DCE, needed for creating the DCE instance, is documented in :ref:`api_config`
 
 .. _lifecycle_api:
 
@@ -26,6 +27,10 @@ Lifecycle API
 
 These functions are used to create, destroy and set modem working mode.
 
+- :cpp:func:`esp_modem_new`
+- :cpp:func:`esp_modem_destroy`
+- :cpp:func:`esp_modem_set_mode`
+
 .. doxygengroup:: ESP_MODEM_C_API
 
 
@@ -37,4 +42,13 @@ Modem commands
 These functions are the actual commands to communicate with the modem using AT command interface.
 
 
-.. doxygenfile:: c_api.h
+.. doxygenfile:: esp_modem_api_commands.h
+
+.. _api_config:
+
+Configuration structures
+------------------------
+
+
+.. doxygengroup:: ESP_MODEM_CONFIG
+   :members:

esp_modem/docs/conf.py

@@ -9,14 +9,14 @@ import subprocess
 import sys
 
 # General information about the project.
-project = u'ESP-MODEM Documentation'
+project = u'esp-modem'
 copyright = u'2016 - 2021, Espressif Systems (Shanghai) Co., Ltd'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
 language = 'en'
 
-extensions = ['breathe' ]
+extensions = ['breathe']
 
 breathe_projects = {'esp_modem': 'xml'}
 

esp_modem/docs/cxx_api_docs.rst

@@ -3,10 +3,14 @@ C++ API Documentation
 
 Similar to the :ref:`c_api`, the basic application workflow consist of
 
-- Construction of the DCE
-- Sending (AT) commands
-- Switching modes
-- Destroying the DCE
+.. toctree::
+
+- :ref:`Construction of the DCE<cpp_init>`
+- :ref:`Switching modes<cpp_mode_switch>`
+- :ref:`Sending (AT) commands<cpp_modem_commands>`
+- :ref:`Destroying the DCE<cpp_destroy>`
+
+.. _cpp_init:
 
 Create DTE and DCE
 ------------------
@@ -16,21 +20,22 @@ Create DTE and DCE
 .. doxygengroup:: ESP_MODEM_INIT_DCE
 
 
+.. _cpp_mode_switch:
+
 Mode switching commands
 -----------------------
 
 .. doxygenclass:: esp_modem::DCE_T
    :members:
 
+.. _cpp_modem_commands:
 
 Modem commands
 --------------
 
-Create the DCE object with DCE factory :cpp:func:`esp_modem_new`
-
-.. doxygenclass:: DCE
-   :members:
+.. include:: cxx_api_links.rst
 
+.. _cpp_destroy:
 
 Destroy the DCE
 ---------------

esp_modem/docs/cxx_api_links.rst

@@ -0,0 +1,13 @@
+
+- :cpp:func:`esp_modem::DCE::set_pin` 
+- :cpp:func:`esp_modem::DCE::read_pin` 
+- :cpp:func:`esp_modem::DCE::set_echo` 
+- :cpp:func:`esp_modem::DCE::resume_data_mode` 
+- :cpp:func:`esp_modem::DCE::set_pdp_context` 
+- :cpp:func:`esp_modem::DCE::set_command_mode` 
+- :cpp:func:`esp_modem::DCE::set_cmux` 
+- :cpp:func:`esp_modem::DCE::get_imsi` 
+- :cpp:func:`esp_modem::DCE::get_imei` 
+- :cpp:func:`esp_modem::DCE::get_module_name` 
+- :cpp:func:`esp_modem::DCE::set_data_mode` 
+- :cpp:func:`esp_modem::DCE::get_signal_quality`

esp_modem/docs/esp_modem_api_commands.h

@@ -1,4 +1,5 @@
 // cat ../include/generate/esp_modem_command_declare.inc | clang -E -P -CC  -xc -I../include -DGENERATE_DOCS  - | sed -n '1,/DCE command documentation/!p' > c_api.h
+// cat ../include/generate/esp_modem_command_declare.inc | clang -E -P  -xc -I../include -DGENERATE_DOCS -DGENERATE_RST_LINKS - | sed 's/NL/\n/g' > cxx_api_links.rst
 //  --- DCE command documentation starts here ---
 /**
  * @brief Sends the supplied PIN code

esp_modem/docs/esp_modem_dce.hpp

@@ -1,6 +1,8 @@
+// cat ../include/generate/esp_modem_command_declare.inc | clang -E -P -CC  -xc -I../include -DGENERATE_DOCS  - | sed -n '1,/DCE command documentation/!p' > c_api.h
+// cat ../include/generate/esp_modem_command_declare.inc | clang -E -P  -xc -I../include -DGENERATE_DOCS -DGENERATE_RST_LINKS - | sed 's/NL/\n/g' > cxx_api_links.rst
 //  --- DCE command documentation starts here ---
 
-class DCE: public DCE_T<GenericModule> {
+class esp_modem::DCE: public DCE_T<GenericModule> {
 public:
     using DCE_T<GenericModule>::DCE_T;
 
@@ -9,6 +11,7 @@ public:
 
 
 
+
 /**
  * @brief Sends the supplied PIN code
  *

esp_modem/docs/generate_docs

@@ -1,2 +1,20 @@
+# Cleanup the generated html
+rm -rf html
 
+# Generate C++ API header of the DCE
+cat ../include/generate/esp_modem_command_declare.inc | clang++ -E -P -CC  -xc++ -I../include -DGENERATE_DOCS  - | sed -n '1,/DCE command documentation/!p' > esp_modem_dce.hpp
+
+# Generate C API header of the modem_api.h
+cat ../include/generate/esp_modem_command_declare.inc | clang -E -P -CC  -xc -I../include -DGENERATE_DOCS  - | sed -n '1,/DCE command documentation/!p' > esp_modem_api_commands.h
+
+# RST with links to C++ API
+cat ../include/generate/esp_modem_command_declare.inc | clang -E -P  -xc -I../include -DGENERATE_DOCS -DGENERATE_RST_LINKS - | sed 's/NL/\n/g' > cxx_api_links.rst
+
+# Run doxygen
+doxygen
+
+# Generate the docs
 python -u -m sphinx.cmd.build -b html  . html
+
+# Cleanup the doxygen xml's
+rm -rf xml

esp_modem/docs/index.rst

@@ -1,5 +1,5 @@
-ESP-MODEM Documentation
-=======================
+ESP-MODEM Programmers manual
+============================
 
 .. toctree::
 
@@ -8,4 +8,4 @@ ESP-MODEM Documentation
    C++ interface <cxx_api_docs>
    Advanced use cases <advanced_api>
    Internal design <internal_design>
-
+   Internal implementation <internal_docs>

esp_modem/docs/internal_design.md

@@ -3,45 +3,14 @@
 ## Design decisions
 
 * Use C++ with additional C API
-  
-  | esp-modem in C | esp-modem in C++ |
-  |----------------|---------------|
-```
-    +2282
-    -3908
-```
 
 * Use exceptions
   - Use macro wrapper over `try-catch` blocks when exceptions off (use `abort()` if `THROW()`) 
 
-| exceptions off | exceptions on |
-|----------------|---------------|
-```
-Difference is counted as <CURRENT> - <REFERENCE>, i.e. a positive number means that <CURRENT> is larger.
-Total sizes of <CURRENT>:                                                 <REFERENCE>     Difference
- DRAM .data size:   10996 bytes                                                 10996
- DRAM .bss  size:   12552 bytes                                                 12488            +64
-Used static DRAM:   23548 bytes ( 157188 available, 13.0% used)                 23484            +64 (    -64 available,      +0 total)
-Used static IRAM:   54145 bytes (  76927 available, 41.3% used)                 54093            +52 (    -52 available,      +0 total)
-      Flash code:  603979 bytes                                                595551          +8428
-    Flash rodata:  187772 bytes                                                177852          +9920
-Total image size:~ 869444 bytes (.bin may be padded larger)                    850980         +18464
-```
-| exceptions on | RTTI on |
-|----------------|---------------|
-```
-Total sizes of <CURRENT>:                                                 <REFERENCE>     Difference
- DRAM .data size:   10996 bytes                                                 10996
- DRAM .bss  size:   12552 bytes                                                 12552
-Used static DRAM:   23548 bytes ( 157188 available, 13.0% used)                 23548                (     +0 available,      +0 total)
-Used static IRAM:   54145 bytes (  76927 available, 41.3% used)                 54145                (     +0 available,      +0 total)
-      Flash code:  605331 bytes                                                603979          +1352
-    Flash rodata:  196788 bytes                                                187772          +9016
-Total image size:~ 879812 bytes (.bin may be padded larger)                    869444         +10368
-```
 * 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
@@ -57,12 +26,11 @@ The diagram describes how the DCE class collaborates with DTE, PPP and the devic
 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.
 
-![TerminalInheritance](Terminal_inheritance.png)
-
 ## CMUX terminal
 
-The below diagram depicts the idea of using CMUX terminal mode using the CMux class which is a 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 another terminal, the real terminal, which is multiplexed.
+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)

esp_modem/docs/internal_docs.rst

@@ -0,0 +1,85 @@
+DCE Internal implementation
+===========================
+
+This chapter provides a detailed description of the classes and building blocks of the esp-modem component and their responsibilities.
+
+The esp-modem actually implements the DCE class, which in turn aggregates these thee units:
+
+- :ref:`DTE<dte_impl>` to communicate with the device on a specific Terminal interface such as UART.
+- :ref:`Netif<netif_impl>` to provide the network connectivity
+- :ref:`Module<module_impl>` to define the specific command library
+
+------------
+
+.. doxygengroup:: ESP_MODEM_DCE
+   :members:
+
+.. _dte_impl:
+
+DTE abstraction
+---------------
+
+DTE is a basic unit to talk to the module using a Terminal interface. It also implements and uses the CMUX to multiplex
+terminals. Besides the DTE documentation, this section also refers to the
+
+- :ref:`Terminal interface<term_impl>`
+- :ref:`CMUX implementation<cmux_impl>`
+
+
+------------
+
+.. doxygengroup:: ESP_MODEM_DTE
+   :members:
+
+.. _term_impl:
+
+Terminal interface
+^^^^^^^^^^^^^^^^^^
+
+.. doxygengroup:: ESP_MODEM_TERMINAL
+   :members:
+
+.. _cmux_impl:
+
+CMUX implementation
+^^^^^^^^^^^^^^^^^^^
+
+.. doxygengroup:: ESP_MODEM_CMUX
+   :members:
+
+.. _netif_impl:
+
+Netif
+-----
+
+.. doxygengroup:: ESP_MODEM_NETIF
+   :members:
+
+.. _module_impl:
+
+Module abstraction
+------------------
+
+.. doxygengroup:: ESP_MODEM_MODULE
+   :members:
+
+Command library
+^^^^^^^^^^^^^^^
+
+This is a namespace holding a library of typical AT commands used by supported devices.
+Please refer to the :ref:`c_api` for the list of supported commands.
+
+.. doxygengroup:: ESP_MODEM_DCE_COMMAND
+   :members:
+
+
+Modem types
+-----------
+
+.. doxygengroup:: ESP_MODEM_TYPES
+   :members:
+
+
+
+
+