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:
DTE to communicate with the device on a specific Terminal interface such as UART.
Netif to provide the network connectivity
Module 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 Module section, as Adding new module or command
- group ESP_MODEM_DCE
Definition of DCE abstraction.
-
class DCE_Mode
- #include <esp_modem_dce.hpp>
Helper class responsible for switching modes of the DCE’s.
-
template<class SpecificModule>
class DCE_T - #include <esp_modem_dce.hpp>
General DCE class templated on a specific module. It is responsible for all the necessary transactions related to switching modes and consequent synergy with aggregated objects of DTE, Netif and a specific Module.
Public Functions
-
inline void set_data()
Set data mode!
-
inline void set_data()
-
class DCE : public esp_modem::DCE_T<GenericModule>, public esp_modem::DCE_T<GenericModule>
- #include <esp_modem_dce.hpp>
Common abstraction of the modem DCE, specialized by the GenericModule which is a parent class for the supported devices and most common modems, as well.
Public Functions
-
command_result sync()
Sends the initial AT sequence to sync up with the device.
- Returns
OK, FAIL or TIMEOUT
-
command_result get_operator_name(std::string &name, int &act)
Reads the operator name.
- Parameters
name – [out] operator name
act – [out] access technology
- Returns
OK, FAIL or TIMEOUT
-
command_result store_profile()
Stores current user profile.
- Returns
OK, FAIL or TIMEOUT
-
command_result set_pin(const std::string &pin)
Sets the supplied PIN code.
- Parameters
pin – [in] Pin
- Returns
OK, FAIL or TIMEOUT
-
command_result at_raw(const std::string &cmd, std::string &out, const std::string &pass, const std::string &fail, int timeout)
Execute the supplied AT command in raw mode (doesn’t append ‘\r’ to command, returns everything)
-
command_result at(const std::string &cmd, std::string &out, int timeout)
Execute the supplied AT command.
- Parameters
cmd – [in] AT command
out – [out] Command output string
timeout – [in] AT command timeout in milliseconds
- Returns
OK, FAIL or TIMEOUT
-
command_result read_pin(bool &pin_ok)
Checks if the SIM needs a PIN.
- Parameters
pin_ok – [out] true if the SIM card doesn’t need a PIN to unlock
- Returns
OK, FAIL or TIMEOUT
-
command_result set_echo(const bool echo_on)
Sets echo mode.
- Parameters
echo_on – [in] true if echo mode on (repeats the commands)
- Returns
OK, FAIL or TIMEOUT
-
command_result sms_txt_mode(const bool txt)
Sets the Txt or Pdu mode for SMS (only txt is supported)
- Parameters
txt – [in] true if txt mode
- Returns
OK, FAIL or TIMEOUT
-
command_result sms_character_set()
Sets the default (GSM) character set.
- Returns
OK, FAIL or TIMEOUT
-
command_result send_sms(const std::string &number, const std::string &message)
Sends SMS message in txt mode.
- Parameters
number – [in] Phone number to send the message to
message – [in] Text message to be sent
- Returns
OK, FAIL or TIMEOUT
-
command_result resume_data_mode()
Resumes data mode (Switches back to the data mode, which was temporarily suspended)
- Returns
OK, FAIL or TIMEOUT
-
command_result set_pdp_context(PdpContext &p1)
Sets php context.
- Parameters
p1 – [in] PdP context struct to setup modem cellular connection
- Returns
OK, FAIL or TIMEOUT
-
command_result set_command_mode()
Switches to the command mode.
- Returns
OK, FAIL or TIMEOUT
-
command_result set_cmux()
Switches to the CMUX mode.
- Returns
OK, FAIL or TIMEOUT
-
command_result get_imsi(std::string &imsi)
Reads the IMSI number.
- Parameters
imsi – [out] Module’s IMSI number
- Returns
OK, FAIL or TIMEOUT
-
command_result get_imei(std::string &imei)
Reads the IMEI number.
- Parameters
imei – [out] Module’s IMEI number
- Returns
OK, FAIL or TIMEOUT
-
command_result get_module_name(std::string &name)
Reads the module name.
- Parameters
name – [out] module name
- Returns
OK, FAIL or TIMEOUT
-
command_result set_data_mode()
Sets the modem to data mode.
- Returns
OK, FAIL or TIMEOUT
-
command_result get_signal_quality(int &rssi, int &ber)
Get Signal quality.
- Parameters
rssi – [out] signal strength indication
ber – [out] channel bit error rate
- Returns
OK, FAIL or TIMEOUT
-
command_result set_flow_control(int dce_flow, int dte_flow)
Sets HW control flow.
-
command_result hang_up()
Hangs up current data call.
- Returns
OK, FAIL or TIMEOUT
-
command_result get_battery_status(int &voltage, int &bcs, int &bcl)
Get voltage levels of modem power up circuitry.
- Parameters
voltage – [out] Current status in mV
bcs – [out] charge status (-1-Not available, 0-Not charging, 1-Charging, 2-Charging done)
bcl – [out] 1-100% battery capacity, -1-Not available
- Returns
OK, FAIL or TIMEOUT
-
command_result power_down()
Power down the module.
- Returns
OK, FAIL or TIMEOUT
-
command_result reset()
Reset the module.
- Returns
OK, FAIL or TIMEOUT
-
command_result set_baud(int baud)
Configures the baudrate.
- Parameters
baud – [in] Desired baud rate of the DTE
- Returns
OK, FAIL or TIMEOUT
-
command_result set_operator(int mode, int format, const std::string &oper)
Force an attempt to connect to a specific operator.
- Parameters
mode – [in] 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
format – [in] what format the operator is given in format=0 - long format format=1 - short format format=2 - numeric
oper – [in] the operator to connect to
- Returns
OK, FAIL or TIMEOUT
-
command_result set_network_attachment_state(int state)
Attach or detach from the GPRS service.
- Parameters
state – [in] 1-attach 0-detach
- Returns
OK, FAIL or TIMEOUT
-
command_result get_network_attachment_state(int &state)
Get network attachment state.
- Parameters
state – [out] 1-attached 0-detached
- Returns
OK, FAIL or TIMEOUT
-
command_result set_radio_state(int state)
What mode the radio should be set to.
- Parameters
state – [in] state 1-full 0-minimum …
- Returns
OK, FAIL or TIMEOUT
-
command_result get_radio_state(int &state)
Get current radio state.
- Parameters
state – [out] 1-full 0-minimum …
- Returns
OK, FAIL or TIMEOUT
-
command_result set_network_mode(int mode)
Set network mode.
- Parameters
mode – [in] preferred mode
- Returns
OK, FAIL or TIMEOUT
-
command_result set_preferred_mode(int mode)
Preferred network mode (CAT-M and/or NB-IoT)
- Parameters
mode – [in] preferred selection
- Returns
OK, FAIL or TIMEOUT
-
command_result set_network_bands(const std::string &mode, const int *bands, int size)
Set network bands for CAT-M or NB-IoT.
- Parameters
mode – [in] CAT-M or NB-IoT
bands – [in] bitmap in hex representing bands
size – [in] size of teh bands bitmap
- Returns
OK, FAIL or TIMEOUT
-
command_result get_network_system_mode(int &mode)
Show network system mode.
- Parameters
mode – [out] current network mode
- Returns
OK, FAIL or TIMEOUT
-
command_result set_gnss_power_mode(int mode)
GNSS power control.
- Parameters
mode – [out] power mode (0 - off, 1 - on)
- Returns
OK, FAIL or TIMEOUT
-
command_result get_gnss_power_mode(int &mode)
GNSS power control.
- Parameters
mode – [out] power mode (0 - off, 1 - on)
- Returns
OK, FAIL or TIMEOUT
-
command_result sync()
-
class DCE_Mode
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
- group ESP_MODEM_DTE
Definition of DTE and related classes.
-
struct DTE_Command
- #include <esp_modem_dte.hpp>
-
class DTE : public esp_modem::CommandableIf
- #include <esp_modem_dte.hpp>
DTE (Data Terminal Equipment) class
Public Functions
-
explicit DTE(const esp_modem_dte_config *config, std::unique_ptr<Terminal> t)
Creates a DTE instance from the terminal.
-
virtual int write(uint8_t *data, size_t len) override
Writing to the underlying terminal.
- Parameters
data – Data pointer to write
len – Data len to write
- Returns
number of bytes written
-
int send(uint8_t *data, size_t len, int term_id = 1)
send data to the selected terminal, by default (without term_id argument) this API works the same as write: sends data to the secondary terminal, which is typically used as data terminal (for networking).
- Parameters
data – Data pointer to write
len – Data len to write
term_id – Terminal id: Primary if id==0, Secondary if id==1
- Returns
number of bytes written
-
int read(uint8_t **d, size_t len)
Reading from the underlying terminal.
- Parameters
d – Returning the data pointer of the received payload
len – Length of the data payload
- Returns
number of bytes read
-
void set_read_cb(std::function<bool(uint8_t *data, size_t len)> f)
Sets read callback with valid data and length.
- Parameters
f – Function to be called on data available
-
virtual void on_read(got_line_cb on_data) override
Sets read callback for manual command processing Note that this API also locks the command API, which can only be used after you remove the callback by dte->on_read(nullptr)
- Parameters
on_data – Function to be called when a command response is available
-
void set_error_cb(std::function<void(terminal_error err)> f)
Sets DTE error callback.
- Parameters
f – Function to be called on DTE error
-
bool set_mode(modem_mode m)
Sets the DTE to desired mode (Command/Data/Cmux)
- Parameters
m – Desired operation mode
- Returns
true on success
-
virtual command_result command(const std::string &command, got_line_cb got_line, uint32_t time_ms) override
Sends command and provides callback with responding line.
- Parameters
command – String parameter representing command
got_line – Function to be called after line available as a response
time_ms – Time in ms to wait for the answer
- Returns
OK, FAIL, TIMEOUT
-
virtual command_result command(const std::string &command, got_line_cb got_line, uint32_t time_ms, char separator) override
Sends the command (same as above) but with a specific separator.
-
explicit DTE(const esp_modem_dte_config *config, std::unique_ptr<Terminal> t)
-
struct DTE_Command
Terminal interface
- group ESP_MODEM_TERMINAL
Definition of an abstract terminal to be attached to DTE class.
Enums
-
class Terminal
- #include <esp_modem_terminal.hpp>
Terminal interface. All communication interfaces must comply to this interface in order to be used as a DTE.
Subclassed by esp_modem::CMuxInstance
Public Functions
-
virtual int write(uint8_t *data, size_t len) = 0
Writes data to the terminal.
- Parameters
data – Data pointer
len – Data len
- Returns
length of data written
-
virtual int read(uint8_t *data, size_t len) = 0
Read from the terminal. This function doesn’t block, but return all available data.
- Parameters
data – Data pointer to store the read payload
len – Maximum data len to read
- Returns
length of data actually read
-
virtual int write(uint8_t *data, size_t len) = 0
-
class Terminal
CMUX implementation
- group ESP_MODEM_CMUX
Definition of CMUX terminal.
Enums
-
class CMux
- #include <esp_modem_cmux.hpp>
CMux class which consumes the original terminal and creates multiple virtual terminals from it. This class itself is not usable as a DTE terminal, only via its instances defined in
CMuxInstance
Public Functions
-
std::pair<std::shared_ptr<Terminal>, unique_buffer> detach()
Ejects the attached terminal and buffer, so they could be used as traditional command/data DTE’s.
- Returns
pair of the original terminal and buffer
-
void set_read_cb(int inst, std::function<bool(uint8_t *data, size_t len)> f)
Sets read callback for the appropriate terminal.
- Parameters
inst – Index of the terminal
f – function pointer
-
int write(int i, uint8_t *data, size_t len)
Writes to the appropriate terminal.
- Parameters
i – Index of the terminal
data – Data to write
len – Data length to write
- Returns
The actual written length
-
bool recover()
Recovers the protocol.
This restarts the CMUX state machine, which could have been in a wrong state due to communication issue on a lower layer.
- Returns
true on success
-
std::pair<std::shared_ptr<Terminal>, unique_buffer> detach()
-
class CMuxInstance : public esp_modem::Terminal
- #include <esp_modem_cmux.hpp>
This represents a specific instance of a CMUX virtual terminal. This class also implements Terminal interface and as such could be used as a DTE’s terminal.
Public Functions
-
inline virtual int write(uint8_t *data, size_t len) override
Writes data to the terminal.
- Parameters
data – Data pointer
len – Data len
- Returns
length of data written
-
inline virtual int read(uint8_t *data, size_t len) override
Read from the terminal. This function doesn’t block, but return all available data.
- Parameters
data – Data pointer to store the read payload
len – Maximum data len to read
- Returns
length of data actually read
-
inline virtual int write(uint8_t *data, size_t len) override
-
class CMux
Netif
Module abstraction
- group ESP_MODEM_MODULE
Definition of modules representing specific modem devices.
-
class GenericModule : public esp_modem::ModuleIf
- #include <esp_modem_dce_module.hpp>
This is a basic building block for custom modules as well as for the supported modules in the esp-modem component It derives from the ModuleIf.
Subclassed by esp_modem::BG96, esp_modem::SIM7000, esp_modem::SIM7070, esp_modem::SIM7600, esp_modem::SIM800
Public Functions
We can construct a generic device with an existent DTE and it’s configuration The configuration could be either the dce-config struct or just a pdp context.
-
inline virtual bool setup_data_mode() override
This is a mandatory method for ModuleIf class, which sets up the device to be able to connect to the network. This typically consists of setting basic communication parameters and setting the PDP (defining logical access point to cellular network)
-
inline virtual bool set_mode(modem_mode mode) override
This is a mandatory method of ModuleIf class, which defines basic commands for switching between DATA, COMMAND and CMUX modes.
-
inline void configure_pdp_context(std::unique_ptr<PdpContext> new_pdp)
Additional method providing runtime configuration of PDP context.
-
inline command_result get_operator_name(std::string &name)
Simplified version of operator name (without the ACT, which is included in the command library)
-
class SIM7600 : public esp_modem::GenericModule
- #include <esp_modem_dce_module.hpp>
Specific definition of the SIM7600 module.
-
class SIM7070 : public esp_modem::GenericModule
- #include <esp_modem_dce_module.hpp>
Specific definition of the SIM7070 module.
-
class SIM7000 : public esp_modem::GenericModule
- #include <esp_modem_dce_module.hpp>
Specific definition of the SIM7000 module.
-
class SIM800 : public esp_modem::GenericModule
- #include <esp_modem_dce_module.hpp>
Specific definition of the SIM800 module.
-
class BG96 : public esp_modem::GenericModule
- #include <esp_modem_dce_module.hpp>
Specific definition of the BG96 module.
-
class GenericModule : public esp_modem::ModuleIf
Adding new devices
To support a new module, developers would have to implement a new class derived from esp_modem::GenericModule
the same way
as it is described in the Advanced user manual. 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 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 C API Documentation for the list of supported commands.
- group ESP_MODEM_DCE_COMMAND
Library of the most useful DCE commands.
Defines
-
ESP_MODEM_DECLARE_DCE_COMMAND(name, return_type, num, ...)
Declaration of all commands is generated from esp_modem_command_declare.inc.
Functions
-
command_result generic_command(CommandableIf *t, const std::string &command, const std::string &pass_phrase, const std::string &fail_phrase, uint32_t timeout_ms)
Generic AT command to be send with pass and fail phrases.
- Parameters
t – Commandable object (anything that can accept commands)
command – Command to be sent do the commandable object
pass_phrase – String to be present in the reply to pass this command
fail_phrase – String to be present in the reply to fail this command
timeout_ms – Timeout in ms
-
command_result get_battery_status_sim7xxx(CommandableIf *t, int &voltage, int &bcs, int &bcl)
Following commands that are different for some specific modules.
-
command_result set_gnss_power_mode_sim76xx(CommandableIf *t, int mode)
-
command_result power_down_sim76xx(CommandableIf *t)
-
command_result power_down_sim70xx(CommandableIf *t)
-
command_result set_network_bands_sim76xx(CommandableIf *t, const std::string &mode, const int *bands, int size)
-
command_result power_down_sim8xx(CommandableIf *t)
-
command_result set_data_mode_alt(CommandableIf *t)
-
command_result set_pdp_context(CommandableIf *t, PdpContext &pdp, uint32_t timeout_ms)
-
ESP_MODEM_DECLARE_DCE_COMMAND(name, return_type, num, ...)
Modem types
- group ESP_MODEM_TYPES
Basic type definitions used in esp-modem.
Typedefs
-
typedef std::function<command_result(uint8_t *data, size_t len)> got_line_cb
Enums
-
enum class modem_mode
Modem working mode.
Values:
-
enumerator UNDEF
-
enumerator COMMAND_MODE
Command mode — the modem is supposed to send AT commands in this mode
-
enumerator DATA_MODE
Data mode — the modem communicates with network interface on PPP protocol
-
enumerator DUAL_MODE
Dual mode — the modem has two real terminals. Data and commands work at the same time
-
enumerator CMUX_MODE
CMUX (Multiplex mode) — Simplified CMUX mode, which creates two virtual terminals, assigning one solely to command interface and the other to the data mode
-
enumerator CMUX_MANUAL_MODE
Enter CMUX mode manually — just creates two virtual terminals
-
enumerator CMUX_MANUAL_EXIT
Exits CMUX mode manually — just destroys two virtual terminals
-
enumerator CMUX_MANUAL_DATA
Sets the primary terminal to DATA mode in manual CMUX
-
enumerator CMUX_MANUAL_COMMAND
Sets the primary terminal to COMMAND mode in manual CMUX
-
enumerator CMUX_MANUAL_SWAP
Swaps virtual terminals in manual CMUX mode (primary <-> secondary)
-
enumerator RESUME_DATA_MODE
This is used when the device is already in DATA mode and we need the modem lib to enter the mode without switching. On success, we would end up in DATA-mode, UNDEF otherwise
-
enumerator RESUME_COMMAND_MODE
This is used when the device is already in COMMAND mode and we want to resume it On success, we would end up in DATA-mode, UNDEF otherwise
-
enumerator RESUME_CMUX_MANUAL_MODE
This is used when the device is already in CMUX mode and we need the modem lib to enter it without switching. On success, we would end up in CMUX_MANUAL-mode, UNDEF otherwise
-
enumerator RESUME_CMUX_MANUAL_DATA
This is used when the device is already in CMUX-DATA mode and we need the modem lib to enter it without switching. On success, we would end up in CMUX_MANUAL-DATA mode, UNDEF otherwise
-
enumerator AUTODETECT
Auto-detection command: It tries to send a few packets in order to recognize which mode the the device currently is and update the modem library mode. On success the modem is updated, otherwise it’s set to UNDEF
-
enumerator UNDEF
-
struct PdpContext
- #include <esp_modem_types.hpp>
PDP context used for configuring and setting the data mode up.
-
class CommandableIf
- #include <esp_modem_types.hpp>
Interface for classes eligible to send AT commands (Modules, DCEs, DTEs)
Subclassed by esp_modem::DTE
Public Functions
-
virtual command_result command(const std::string &command, got_line_cb got_line, uint32_t time_ms, const char separator) = 0
Sends custom AT command.
- Parameters
command – Command to be sent
got_line – callback if a line received
time_ms – timeout in milliseconds
separator –
Character treated as a line separator, typically ‘
’
- Returns
OK, FAIL or TIMEOUT
-
virtual command_result command(const std::string &command, got_line_cb got_line, uint32_t time_ms, const char separator) = 0
-
class ModuleIf
- #include <esp_modem_types.hpp>
Interface for classes implementing a module for the modem.
Subclassed by esp_modem::GenericModule
Public Functions
-
virtual bool setup_data_mode() = 0
Sets the data mode up (provides the necessary configuration to connect to the cellular network)
- Returns
true on success
-
virtual bool set_mode(modem_mode mode) = 0
Sets the operation mode.
- Parameters
mode – Desired mode
- Returns
true on success
-
virtual bool setup_data_mode() = 0
-
typedef std::function<command_result(uint8_t *data, size_t len)> got_line_cb