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!

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


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
  • configDTE 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_idTerminal 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

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.

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 &#8212; the modem is supposed to send AT commands in this mode

enumerator DATA_MODE

Data mode &#8212; the modem communicates with network interface on PPP protocol

enumerator DUAL_MODE

Dual mode &#8212; the modem has two real terminals. Data and commands work at the same time

enumerator CMUX_MODE

CMUX (Multiplex mode) &#8212; 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 &#8212; just creates two virtual terminals

enumerator CMUX_MANUAL_EXIT

Exits CMUX mode manually &#8212; 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