Advanced esp-modem use cases

This chapter outlines basic extensibility of the esp-modem component.

Custom instantiation with DCE factory

It is possible to create a modem handle in many different ways:

  • Build a DCE on top a generic module, user defined module or build the module only (in case the application will only use AT command interface)

  • Create the DCE as a shared, unique or a vanilla pointer

  • Create a generic DCE or a templated DCE_T of a specific module (this could be one of the supported modules or a user defined module)

All the functionality is provided by the DCE factory

group ESP_MODEM_DCE_FACTORY

DCE modem factory.

Enums

enum class ModemType

Specific modem choice when creating by the Factory.

Values:

enumerator GenericModule

Default generic module with the most common commands

enumerator SIM7600

Derived from the GenericModule, specifics applied to SIM7600 model

enumerator SIM7070

Derived from the GenericModule, specifics applied to SIM7070 model

enumerator SIM7000

Derived from the GenericModule, specifics applied to SIM7000 model

enumerator BG96

Derived from the GenericModule, specifics applied to BG69 model

enumerator SIM800

Derived from the GenericModule with specifics applied to SIM800 model

class FactoryHelper
#include <esp_modem_dce_factory.hpp>

Helper class for creating a user define pointer in a specific way, either as a plain pointer, shared_ptr or unique_ptr.

template<typename T_Module>
class Creator
#include <esp_modem_dce_factory.hpp>

Creator class for building a DCE_T<Module> in a specific way, either from a Module object or by default from the DTE and netif.

Throws :

class Factory
#include <esp_modem_dce_factory.hpp>

Factory class for creating virtual DCE objects based on the configuration of the supplied module. This could also be used to create a custom module or a DCE_T<module>, provided user app derives from this factory.

Public Functions

template<typename ...Args>
inline std::unique_ptr<DCE> build_unique(const config *cfg, Args&&... args)

Create a default unique_ptr DCE generically, with the chosen module derived from the GenericModule.

Template Parameters:

Args – Arguments to the builder, i.e. constructor of esp_modem::DCE_T class

Parameters:
Returns:

unique_ptr DCE of the created DCE on success

Public Static Functions

template<typename T_Module, typename ...Args>
static inline std::unique_ptr<DCE> build_unique(const config *cfg, Args&&... args)

Create a default unique_ptr DCE in a specific way (from the module)

Template Parameters:

  • Module – Specific Module used in this DCE

  • Args – Arguments to the builder, i.e. constructor of esp_modem::DCE_T class

Parameters:
Returns:

unique_ptr DCE of the created DCE on success

template<typename T_Module, typename ...Args>
static inline DCE *build(const config *cfg, Args&&... args)

Create a DCE.

Template Parameters:

  • Module – Specific Module used in this DCE

  • Args – Arguments to the builder, i.e. constructor of esp_modem::DCE_T class

Parameters:
Returns:

DCE pointer the created DCE on success

Create custom module

Creating a custom module is necessary if the application needs to use a specific device that is not supported and their commands differ from any of the supported devices. In this case it is recommended to define a new class representing this specific device and derive from the esp_modem::GenericModule. In order to instantiate the appropriate DCE of this module, application could use the DCE factory, and build the DCE with the specific module, using esp_modem::dce_factory::Factory::build().

Please refer to the implementation of the existing modules.

Please note that the modem_console example defines a trivial custom modem DCE which overrides one command, for demonstration purposes only.

Create new communication interface

In order to connect to a device using an unsupported interface (e.g. SPI or I2C), it is necessary to implement a custom DTE object and supply it into the DCE factory. The DCE is typically created in two steps:

  • Define and create the corresponding terminal, which communicates on the custom interface. This terminal should support basic IO methods defined in esp_modem::Terminal and derive from it.

  • Create the DTE which uses the custom Terminal

Please refer to the implementation of the existing UART DTE.