From d9ed971b9244de720b6038e001144023b675ce41 Mon Sep 17 00:00:00 2001 From: Suren Gabrielyan Date: Tue, 18 Apr 2023 21:12:39 +0400 Subject: [PATCH] docs(esp_modem): updated documents to show missed topics --- components/esp_modem/README.md | 4 +- docs/esp_modem/README.md | 92 ------------- .../esp_modem/{ => en}/CMux_collaboration.png | Bin .../{ => en}/DCE_DTE_collaboration.png | Bin docs/esp_modem/en/README.rst | 128 ++++++++++++++++++ docs/esp_modem/en/internal_design.md | 36 ----- docs/esp_modem/en/internal_design.rst | 63 +++++++++ .../esp_modem}/esp_modem_command_declare.inc | 0 .../esp_modem_command_declare_helper.inc | 0 docs/esp_modem/generate_docs | 65 ++++++++- 10 files changed, 251 insertions(+), 137 deletions(-) delete mode 100644 docs/esp_modem/README.md rename docs/esp_modem/{ => en}/CMux_collaboration.png (100%) rename docs/esp_modem/{ => en}/DCE_DTE_collaboration.png (100%) create mode 100644 docs/esp_modem/en/README.rst delete mode 100644 docs/esp_modem/en/internal_design.md create mode 100644 docs/esp_modem/en/internal_design.rst rename {components/esp_modem/include/generate => docs/esp_modem}/esp_modem_command_declare.inc (100%) rename {components/esp_modem/include/generate => docs/esp_modem}/esp_modem_command_declare_helper.inc (100%) diff --git a/components/esp_modem/README.md b/components/esp_modem/README.md index c4407100122..fe188eea628 100644 --- a/components/esp_modem/README.md +++ b/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](../../docs/esp_modem/en/README.rst) +* View the full [html documentation](https://docs.espressif.com/projects/esp-protocols/esp_modem/docs/latest/index.html) diff --git a/docs/esp_modem/README.md b/docs/esp_modem/README.md deleted file mode 100644 index 6e50d9bcd40..00000000000 --- a/docs/esp_modem/README.md +++ /dev/null @@ -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` diff --git a/docs/esp_modem/CMux_collaboration.png b/docs/esp_modem/en/CMux_collaboration.png similarity index 100% rename from docs/esp_modem/CMux_collaboration.png rename to docs/esp_modem/en/CMux_collaboration.png diff --git a/docs/esp_modem/DCE_DTE_collaboration.png b/docs/esp_modem/en/DCE_DTE_collaboration.png similarity index 100% rename from docs/esp_modem/DCE_DTE_collaboration.png rename to docs/esp_modem/en/DCE_DTE_collaboration.png diff --git a/docs/esp_modem/en/README.rst b/docs/esp_modem/en/README.rst new file mode 100644 index 00000000000..42d97d09e82 --- /dev/null +++ b/docs/esp_modem/en/README.rst @@ -0,0 +1,128 @@ +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`` diff --git a/docs/esp_modem/en/internal_design.md b/docs/esp_modem/en/internal_design.md deleted file mode 100644 index c132bede068..00000000000 --- a/docs/esp_modem/en/internal_design.md +++ /dev/null @@ -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`) 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) diff --git a/docs/esp_modem/en/internal_design.rst b/docs/esp_modem/en/internal_design.rst new file mode 100644 index 00000000000..a2b0353bf89 --- /dev/null +++ b/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``) 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 diff --git a/components/esp_modem/include/generate/esp_modem_command_declare.inc b/docs/esp_modem/esp_modem_command_declare.inc similarity index 100% rename from components/esp_modem/include/generate/esp_modem_command_declare.inc rename to docs/esp_modem/esp_modem_command_declare.inc diff --git a/components/esp_modem/include/generate/esp_modem_command_declare_helper.inc b/docs/esp_modem/esp_modem_command_declare_helper.inc similarity index 100% rename from components/esp_modem/include/generate/esp_modem_command_declare_helper.inc rename to docs/esp_modem/esp_modem_command_declare_helper.inc diff --git a/docs/esp_modem/generate_docs b/docs/esp_modem/generate_docs index def507c5ede..7ed08c8706f 100755 --- a/docs/esp_modem/generate_docs +++ b/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 "" >> html/index.html + # Modifes some version and target fields of index.html -echo "" >> html/index.html +" >> html/index.html