Documentaton generation completed

This commit is contained in:
David Cermak
2021-04-14 17:57:42 +02:00
parent d384cde725
commit 4bf8ab07ca
27 changed files with 509 additions and 88 deletions

Binary file not shown.

Before

Width:  |  Height:  |  Size: 20 KiB

After

Width:  |  Height:  |  Size: 32 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 59 KiB

After

Width:  |  Height:  |  Size: 139 KiB

View File

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

Binary file not shown.

Before

Width:  |  Height:  |  Size: 40 KiB

View File

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

View File

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

View File

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

View File

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

View File

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

View File

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

View File

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

View File

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

View File

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

View File

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

View File

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