Added simple docs sketch

This commit is contained in:
David Cermak
2021-04-13 20:29:55 +02:00
parent 8b7df5b8c9
commit 17d3d9a794
16 changed files with 3010 additions and 88 deletions

2567
esp_modem/docs/Doxyfile Normal file

File diff suppressed because it is too large Load Diff

79
esp_modem/docs/README.md Normal file
View File

@ -0,0 +1,79 @@
# 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 connected interface. Current implementation supports only UART
### PPP
Is used to connect the specific network interface to the modem data mode. Currently implementation supports only PPPoS protocol.
### Module
Abstraction of the specific modem device. Currently the component supports SIM800, BG96, SIM7600.
## Use cases
Users could 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 modules 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 the data mode, while other to command mode.
### DTE's
Currently we support only UART, 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-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.

View File

@ -0,0 +1,15 @@
Advanced esp-modem use cases
============================
Create custom modem instance with DCE factory
---------------------------------------------
Create custom module
--------------------
Create new communication interface
----------------------------------

View File

@ -0,0 +1,40 @@
.. _c_api:
API Guide for C interface
=========================
C API is very simple and consist of these two basic parts:
- :ref:`lifecycle_api`
- :ref:`modem_commands`
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`)
.. _lifecycle_api:
Lifecycle API
-------------
These functions are used to create, destroy and set modem working 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.
.. doxygenfile:: c_api.h

50
esp_modem/docs/c_api.h Normal file
View File

@ -0,0 +1,50 @@
// 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
// --- DCE command documentation starts here ---
/**
* @brief Sends the supplied PIN code
*
* @param pin Pin
*
*/ command_result esp_modem_set_pin (const char* pin); /**
* @brief Checks if the SIM needs a PIN
*
* @param[out] pin_ok Pin
*/ command_result esp_modem_read_pin (bool* pin_ok); /**
* @brief Reads the module name
*
* @param[out] name module name
*/ command_result esp_modem_set_echo (const bool x); /**
* @brief Reads the module name
*
* @param[out] name module name
*/ command_result esp_modem_resume_data_mode (); /**
* @brief Reads the module name
*
* @param[out] name module name
*/ command_result esp_modem_set_pdp_context (struct PdpContext* x); /**
* @brief Reads the module name
*
* @param[out] name module name
*/ command_result esp_modem_set_command_mode (); /**
* @brief Reads the module name
*
* @param[out] name module name
*/ command_result esp_modem_set_cmux (); /**
* @brief Reads the module name
*
* @param[out] name module name
*/ command_result esp_modem_get_imsi (char* x); /**
* @brief Reads the module name
*
* @param[out] name module name
*/ command_result esp_modem_get_imei (char* x); /**
* @brief Reads the module name
*
* @param[out] name module name
*/ command_result esp_modem_get_module_name (char* name); /**
* @brief Sets the modem to data mode
*
*/ command_result esp_modem_set_data_mode (); /**
* @brief Get Signal quality
*
*/ command_result esp_modem_get_signal_quality (int* x, int* y);

27
esp_modem/docs/conf.py Normal file
View File

@ -0,0 +1,27 @@
# -*- coding: utf-8 -*-
#
# English Language RTD & Sphinx config file
#
import os
import os.path
import re
import subprocess
import sys
# General information about the project.
project = u'ESP-MODEM Documentation'
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' ]
breathe_projects = {'esp_modem': 'xml'}
breathe_default_project = "esp_modem"
source_suffix = ['.rst', '.md']
source_parsers = {'.md': 'recommonmark.parser.CommonMarkParser', }

60
esp_modem/docs/cpp_api.h Normal file
View File

@ -0,0 +1,60 @@
// --- DCE command documentation starts here ---
class DCE: public DCE_T<GenericModule> {
public:
using DCE_T<GenericModule>::DCE_T;
/**
* @brief Sends the supplied PIN code
*
* @param pin Pin
*
*/ command_result set_pin (const std::string& pin); /**
* @brief Checks if the SIM needs a PIN
*
* @param[out] pin_ok Pin
*/ command_result read_pin (bool& pin_ok); /**
* @brief Reads the module name
*
* @param[out] name module name
*/ command_result set_echo (const bool x); /**
* @brief Reads the module name
*
* @param[out] name module name
*/ command_result resume_data_mode (); /**
* @brief Reads the module name
*
* @param[out] name module name
*/ command_result set_pdp_context (PdpContext& x); /**
* @brief Reads the module name
*
* @param[out] name module name
*/ command_result set_command_mode (); /**
* @brief Reads the module name
*
* @param[out] name module name
*/ command_result set_cmux (); /**
* @brief Reads the module name
*
* @param[out] name module name
*/ command_result get_imsi (std::string& x); /**
* @brief Reads the module name
*
* @param[out] name module name
*/ command_result get_imei (std::string& x); /**
* @brief Reads the module name
*
* @param[out] name module name
*/ command_result get_module_name (std::string& name); /**
* @brief Sets the modem to data mode
*
*/ command_result set_data_mode (); /**
* @brief Get Signal quality
*
*/ command_result get_signal_quality (int& x, int& y);
};

View File

@ -0,0 +1,39 @@
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
Create DTE and DCE
------------------
.. doxygengroup:: ESP_MODEM_INIT_DTE
.. doxygengroup:: ESP_MODEM_INIT_DCE
Mode switching commands
-----------------------
.. doxygenclass:: esp_modem::DCE_T
:members:
Modem commands
--------------
Create the DCE object with DCE factory :cpp:func:`esp_modem_new`
.. doxygenclass:: DCE
:members:
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.

2
esp_modem/docs/generate_docs Executable file
View File

@ -0,0 +1,2 @@
python -u -m sphinx.cmd.build -b html . html

11
esp_modem/docs/index.rst Normal file
View File

@ -0,0 +1,11 @@
ESP-MODEM Documentation
=======================
.. toctree::
Brief intro <README>
C interface <api_docs>
C++ interface <cxx_api_docs>
Advanced use cases <advanced_api>
Internal design <internal_design>