mirror of
https://github.com/espressif/esp-protocols.git
synced 2025-07-16 12:02:11 +02:00
docs(common): improving documentation
- update esp_modem to use esp_docs - migrated docs from github pages to docs.espressif.com
This commit is contained in:
Suren Gabrielyan
Binary file not shown.
|
Before Width: | Height: | Size: 26 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 139 KiB |
File diff suppressed because it is too large
Load Diff
@ -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`
|
||||
@ -1,48 +0,0 @@
|
||||
Advanced esp-modem use cases
|
||||
============================
|
||||
|
||||
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:
|
||||
|
||||
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:`esp_modem::GenericModule`. In order to instantiate
|
||||
the appropriate DCE of this module, application could use :ref:`the DCE factory<dce_factory>`, and 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.
|
||||
|
||||
Please note that the ``modem_console`` example defines a trivial custom modem DCE which overrides one command,
|
||||
for demonstration purposes only.
|
||||
|
||||
|
||||
Create new communication interface
|
||||
----------------------------------
|
||||
|
||||
In order to connect to a device using an unsupported 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 communicates 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.
|
||||
@ -1,57 +0,0 @@
|
||||
.. _c_api:
|
||||
|
||||
C API Documentation
|
||||
===================
|
||||
|
||||
|
||||
The C API is very simple and consist of these two basic parts:
|
||||
|
||||
- :ref:`lifecycle_api`
|
||||
- :ref:`modem_commands`
|
||||
|
||||
The Typical application workflow is to:
|
||||
|
||||
- Create a DCE instance (using :cpp:func:`esp_modem_new`)
|
||||
- Call specific functions to issue AT commands (:ref:`modem_commands`)
|
||||
- Switch to the data mode (using :cpp:func:`esp_modem_set_mode`)
|
||||
- Perform desired network operations (using standard networking API, unrelated to ESP-MODEM)
|
||||
- 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:
|
||||
|
||||
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
|
||||
|
||||
|
||||
.. _modem_commands:
|
||||
|
||||
Modem commands
|
||||
--------------
|
||||
|
||||
These functions are the actual commands to communicate with the modem using AT command interface.
|
||||
|
||||
Note that the functions which implement AT commands returning textual values use plain ``char *``
|
||||
pointer as the return value. The API expects the output data to point to user allocated space of at least
|
||||
``ESP_MODEM_C_API_STR_MAX`` (64 by default) bytes, it also truncates the output data to this size.
|
||||
|
||||
.. doxygenfile:: esp_modem_api_commands.h
|
||||
|
||||
.. _api_config:
|
||||
|
||||
Configuration structures
|
||||
------------------------
|
||||
|
||||
|
||||
.. doxygengroup:: ESP_MODEM_CONFIG
|
||||
:members:
|
||||
@ -1,24 +0,0 @@
|
||||
# -*- coding: utf-8 -*-
|
||||
#
|
||||
# English Language RTD & Sphinx config file
|
||||
#
|
||||
|
||||
# General information about the project.
|
||||
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', 'recommonmark']
|
||||
|
||||
breathe_projects = {'esp_modem': 'xml'}
|
||||
|
||||
breathe_default_project = 'esp_modem'
|
||||
|
||||
source_suffix = ['.rst', '.md']
|
||||
|
||||
source_parsers = {
|
||||
'.md': 'recommonmark.parser.CommonMarkParser',
|
||||
}
|
||||
@ -1,44 +0,0 @@
|
||||
C++ API Documentation
|
||||
=====================
|
||||
|
||||
Similar to the :ref:`c_api`, the basic application workflow consist of
|
||||
|
||||
.. 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
|
||||
------------------
|
||||
|
||||
.. doxygengroup:: ESP_MODEM_INIT_DTE
|
||||
|
||||
.. doxygengroup:: ESP_MODEM_INIT_DCE
|
||||
|
||||
|
||||
.. _cpp_mode_switch:
|
||||
|
||||
Mode switching commands
|
||||
-----------------------
|
||||
|
||||
.. doxygenclass:: esp_modem::DCE_T
|
||||
:members:
|
||||
|
||||
.. _cpp_modem_commands:
|
||||
|
||||
Modem commands
|
||||
--------------
|
||||
|
||||
.. include:: cxx_api_links.rst
|
||||
|
||||
.. _cpp_destroy:
|
||||
|
||||
Destroy the DCE
|
||||
---------------
|
||||
|
||||
The DCE object is created as ``std::unique_ptr`` by default and as such doesn't have to be explicitly destroyed.
|
||||
It simply gets destroyed and cleaned-up automatically if the object goes out of the block scope.
|
||||
@ -1,23 +0,0 @@
|
||||
# Cleanup the generated html
|
||||
rm -rf html
|
||||
|
||||
# Cleans example and test build dirs (to reduce the component size before upload)
|
||||
rm -rf ../examples/ap_to_pppos/build/ ../examples/simple_cmux_client/build/ ../examples/pppos_client/build/ ../examples/linux_modem/build/ ../examples/modem_console/build ../test/host_test/build/ ../test/target/build/
|
||||
|
||||
# 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 and temporary headers
|
||||
rm -rf xml esp_modem_api_commands.h esp_modem_dce.hpp cxx_api_links.rst
|
||||
@ -1,11 +0,0 @@
|
||||
ESP-MODEM Programmers manual
|
||||
============================
|
||||
|
||||
.. toctree::
|
||||
|
||||
Brief intro <README>
|
||||
C interface <api_docs>
|
||||
C++ interface <cxx_api_docs>
|
||||
Advanced use cases <advanced_api>
|
||||
Internal design <internal_design>
|
||||
Internal implementation <internal_docs>
|
||||
@ -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
|
||||
|
||||
|
||||
|
||||
## 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.
|
||||
|
||||
|
||||
@ -1,117 +0,0 @@
|
||||
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
|
||||
|
||||
Developers would typically have to
|
||||
|
||||
* Add support for a new module
|
||||
* Implement a generic (common for all modules) AT command
|
||||
|
||||
This is explained in the :ref:`Module<module_impl>` section, as :ref:`Adding new module or command<module_addition>`
|
||||
|
||||
------------
|
||||
|
||||
.. 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:
|
||||
|
||||
.. _module_addition:
|
||||
|
||||
Adding new devices
|
||||
^^^^^^^^^^^^^^^^^^
|
||||
|
||||
To support a new module, developers would have to implement a new class derived from :cpp:class:`esp_modem::GenericModule` the same way
|
||||
as it is described in the :ref:`Advanced user manual<create_custom_module>`. The only difference is that the new class (and factory extension)
|
||||
would be available in the esp_modem code base.
|
||||
|
||||
Implement a new generic command
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Adding a generic command, i.e. the command that is shared for all modules and is included in the :cpp:class:`esp_modem::GenericModule`,
|
||||
has to be declared first in the ``include/generate/esp_modem_command_declare.inc`` file, which is the single source
|
||||
of supported command definitions, that is used in:
|
||||
|
||||
* public C API
|
||||
* public CPP API
|
||||
* generated documentation
|
||||
* implementation of the command
|
||||
|
||||
Therefore, a care must be taken, to correctly specify all parameters and types, especially:
|
||||
|
||||
* Keep number of parameters low (<= 6, used in preprocessor's forwarding to the command library)
|
||||
* Use macros to specify parameter types (as they are used both from C and C++ with different underlying types)
|
||||
* Parameter names are used only for clarity and documentation, they get expanded to numbered arguments.
|
||||
|
||||
Please use the following pattern: ``INT_IN(p1, baud)``, meaning that the parameter is an input integer,
|
||||
human readable argument name is ``baud``, it's the first argument, so expands to ``p1`` (second argument would be ``p2``, etc)
|
||||
|
||||
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:
|
||||
Reference in New Issue
Block a user