mirror of
https://github.com/espressif/esp-protocols.git
synced 2025-07-17 04:22:14 +02:00
docs(esp_modem): updated documents to show missed topics
This commit is contained in:
Suren Gabrielyan
@ -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`
|
||||
|
Before Width: | Height: | Size: 26 KiB After Width: | Height: | Size: 26 KiB |
|
Before Width: | Height: | Size: 139 KiB After Width: | Height: | Size: 139 KiB |
132
docs/esp_modem/en/README.rst
Normal file
132
docs/esp_modem/en/README.rst
Normal file
@ -0,0 +1,132 @@
|
||||
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,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.
|
||||
|
||||
|
||||
63
docs/esp_modem/en/internal_design.rst
Normal file
63
docs/esp_modem/en/internal_design.rst
Normal file
@ -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<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
|
||||
|
||||
.. 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
|
||||
308
docs/esp_modem/esp_modem_command_declare.inc
Normal file
308
docs/esp_modem/esp_modem_command_declare.inc
Normal file
@ -0,0 +1,308 @@
|
||||
// Copyright 2021-2022 Espressif Systems (Shanghai) PTE LTD
|
||||
//
|
||||
// Licensed under the Apache License, Version 2.0 (the "License");
|
||||
// you may not use this file except in compliance with the License.
|
||||
// You may obtain a copy of the License at
|
||||
|
||||
// http://www.apache.org/licenses/LICENSE-2.0
|
||||
//
|
||||
// Unless required by applicable law or agreed to in writing, software
|
||||
// distributed under the License is distributed on an "AS IS" BASIS,
|
||||
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||||
// See the License for the specific language governing permissions and
|
||||
// limitations under the License.
|
||||
#pragma once
|
||||
|
||||
#include "esp_modem_command_declare_helper.inc"
|
||||
|
||||
|
||||
#define DECLARE_ALL_COMMAND_APIS(...) \
|
||||
/**
|
||||
* @brief Sends the initial AT sequence to sync up with the device
|
||||
* @return OK, FAIL or TIMEOUT
|
||||
*/ \
|
||||
ESP_MODEM_DECLARE_DCE_COMMAND(sync, command_result, 0) \
|
||||
\
|
||||
/**
|
||||
* @brief Reads the operator name
|
||||
* @param[out] operator name
|
||||
* @param[out] access technology
|
||||
* @return OK, FAIL or TIMEOUT
|
||||
*/ \
|
||||
ESP_MODEM_DECLARE_DCE_COMMAND(get_operator_name, command_result, 2, STRING_OUT(p1, name), INT_OUT(p2, act)) \
|
||||
\
|
||||
/**
|
||||
* @brief Stores current user profile
|
||||
* @return OK, FAIL or TIMEOUT
|
||||
*/ \
|
||||
ESP_MODEM_DECLARE_DCE_COMMAND(store_profile, command_result, 0) \
|
||||
\
|
||||
/**
|
||||
* @brief Sets the supplied PIN code
|
||||
* @param[in] pin Pin
|
||||
* @return OK, FAIL or TIMEOUT
|
||||
*/\
|
||||
ESP_MODEM_DECLARE_DCE_COMMAND(set_pin, command_result, 1, STRING_IN(p1, pin)) \
|
||||
\
|
||||
/**
|
||||
* @brief Execute the supplied AT command
|
||||
* @param[in] at AT command
|
||||
* @param[out] out Command output string
|
||||
* @param[in] timeout AT command timeout in milliseconds
|
||||
* @return OK, FAIL or TIMEOUT
|
||||
*/\
|
||||
ESP_MODEM_DECLARE_DCE_COMMAND(at, command_result, 3, STRING_IN(p1, cmd), STRING_OUT(p2, out), INT_IN(p3, timeout)) \
|
||||
\
|
||||
/**
|
||||
* @brief Checks if the SIM needs a PIN
|
||||
* @param[out] pin_ok true if the SIM card doesn't need a PIN to unlock
|
||||
* @return OK, FAIL or TIMEOUT
|
||||
*/ \
|
||||
ESP_MODEM_DECLARE_DCE_COMMAND(read_pin, command_result, 1, BOOL_OUT(p1, pin_ok)) \
|
||||
\
|
||||
/**
|
||||
* @brief Sets echo mode
|
||||
* @param[in] echo_on true if echo mode on (repeats the commands)
|
||||
* @return OK, FAIL or TIMEOUT
|
||||
*/ \
|
||||
ESP_MODEM_DECLARE_DCE_COMMAND(set_echo, command_result, 1, BOOL_IN(p1, echo_on)) \
|
||||
\
|
||||
/**
|
||||
* @brief Sets the Txt or Pdu mode for SMS (only txt is supported)
|
||||
* @param[in] txt true if txt mode
|
||||
* @return OK, FAIL or TIMEOUT
|
||||
*/ \
|
||||
ESP_MODEM_DECLARE_DCE_COMMAND(sms_txt_mode, command_result, 1, BOOL_IN(p1, txt)) \
|
||||
\
|
||||
/**
|
||||
* @brief Sets the default (GSM) character set
|
||||
* @return OK, FAIL or TIMEOUT
|
||||
*/ \
|
||||
ESP_MODEM_DECLARE_DCE_COMMAND(sms_character_set, command_result, 0) \
|
||||
\
|
||||
/**
|
||||
* @brief Sends SMS message in txt mode
|
||||
* @param[in] number Phone number to send the message to
|
||||
* @param[in] message Text message to be sent
|
||||
* @return OK, FAIL or TIMEOUT
|
||||
*/ \
|
||||
ESP_MODEM_DECLARE_DCE_COMMAND(send_sms, command_result, 2, STRING_IN(p1, number), STRING_IN(p2, message)) \
|
||||
\
|
||||
/**
|
||||
* @brief Resumes data mode (Switches back to the data mode, which was temporarily suspended)
|
||||
* @return OK, FAIL or TIMEOUT
|
||||
*/ \
|
||||
ESP_MODEM_DECLARE_DCE_COMMAND(resume_data_mode, command_result, 0) \
|
||||
\
|
||||
/**
|
||||
* @brief Sets php context
|
||||
* @param[in] p1 PdP context struct to setup modem cellular connection
|
||||
* @return OK, FAIL or TIMEOUT
|
||||
*/ \
|
||||
ESP_MODEM_DECLARE_DCE_COMMAND(set_pdp_context, command_result, 1, STRUCT_OUT(PdpContext, p1)) \
|
||||
\
|
||||
/**
|
||||
* @brief Switches to the command mode
|
||||
* @return OK, FAIL or TIMEOUT
|
||||
*/ \
|
||||
ESP_MODEM_DECLARE_DCE_COMMAND(set_command_mode, command_result, 0) \
|
||||
\
|
||||
/**
|
||||
* @brief Switches to the CMUX mode
|
||||
* @return OK, FAIL or TIMEOUT
|
||||
*/ \
|
||||
ESP_MODEM_DECLARE_DCE_COMMAND(set_cmux, command_result, 0) \
|
||||
\
|
||||
/**
|
||||
* @brief Reads the IMSI number
|
||||
* @param[out] imsi Module's IMSI number
|
||||
* @return OK, FAIL or TIMEOUT
|
||||
*/ \
|
||||
ESP_MODEM_DECLARE_DCE_COMMAND(get_imsi, command_result, 1, STRING_OUT(p1, imsi)) \
|
||||
\
|
||||
/**
|
||||
* @brief Reads the IMEI number
|
||||
* @param[out] imei Module's IMEI number
|
||||
* @return OK, FAIL or TIMEOUT
|
||||
*/ \
|
||||
ESP_MODEM_DECLARE_DCE_COMMAND(get_imei, command_result, 1, STRING_OUT(p1, imei)) \
|
||||
\
|
||||
/**
|
||||
* @brief Reads the module name
|
||||
* @param[out] name module name
|
||||
* @return OK, FAIL or TIMEOUT
|
||||
*/ \
|
||||
ESP_MODEM_DECLARE_DCE_COMMAND(get_module_name, command_result, 1, STRING_OUT(p1, name)) \
|
||||
\
|
||||
/**
|
||||
* @brief Sets the modem to data mode
|
||||
* @return OK, FAIL or TIMEOUT
|
||||
*/ \
|
||||
ESP_MODEM_DECLARE_DCE_COMMAND(set_data_mode, command_result, 0) \
|
||||
\
|
||||
/**
|
||||
* @brief Get Signal quality
|
||||
* @param[out] rssi signal strength indication
|
||||
* @param[out] ber channel bit error rate
|
||||
* @return OK, FAIL or TIMEOUT
|
||||
*/ \
|
||||
ESP_MODEM_DECLARE_DCE_COMMAND(get_signal_quality, command_result, 2, INT_OUT(p1, rssi), INT_OUT(p2, ber)) \
|
||||
\
|
||||
/**
|
||||
* @brief Sets HW control flow
|
||||
* @param[in] dce_flow 0=none, 2=RTS hw flow control of DCE
|
||||
* @param[in] dte_flow 0=none, 2=CTS hw flow control of DTE
|
||||
* @return OK, FAIL or TIMEOUT
|
||||
*/ \
|
||||
ESP_MODEM_DECLARE_DCE_COMMAND(set_flow_control, command_result, 2, INT_IN(p1, dce_flow), INT_IN(p2, dte_flow)) \
|
||||
\
|
||||
/**
|
||||
* @brief Hangs up current data call
|
||||
* @return OK, FAIL or TIMEOUT
|
||||
*/ \
|
||||
ESP_MODEM_DECLARE_DCE_COMMAND(hang_up, command_result, 0) \
|
||||
\
|
||||
/**
|
||||
* @brief Get voltage levels of modem power up circuitry
|
||||
* @param[out] voltage Current status in mV
|
||||
* @param[out] bcs charge status (-1-Not available, 0-Not charging, 1-Charging, 2-Charging done)
|
||||
* @param[out] bcl 1-100% battery capacity, -1-Not available
|
||||
* @return OK, FAIL or TIMEOUT
|
||||
*/ \
|
||||
ESP_MODEM_DECLARE_DCE_COMMAND(get_battery_status, command_result, 3, INT_OUT(p1, voltage), INT_OUT(p2, bcs), INT_OUT(p3, bcl)) \
|
||||
\
|
||||
/**
|
||||
* @brief Power down the module
|
||||
* @return OK, FAIL or TIMEOUT
|
||||
*/ \
|
||||
ESP_MODEM_DECLARE_DCE_COMMAND(power_down, command_result, 0) \
|
||||
\
|
||||
/**
|
||||
* @brief Reset the module
|
||||
* @return OK, FAIL or TIMEOUT
|
||||
*/ \
|
||||
ESP_MODEM_DECLARE_DCE_COMMAND(reset, command_result, 0) \
|
||||
\
|
||||
/**
|
||||
* @brief Configures the baudrate
|
||||
* @param[in] baud Desired baud rate of the DTE
|
||||
* @return OK, FAIL or TIMEOUT
|
||||
*/ \
|
||||
ESP_MODEM_DECLARE_DCE_COMMAND(set_baud, command_result, 1, INT_IN(p1, baud)) \
|
||||
\
|
||||
/**
|
||||
* @brief Force an attempt to connect to a specific operator
|
||||
* @param[in] mode mode of attempt
|
||||
* mode=0 - automatic
|
||||
* mode=1 - manual
|
||||
* mode=2 - deregister
|
||||
* mode=3 - set format for read operation
|
||||
* mode=4 - manual with fallback to automatic
|
||||
* @param[in] format what format the operator is given in
|
||||
* format=0 - long format
|
||||
* format=1 - short format
|
||||
* format=2 - numeric
|
||||
* @param[in] oper the operator to connect to
|
||||
* @return OK, FAIL or TIMEOUT
|
||||
*/ \
|
||||
ESP_MODEM_DECLARE_DCE_COMMAND(set_operator, command_result, 3, INT_IN(p1, mode), INT_IN(p2, format), STRING_IN(p3, oper)) \
|
||||
\
|
||||
/**
|
||||
* @brief Attach or detach from the GPRS service
|
||||
* @param[in] state 1-attach 0-detach
|
||||
* @return OK, FAIL or TIMEOUT
|
||||
*/ \
|
||||
ESP_MODEM_DECLARE_DCE_COMMAND(set_network_attachment_state, command_result, 1, INT_IN(p1, state)) \
|
||||
\
|
||||
/**
|
||||
* @brief Get network attachment state
|
||||
* @param[out] state 1-attached 0-detached
|
||||
* @return OK, FAIL or TIMEOUT
|
||||
*/ \
|
||||
ESP_MODEM_DECLARE_DCE_COMMAND(get_network_attachment_state, command_result, 1, INT_OUT(p1, state)) \
|
||||
\
|
||||
/**
|
||||
* @brief What mode the radio should be set to
|
||||
* @param[in] state state 1-full 0-minimum ...
|
||||
* @return OK, FAIL or TIMEOUT
|
||||
*/ \
|
||||
ESP_MODEM_DECLARE_DCE_COMMAND(set_radio_state, command_result, 1, INT_IN(p1, state)) \
|
||||
\
|
||||
/**
|
||||
* @brief Get current radio state
|
||||
* @param[out] state 1-full 0-minimum ...
|
||||
* @return OK, FAIL or TIMEOUT
|
||||
*/ \
|
||||
ESP_MODEM_DECLARE_DCE_COMMAND(get_radio_state, command_result, 1, INT_OUT(p1, state)) \
|
||||
\
|
||||
/**
|
||||
* @brief Set network mode
|
||||
* @param[in] mode preferred mode
|
||||
* @return OK, FAIL or TIMEOUT
|
||||
*/ \
|
||||
ESP_MODEM_DECLARE_DCE_COMMAND(set_network_mode, command_result, 1, INT_IN(p1, mode)) \
|
||||
\
|
||||
/**
|
||||
* @brief Preferred network mode (CAT-M and/or NB-IoT)
|
||||
* @param[in] mode preferred selection
|
||||
* @return OK, FAIL or TIMEOUT
|
||||
*/ \
|
||||
ESP_MODEM_DECLARE_DCE_COMMAND(set_preferred_mode, command_result, 1, INT_IN(p1, mode)) \
|
||||
\
|
||||
/**
|
||||
* @brief Set network bands for CAT-M or NB-IoT
|
||||
* @param[in] mode CAT-M or NB-IoT
|
||||
* @return OK, FAIL or TIMEOUT
|
||||
*/ \
|
||||
ESP_MODEM_DECLARE_DCE_COMMAND(set_network_bands, command_result, 3, STRING_IN(p1, mode), INTEGER_LIST_IN(p2, bands), INT_IN(p3, size)) \
|
||||
\
|
||||
/**
|
||||
* @brief Show network system mode
|
||||
* @param[out] mode current network mode
|
||||
* @return OK, FAIL or TIMEOUT
|
||||
*/ \
|
||||
ESP_MODEM_DECLARE_DCE_COMMAND(get_network_system_mode, command_result, 1, INT_OUT(p1, mode)) \
|
||||
\
|
||||
/**
|
||||
* @brief GNSS power control
|
||||
* @param[out] mode power mode (0 - off, 1 - on)
|
||||
* @return OK, FAIL or TIMEOUT
|
||||
*/ \
|
||||
ESP_MODEM_DECLARE_DCE_COMMAND(set_gnss_power_mode, command_result, 1, INT_IN(p1, mode)) \
|
||||
\
|
||||
/**
|
||||
* @brief GNSS power control
|
||||
* @param[out] mode power mode (0 - off, 1 - on)
|
||||
* @return OK, FAIL or TIMEOUT
|
||||
*/ \
|
||||
ESP_MODEM_DECLARE_DCE_COMMAND(get_gnss_power_mode, command_result, 1, INT_OUT(p1, mode)) \
|
||||
\
|
||||
|
||||
|
||||
#ifdef GENERATE_DOCS
|
||||
// cat ../include/generate/esp_modem_command_declare.inc | clang++ -E -P -CC -xc++ -I../include -DGENERATE_DOCS - | sed -n '1,/DCE command documentation/!p'
|
||||
// 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
|
||||
|
||||
// call parametrs by names for documentation
|
||||
#undef _ARG
|
||||
#define _ARG(param, name) name
|
||||
// --- DCE command documentation starts here ---
|
||||
#ifdef __cplusplus
|
||||
class esp_modem::DCE : public DCE_T<GenericModule> {
|
||||
public:
|
||||
using DCE_T<GenericModule>::DCE_T;
|
||||
#define ESP_MODEM_DECLARE_DCE_COMMAND(name, return_type, TEMPLATE_ARG, ...) return_type name (__VA_ARGS__);
|
||||
#elif defined(GENERATE_RST_LINKS)
|
||||
#define ESP_MODEM_DECLARE_DCE_COMMAND(name, return_type, TEMPLATE_ARG, ...) NL- :cpp:func:`esp_modem::DCE::name`
|
||||
#else
|
||||
#define ESP_MODEM_DECLARE_DCE_COMMAND(name, return_type, TEMPLATE_ARG, ...) return_type esp_modem_ ## name (__VA_ARGS__);
|
||||
#endif
|
||||
|
||||
DECLARE_ALL_COMMAND_APIS()
|
||||
|
||||
#ifdef __cplusplus
|
||||
};
|
||||
#endif
|
||||
|
||||
#endif
|
||||
26
docs/esp_modem/esp_modem_command_declare_helper.inc
Normal file
26
docs/esp_modem/esp_modem_command_declare_helper.inc
Normal file
@ -0,0 +1,26 @@
|
||||
|
||||
|
||||
// Parameters
|
||||
// * handle different parameters for C++ and C API
|
||||
// * make parameter unique names, so they could be easily referenced and forwarded
|
||||
#define _ARG(param, name) param
|
||||
#define INT_IN(param, name) int _ARG(param, name)
|
||||
#ifdef __cplusplus
|
||||
#include <string>
|
||||
#define STRING_IN(param, name) const std::string& _ARG(param, name)
|
||||
#define STRING_OUT(param, name) std::string& _ARG(param, name)
|
||||
#define BOOL_IN(param, name) const bool _ARG(param, name)
|
||||
#define BOOL_OUT(param, name) bool& _ARG(param, name)
|
||||
#define INT_OUT(param, name) int& _ARG(param, name)
|
||||
#define INTEGER_LIST_IN(param, name) const int* _ARG(param, name)
|
||||
|
||||
#define STRUCT_OUT(struct_name, p1) struct_name& p1
|
||||
#else
|
||||
#define STRING_IN(param, name) const char* _ARG(param, name)
|
||||
#define STRING_OUT(param, name) char* _ARG(param, name)
|
||||
#define BOOL_IN(param, name) const bool _ARG(param, name)
|
||||
#define BOOL_OUT(param, name) bool* _ARG(param, name)
|
||||
#define INT_OUT(param, name) int* _ARG(param, name)
|
||||
#define INTEGER_LIST_IN(param, name) const int* _ARG(param, name)
|
||||
#define STRUCT_OUT(struct_name, p1) esp_modem_ ## struct_name ## _t* p1
|
||||
#endif
|
||||
@ -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 "<script type="text/javascript">
|
||||
#window.onload =(function() {
|
||||
# var myAnchor = document.getElementById('version-select');
|
||||
# var mySpan = document.createElement('input');
|
||||
# mySpan.setAttribute('type', 'text');
|
||||
# mySpan.setAttribute('maxLength', '10');
|
||||
# mySpan.value = 'latest';
|
||||
# mySpan.setAttribute('disabled', true);
|
||||
# myAnchor.parentNode.replaceChild(mySpan, myAnchor);
|
||||
#
|
||||
# var myAnchor = document.getElementById('target-select');
|
||||
# var mySpan = document.createElement('input');
|
||||
# mySpan.setAttribute('type', 'text');
|
||||
# mySpan.setAttribute('maxLength', '10');
|
||||
# mySpan.value = 'all targets';
|
||||
# mySpan.setAttribute('disabled', true);
|
||||
# myAnchor.parentNode.replaceChild(mySpan, myAnchor);
|
||||
#
|
||||
#})();
|
||||
#</script>" >> html/index.html
|
||||
|
||||
# Modifes some version and target fields of index.html
|
||||
echo "<script type="text/javascript">
|
||||
echo "<script type='text/javascript'>
|
||||
window.onload =(function() {
|
||||
var myAnchor = document.getElementById('version-select');
|
||||
var mySpan = document.createElement('input');
|
||||
mySpan.setAttribute('type', 'text');
|
||||
mySpan.setAttribute('maxLength', '10');
|
||||
mySpan.value = 'latest';
|
||||
mySpan.setAttribute('disabled', true);
|
||||
var mySpan = document.createElement('select');
|
||||
mySpan.style.float = 'left';
|
||||
|
||||
latest_ver = document.createElement('option');
|
||||
latest_ver.value = 'latest';
|
||||
latest_ver.textContent = 'latest(master)';
|
||||
mySpan.append(latest_ver);
|
||||
|
||||
var myArray = ['v1.0.0''];
|
||||
for (var i = myArray.length - 1; i >= 0; i--) {
|
||||
current_ver = document.createElement('option');
|
||||
current_ver.value = myArray[i];
|
||||
current_ver.textContent = 'release-'+myArray[i];
|
||||
mySpan.append(current_ver);
|
||||
}
|
||||
|
||||
|
||||
myAnchor.parentNode.replaceChild(mySpan, myAnchor);
|
||||
mySpan.addEventListener('change', function() {
|
||||
window.location.href='https://docs.espressif.com/projects/esp-protocols/esp_modem/docs/'+event.target.value+'/index.html'
|
||||
});
|
||||
|
||||
var myAnchor = document.getElementById('target-select');
|
||||
var mySpan = document.createElement('input');
|
||||
mySpan.style.float = 'left';
|
||||
mySpan.setAttribute('type', 'text');
|
||||
mySpan.setAttribute('maxLength', '10');
|
||||
mySpan.value = 'all targets';
|
||||
@ -23,4 +74,4 @@ window.onload =(function() {
|
||||
myAnchor.parentNode.replaceChild(mySpan, myAnchor);
|
||||
|
||||
})();
|
||||
</script>" >> html/index.html
|
||||
</script>" >> html/index.html
|
||||
|
||||
Reference in New Issue
Block a user