C++ API Documentation

Similar to the C API Documentation, the basic application workflow consist of

Construction of the DCE
Switching modes
Sending (AT) commands
Destroying the DCE

Create DTE and DCE

group ESP_MODEM_INIT_DTE

Create DTE’s.

Typedefs

using dce_config = ::esp_modem_dce_config 

using dte_config = ::esp_modem_dte_config 

Functions

std::shared_ptr<DTE> create_uart_dte(const dte_config *config)

Create UART DTE.

Parameters:: config – DTE configuration
Returns:: shared ptr to DTE on success nullptr on failure (either due to insufficient memory or wrong dte configuration) if exceptions are disabled the API abort()’s on error

std::shared_ptr<DTE> create_vfs_dte(const dte_config *config)

Create VFS DTE.

Parameters:: config – DTE configuration
Returns:: shared ptr to DTE on success nullptr on failure (either due to insufficient memory or wrong dte configuration) if exceptions are disabled the API abort()’s on error

group ESP_MODEM_INIT_DCE

ESP_MODEM Initialization API for DCE.

Functions

std::unique_ptr<DCE> create_SIM7600_dce(const dce_config *config, std::shared_ptr<DTE> dte, esp_netif_t *netif)

Create DCE based on SIM7600 module.

Parameters:

config – DCE configuration
dte – reference to the communicating DTE
netif – reference to the network interface

Returns:

unique ptr to the created DCE on success nullptr on failure if exceptions are disabled the API abort()’s on error

std::unique_ptr<DCE> create_SIM7070_dce(const dce_config *config, std::shared_ptr<DTE> dte, esp_netif_t *netif): Create DCE based on SIM7070 module.

std::unique_ptr<DCE> create_SIM7000_dce(const dce_config *config, std::shared_ptr<DTE> dte, esp_netif_t *netif): Create DCE based on SIM7000 module.

std::unique_ptr<DCE> create_SIM800_dce(const dce_config *config, std::shared_ptr<DTE> dte, esp_netif_t *netif): Create DCE based on SIM800 module.

std::unique_ptr<DCE> create_BG96_dce(const dce_config *config, std::shared_ptr<DTE> dte, esp_netif_t *netif): Create DCE based on BG96 module.

std::unique_ptr<DCE> create_SQNGM02S_dce(const dce_config *config, std::shared_ptr<DTE> dte, esp_netif_t *netif): Create DCE based on Sequans GM02S module.

std::unique_ptr<DCE> create_generic_dce(const dce_config *config, std::shared_ptr<DTE> dte, esp_netif_t *netif): Create generic DCE.

Mode switching commands

template<class SpecificModule> class DCE_T

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

Modem commands

esp_modem::DCE::sync()
esp_modem::DCE::get_operator_name()
esp_modem::DCE::store_profile()
esp_modem::DCE::set_pin()
esp_modem::DCE::at_raw()
esp_modem::DCE::at()
esp_modem::DCE::read_pin()
esp_modem::DCE::set_echo()
esp_modem::DCE::sms_txt_mode()
esp_modem::DCE::sms_character_set()
esp_modem::DCE::send_sms()
esp_modem::DCE::resume_data_mode()
esp_modem::DCE::set_pdp_context()
esp_modem::DCE::set_command_mode()
esp_modem::DCE::set_cmux()
esp_modem::DCE::get_imsi()
esp_modem::DCE::get_imei()
esp_modem::DCE::get_module_name()
esp_modem::DCE::set_data_mode()
esp_modem::DCE::get_signal_quality()
esp_modem::DCE::set_flow_control()
esp_modem::DCE::hang_up()
esp_modem::DCE::get_battery_status()
esp_modem::DCE::power_down()
esp_modem::DCE::reset()
esp_modem::DCE::set_baud()
esp_modem::DCE::set_operator()()
esp_modem::DCE::set_network_attachment_state()
esp_modem::DCE::get_network_attachment_state()
esp_modem::DCE::set_radio_state()
esp_modem::DCE::get_radio_state()
esp_modem::DCE::set_network_mode()
esp_modem::DCE::set_preferred_mode()
esp_modem::DCE::set_network_bands()
esp_modem::DCE::get_network_system_mode()
esp_modem::DCE::set_gnss_power_mode()
esp_modem::DCE::get_gnss_power_mode()
esp_modem::DCE::config_psm()
esp_modem::DCE::config_network_registration_urc()
esp_modem::DCE::get_network_registration_state()
esp_modem::DCE::config_mobile_termination_error()
esp_modem::DCE::config_edrx()

class DCE : public esp_modem::DCE_T<GenericModule>

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

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

command_result config_psm(int mode, const std::string &tau, const std::string &active_time)

Configure PSM.

Parameters:: mode – [in] psm mode (0 - off, 1 - on, 2 - off & discard stored params)
Returns:: OK, FAIL or TIMEOUT

command_result config_network_registration_urc(int value)

Configure CEREG urc.

Parameters:: value – [in] value = 0 - Disable network URC value = 1 - Enable network URC value = 2 - Enable network URC with location information value = 3 - Enable network URC with location information and EMM cause value = 4 - Enable network URC with location information and PSM value value = 5 - Enable network URC with location information and PSM value, EMM cause

command_result get_network_registration_state(int &state)

Gets the current network registration state.

Parameters:: state – [out] The current network registration state state = 0 - Not registered, MT is not currently searching an operator to register to state = 1 - Registered, home network state = 2 - Not registered, but MT is currently trying to attach or searching an operator to register to state = 3 - Registration denied state = 4 - Unknown state = 5 - Registered, Roaming state = 6 - Registered, for SMS only, home network (NB-IoT only) state = 7 - Registered, for SMS only, roaming (NB-IoT only) state = 8 - Attached for emergency bearer services only state = 9 - Registered for CSFB not preferred, home network state = 10 - Registered for CSFB not preferred, roaming

command_result config_mobile_termination_error(int mode)

Configures the mobile termination error (+CME ERROR)

Parameters:: mode – [in] The form of the final result code mode = 0 - Disable, use and send ERROR instead mode = 1 - Enable, use numeric error values mode = 2 - Enable, result code and use verbose error values

command_result config_edrx(int mode, int access_technology, const std::string &edrx_value)

Configure eDRX.

Parameters:

mode – [in] mode = 0 - Disable mode = 1 - Enable mode = 2 - Enable + URC mode = 3 - Disable + Reset parameter.
access_technology – [in] act = 0 - ACT is not using eDRX (used in URC) act = 1 - EC-GSM-IoT (A/Gb mode) act = 2 - GSM (A/Gb mode) act = 3 - UTRAN (Iu mode) act = 4 - E-UTRAN (WB-S1 mode) act = 5 - E-UTRAN (NB-S1 mode)
edrx_value – [in] nible string containing encoded eDRX time
ptw_value – [in] nible string containing encoded Paging Time Window

Destroy the DCE

The DCE object is created as std::unique_ptr by default and as such doesn’t have to be explicitly destroyed. It simply gets destroyed and cleaned-up automatically if the object goes out of the block scope.