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 esp_modem::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 esp_modem::DCE : 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)

Reads the operator name.

return:

OK, FAIL or TIMEOUT

Parameters:

name – [out] module name

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.

return:

OK, FAIL or TIMEOUT

Parameters:

pin – [in] Pin

command_result read_pin(bool &pin_ok)

Checks if the SIM needs a PIN.

return:

OK, FAIL or TIMEOUT

Parameters:

pin_ok – [out] true if the SIM card doesn’t need a PIN to unlock

command_result set_echo(const bool echo_on)

Sets echo mode.

return:

OK, FAIL or TIMEOUT

Parameters:

echo_on – [in] true if echo mode on (repeats the commands)

command_result sms_txt_mode(const bool txt)

Sets the Txt or Pdu mode for SMS (only txt is supported)

return:

OK, FAIL or TIMEOUT

Parameters:

txt – [in] true if txt mode

command_result sms_character_set()

Sets the default (GSM) charater set.

Returns:

OK, FAIL or TIMEOUT

command_result send_sms(const std::string &number, const std::string &message)

Sends SMS message in txt mode.

return:

OK, FAIL or TIMEOUT

Parameters:

  • number – [in] Phone number to send the message to

  • message – [in] Text message to be sent

command_result resume_data_mode()

Resumes data mode (Switches back to th data mode, which was temporarily suspended)

Returns:

OK, FAIL or TIMEOUT

command_result set_pdp_context(PdpContext &p1)

Sets php context.

return:

OK, FAIL or TIMEOUT

Parameters:

p1 – [in] PdP context struct to setup modem cellular connection

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.

return:

OK, FAIL or TIMEOUT

Parameters:

imsi – [out] Module’s IMSI number

command_result get_imei(std::string &imei)

Reads the IMEI number.

return:

OK, FAIL or TIMEOUT

Parameters:

imei – [out] Module’s IMEI number

command_result get_module_name(std::string &name)

Reads the module name.

return:

OK, FAIL or TIMEOUT

Parameters:

name – [out] module name

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.

return:

OK, FAIL or TIMEOUT

Parameters:

  • rssi – [out] signal strength indication

  • ber – [out] channel bit error rate

command_result set_flow_control(int dce_flow, int dte_flow)

Sets HW control flow.

return:

OK, FAIL or TIMEOUT

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

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.

return:

OK, FAIL or TIMEOUT

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

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.

return:

OK, FAIL or TIMEOUT

Parameters:

baud – [in] Desired baud rate of the DTE

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.

class esp_modem::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

int write(uint8_t *data, size_t len)

Writing to the underlying terminal.

return:

number of bytes written

Parameters:

  • data – Data pointer to write

  • len – Data len to write

int read(uint8_t **d, size_t len)

Reading from the underlying terminal.

return:

number of bytes read

Parameters:

  • d – Returning the data pointer of the received payload

  • len – Length of the data payload

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

bool set_mode(modem_mode m)

Sets the DTE to desired mode (Command/Data/Cmux)

return:

true on success

Parameters:

m – Desired operation mode

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.

return:

OK, FAIL, TIMEOUT

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

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.

Terminal interface

group ESP_MODEM_TERMINAL

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

Enums

enum terminal_error

Terminal errors.

Values:

enumerator BUFFER_OVERFLOW
enumerator CHECKSUM_ERROR
enumerator UNEXPECTED_CONTROL_FLOW
class esp_modem::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.

return:

length of data written

Parameters:

  • data – Data pointer

  • len – Data len

virtual int read(uint8_t *data, size_t len) = 0

Read from the terminal. This function doesn’t block, but return all available data.

return:

length of data actually read

Parameters:

  • data – Data pointer to store the read payload

  • len – Maximum data len to read

CMUX implementation

group ESP_MODEM_CMUX

Definition of CMUX terminal.

Enums

enum cmux_state

CMUX state machine.

Values:

enumerator INIT
enumerator HEADER
enumerator PAYLOAD
enumerator FOOTER
enumerator RECOVER
class esp_modem::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

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.

return:

The actual written length

Parameters:

  • i – Index of the terminal

  • data – Data to write

  • len – Data length to write

class esp_modem::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.

return:

length of data written

Parameters:

  • data – Data pointer

  • len – Data len

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.

return:

length of data actually read

Parameters:

  • data – Data pointer to store the read payload

  • len – Maximum data len to read

Netif

group ESP_MODEM_NETIF

Network interface layer of the esp-modem.

class esp_modem::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 esp_modem::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::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.

class SIM7600 : public esp_modem::GenericModule
#include <esp_modem_dce_module.hpp>

Specific definition of the SIM7600 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 get_battery_status_sim7xxx(CommandableIf *t, int &voltage, int &bcs, int &bcl)

Following commands that are different for some specific modules.

command_result power_down_sim7xxx(CommandableIf *t)
command_result power_down_sim8xx(CommandableIf *t)
command_result set_data_mode_sim8xx(CommandableIf *t)

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

enum 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 esp_modem::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.

return:

OK, FAIL or TIMEOUT

Parameters:

  • command – Command to be sent

  • got_line – callback if a line received

  • time_ms – timeout in milliseconds

class esp_modem::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.

return:

true on success

Parameters:

mode – Desired mode