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 command_result pause_netif(bool do_pause, bool force = false, int delay = 1000)

Pauses/Unpauses network temporarily.

Parameters

do_pause – true to pause, false to unpause
force – true to ignore command failures and continue

Returns

command_result of the underlying commands

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)

Parameters

cmd – [in] String command that’s send to DTE
out – [out] Raw output from DTE
pass – [in] Pattern in response for the API to return OK
fail – [in] Pattern in response for the API to return FAIL
timeout – [in] AT command timeout in milliseconds

Returns

OK, FAIL or TIMEOUT

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.

Parameters

dce_flow – [in] 0=none, 2=RTS hw flow control of DCE
dte_flow – [in] 0=none, 2=CTS hw flow control of DTE

Returns

OK, FAIL or TIMEOUT

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

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

Terminal interface
CMUX implementation

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.

Parameters

config – DTE config structure
t – unique-ptr to Terminal
s – unique-ptr to secondary 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.

bool recover()

Allows this DTE to recover from a generic connection issue.

Returns: true if success

void set_command_callbacks(): Set internal command callbacks to the underlying terminal. Here we capture command replies to be processed by supplied command callbacks in struct command_cb.

Terminal interface

group ESP_MODEM_TERMINAL

Definition of an abstract terminal to be attached to DTE class.

Enums

enum class terminal_error

Terminal errors.

Values:

enumerator BUFFER_OVERFLOW

enumerator CHECKSUM_ERROR

enumerator UNEXPECTED_CONTROL_FLOW

enumerator DEVICE_GONE

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

CMUX implementation

group ESP_MODEM_CMUX

Definition of CMUX terminal.

Enums

enum class cmux_state

CMUX state machine.

Values:

enumerator INIT

enumerator HEADER

enumerator PAYLOAD

enumerator FOOTER

enumerator RECOVER

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

bool init()

Initializes CMux protocol.

Returns: true on success

bool deinit()

Closes and deinits CMux protocol.

Returns: true on success

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

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

Netif

group ESP_MODEM_NETIF

Network interface layer of the esp-modem.

class Netif

#include <esp_modem_netif.hpp>

Network interface class responsible to glue the esp-netif to the modem’s DCE.

Public Functions

void start(): Start the network interface.

void wait_until_ppp_exits(): Blocks until the network interface closes.

void stop(): Stop the network interface.

void pause(): Pause the network interface.

void resume(): Resume the network interface.

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

inline explicit GenericModule(std::shared_ptr<DTE> dte, std::unique_ptr<PdpContext> pdp): 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.

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)

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

enum class command_result

Module command result.

Values:

enumerator OK: The command completed successfully

enumerator FAIL: The command explicitly failed

enumerator TIMEOUT: The device didn’t respond in the specified timeline

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

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