Configuration

This is the default configuration of the middleware. When any of the settings shall be modified, it shall be done in dedicated application config lwesp_opts.h file.

Note

Check Getting started for guidelines on how to create and use configuration file.

group LWESP_OPT

ESP-AT options.

Defines

LWESP_CFG_ESP8266: Enables 1 or disables 0 support for ESP8266 AT commands.

LWESP_CFG_ESP32: Enables 1 or disables 0 support for ESP32 AT commands.

LWESP_CFG_ESP32_C3: Enables 1 or disables 0 support for ESP32-C3 AT commands.

LWESP_CFG_OS: Enables 1 or disables 0 operating system support for ESP library.

Note

Value must be set to 1 in the current revision

Note

Check OS configuration group for more configuration related to operating system

LWESP_CFG_MEM_CUSTOM

Enables 1 or disables 0 custom memory management functions.

When set to 1, Memory manager block must be provided manually. This includes implementation of functions lwesp_mem_malloc, lwesp_mem_calloc, lwesp_mem_realloc and lwesp_mem_free

Note

Function declaration follows standard C functions malloc, calloc, realloc, free. Declaration is available in lwesp/lwesp_mem.h file. Include this file to final implementation file

Note

When implementing custom memory allocation, it is necessary to take care of multiple threads accessing same resource for custom allocator

LWESP_CFG_MEM_ALIGNMENT: Memory alignment for dynamic memory allocations.

Note

Some CPUs can work faster if memory is aligned, usually to 4 or 8 bytes. To speed up this possibilities, you can set memory alignment and library will try to allocate memory on aligned boundaries.

Note

Some CPUs such ARM Cortex-M0 dont’t support unaligned memory access.

Note

This value must be power of 2

LWESP_CFG_USE_API_FUNC_EVT

Enables 1 or disables 0 callback function and custom parameter for API functions.

When enabled, 2 additional parameters are available in API functions. When command is executed, callback function with its parameter could be called when not set to NULL.

LWESP_CFG_MAX_SEND_RETRIES

Set number of retries for send data command.

Sometimes it may happen that AT+SEND command fails due to different problems. Trying to send the same data multiple times can raise chances for success.

LWESP_CFG_AT_PORT_BAUDRATE: Default baudrate used for AT port.

Note

User may call API function to change to desired baudrate if necessary

LWESP_CFG_MODE_STATION: Enables 1 or disables 0 ESP acting as station.

Note

When device is in station mode, it can connect to other access points

LWESP_CFG_MODE_ACCESS_POINT: Enables 1 or disables 0 ESP acting as access point.

Note

When device is in access point mode, it can accept connections from other stations

LWESP_CFG_ACCESS_POINT_STRUCT_FULL_FIELDS

Enables 1 or disables 0 full data info in lwesp_ap_t structure.

When enabled, advanced information is stored, and as a consequence, structure size is increased. Information such as scan type, min scan time, max scan time, frequency offset, frequency calibration are added

LWESP_CFG_KEEP_ALIVE: Enables 1 or disables 0 periodic keep-alive events to registered callbacks.

LWESP_CFG_KEEP_ALIVE_TIMEOUT

Timeout periodic time to trigger keep alive events to registered callbacks.

Feature must be enabled with LWESP_CFG_KEEP_ALIVE

LWESP_CFG_RCV_BUFF_SIZE: Buffer size for received data waiting to be processed.

Note

When server mode is active and a lot of connections are in queue this should be set high otherwise your buffer may overflow

Note

Buffer size also depends on TX user driver if it uses DMA or blocking mode. In case of DMA (CPU can work other tasks), buffer may be smaller as CPU will have more time to process all the incoming bytes

Note

This parameter has no meaning when LWESP_CFG_INPUT_USE_PROCESS is enabled

LWESP_CFG_RESET_ON_INIT: Enables 1 or disables 0 reset sequence after lwesp_init call.

Note

When this functionality is disabled, user must manually call lwesp_reset to send reset sequence to ESP device.

LWESP_CFG_RESTORE_ON_INIT: Enables 1 or disables 0 device restore after lwesp_init call.

Note

When this feature is enabled, it will automatically restore and clear any settings stored as default in ESP device

LWESP_CFG_RESET_ON_DEVICE_PRESENT: Enables 1 or disables 0 reset sequence after lwesp_device_set_present call.

Note

When this functionality is disabled, user must manually call lwesp_reset to send reset sequence to ESP device.

LWESP_CFG_RESET_DELAY_DEFAULT: Default delay (milliseconds unit) before sending first AT command on reset sequence.

LWESP_CFG_MAX_SSID_LENGTH: Maximum length of SSID for access point scan.

Note

This parameter must include trailling zero

LWESP_CFG_MAX_PWD_LENGTH: Maximum length of PWD for access point.

Note

This parameter must include trailling zero

LWESP_CFG_LIST_CMD: Enables 1 or disables 0 listing all available CMDs during reset/restore operation.

Connection settings.

Defines

LWESP_CFG_IPV6: Enables 1 or disables 0 support for IPv6.

LWESP_CFG_CONN_MAX_RECV_BUFF_SIZE: Maximum single buffer size for network receive data on active connection.

Note

When ESP sends buffer bigger than maximal, multiple buffers are created. Exception is UDP connection type, which can be controlled, with option LWESP_CFG_CONN_ALLOW_FRAGMENTED_UDP_SEND

LWESP_CFG_CONN_ALLOW_FRAGMENTED_UDP_SEND

Enables 1 or disables 0 support for fragmented send of UDP packets.

When connection type is UDP and packet length longer than maximal transmission unit, it can be split into multiple packets and sent over the network.

When this feature is disabled, max length of UDP packet is defined with LWESP_CFG_CONN_MAX_DATA_LEN option

LWESP_CFG_MAX_CONNS: Maximal number of connections AT software can support on ESP device.

Note

In case of official ESP-AT software, leave this on default value (5)

LWESP_CFG_CONN_MAX_DATA_LEN

Maximal number of bytes we can send at single command to ESP.

When manual TCP read mode is enabled, this parameter defines number of bytes to be read at a time

Note

Value can not exceed 2048 bytes or no data will be send at all (ESP8266 AT SW limitation)

Note

This is limitation of ESP AT commands and on systems where RAM is not an issue, it should be set to maximal value (2048) to optimize data transfer speed performance

LWESP_CFG_CONN_POLL_INTERVAL

Poll interval for connections in units of milliseconds.

Value indicates interval time to call poll event on active connections.

Note

Single poll interval applies for all connections

Debugging configurations.

Defines

LWESP_CFG_DBG

Set global debug support.

Possible values are LWESP_DBG_ON or LWESP_DBG_OFF

Note

Set to LWESP_DBG_OFF to globally disable all debugs

LWESP_CFG_DBG_OUT(fmt, ...)

Debugging output function.

Called with format and optional parameters for printf-like debug

LWESP_CFG_DBG_LVL_MIN

Minimal debug level.

Check LWESP_DBG_LVL for possible values

LWESP_CFG_DBG_TYPES_ON

Enabled debug types.

When debug is globally enabled with LWESP_CFG_DBG parameter, user must enable debug types such as TRACE or STATE messages.

Check LWESP_DBG_TYPE for possible options. Separate values with bitwise OR operator

LWESP_CFG_DBG_INIT

Set debug level for init function.

Possible values are LWESP_DBG_ON or LWESP_DBG_OFF

LWESP_CFG_DBG_MEM

Set debug level for memory manager.

Possible values are LWESP_DBG_ON or LWESP_DBG_OFF

LWESP_CFG_DBG_INPUT

Set debug level for input module.

Possible values are LWESP_DBG_ON or LWESP_DBG_OFF

LWESP_CFG_DBG_THREAD

Set debug level for ESP threads.

Possible values are LWESP_DBG_ON or LWESP_DBG_OFF

LWESP_CFG_DBG_ASSERT

Set debug level for asserting of input variables.

Possible values are LWESP_DBG_ON or LWESP_DBG_OFF

LWESP_CFG_DBG_IPD

Set debug level for incoming data received from device.

Possible values are LWESP_DBG_ON or LWESP_DBG_OFF

LWESP_CFG_DBG_NETCONN

Set debug level for netconn sequential API.

Possible values are LWESP_DBG_ON or LWESP_DBG_OFF

LWESP_CFG_DBG_PBUF

Set debug level for packet buffer manager.

Possible values are LWESP_DBG_ON or LWESP_DBG_OFF

LWESP_CFG_DBG_CONN

Set debug level for connections.

Possible values are LWESP_DBG_ON or LWESP_DBG_OFF

LWESP_CFG_DBG_VAR

Set debug level for dynamic variable allocations.

Possible values are LWESP_DBG_ON or LWESP_DBG_OFF

LWESP_CFG_AT_ECHO: Enables 1 or disables 0 echo mode on AT commands sent to ESP device.

Note

This mode is useful when debugging ESP communication

Operating system dependant configuration.

Defines

LWESP_CFG_THREAD_PRODUCER_MBOX_SIZE

Set number of message queue entries for procuder thread.

Message queue is used for storing memory address to command data

LWESP_CFG_THREAD_PROCESS_MBOX_SIZE

Set number of message queue entries for processing thread.

Message queue is used to notify processing thread about new received data on AT port

LWESP_CFG_INPUT_USE_PROCESS

Enables 1 or disables 0 direct support for processing input data.

When this mode is enabled, no overhead is included for copying data to receive buffer because bytes are processed directly by lwesp_input_process function

If this mode is not enabled, then user have to send every received byte via lwesp_input function to the internal buffer for future processing. This may introduce additional overhead with data copy and may decrease library performance

Note

This mode can only be used when LWESP_CFG_OS is enabled

Note

When using this mode, separate thread must be dedicated only for reading data on AT port. It is usually implemented in LL driver

Note

Best case for using this mode is if DMA receive is supported by host device

LWESP_THREAD_PRODUCER_HOOK()

Producer thread hook, called each time thread wakes-up and does the processing.

It can be used to check if thread is alive.

LWESP_THREAD_PROCESS_HOOK()

Process thread hook, called each time thread wakes-up and does the processing.

It can be used to check if thread is alive.

LWESP_CFG_THREADX_CUSTOM_MEM_BYTE_POOL

Enables 1 or disables 0 custom memory byte pool extension for ThreadX port.

When enabled, user must manually set byte pool at run-time, before lwesp_init is called

LWESP_CFG_THREADX_IDLE_THREAD_EXTENSION

Enables 1 or disables 0 idle thread extensions feature of ThreadX.

When enabled, user must manually configure idle thread and setup additional thread handle extension fields. By default ThreadX doesn’t support self-thread cleanup when thread memory is dynamically allocated & thread terminated, hence another thread is mandatory to do the cleanup process instead.

This configuration does not create idle-thread, rather only sets additional TX_THREAD fields, indicating thread handle and thread stack are dynamically allocated.

Have a look at System-ThreadX port for implementation

Configuration of specific modules.

Defines

LWESP_CFG_DNS: Enables 1 or disables 0 support for DNS functions.

LWESP_CFG_WPS: Enables 1 or disables 0 support for WPS functions.

LWESP_CFG_SNTP: Enables 1 or disables 0 support for SNTP protocol with AT commands.

LWESP_CFG_HOSTNAME: Enables 1 or disables 0 support for hostname with AT commands.

LWESP_CFG_PING: Enables 1 or disables 0 support for ping functions.

LWESP_CFG_MDNS: Enables 1 or disables 0 support for mDNS.

LWESP_CFG_SMART: Enables 1 or disables 0 support for SMART config.

LWESP_CFG_WEBSERVER: Enables 1 or disables 0 support for Web Server feature.

Configuration of netconn API module.

Defines

LWESP_CFG_NETCONN

Enables 1 or disables 0 NETCONN sequential API support for OS systems.

See also

LWESP_CFG_OS

Note

To use this feature, OS support is mandatory.

LWESP_CFG_NETCONN_RECEIVE_TIMEOUT

Enables 1 or disables 0 receive timeout feature.

When this option is enabled, user will get an option to set timeout value for receive data on netconn, before function returns timeout error.

Note

Even if this option is enabled, user must still manually set timeout, by default time will be set to 0 which means no timeout.

LWESP_CFG_NETCONN_ACCEPT_QUEUE_LEN

Accept queue length for new client when netconn server is used.

Defines number of maximal clients waiting in accept queue of server connection

LWESP_CFG_NETCONN_RECEIVE_QUEUE_LEN

Receive queue length for pbuf entries.

Defines maximal number of pbuf data packet references for receive

Configuration of MQTT and MQTT API client modules.

Defines

LWESP_CFG_MQTT_MAX_REQUESTS: Maximal number of open MQTT requests at a time.

LWESP_CFG_MQTT_API_MBOX_SIZE: Size of MQTT API message queue for received messages.

LWESP_CFG_DBG_MQTT

Set debug level for MQTT client module.

Possible values are LWESP_DBG_ON or LWESP_DBG_OFF

LWESP_CFG_DBG_MQTT_API

Set debug level for MQTT API client module.

Possible values are LWESP_DBG_ON or LWESP_DBG_OFF

Configuration of Cayenne MQTT client.

Defines

LWESP_CFG_CAYENNE_TX_BUFF_SIZE: Size of Cayenne messages size TX buffer in units of bytes.

LWESP_CFG_CAYENNE_RX_BUFF_SIZE: Size of Cayenne RX buffer size in units of bytes.

LWESP_CFG_DBG_CAYENNE

Set debug level for Cayenne MQTT client module.

Possible values are LWESP_DBG_ON or LWESP_DBG_OFF

Standard C library configuration.

Configuration allows you to overwrite default C language function in case of better implementation with hardware (for example DMA for data copy).

Defines

LWESP_MEMCPY(dst, src, len)

Memory copy function declaration.

User is able to change the memory function, in case hardware supports copy operation, it may implement its own

Function prototype must be similar to:

void *  my_memcpy(void* dst, const void* src, size_t len);

Parameters

dst – [in] Destination memory start address
src – [in] Source memory start address
len – [in] Number of bytes to copy

Returns

Destination memory start address

LWESP_MEMSET(dst, b, len)

Memory set function declaration.

Function prototype must be similar to:

void *  my_memset(void* dst, int b, size_t len);

Parameters

dst – [in] Destination memory start address
b – [in] Value (byte) to set in memory
len – [in] Number of bytes to set

Returns

Destination memory start address

Minimum AT versions needed for Espressif devices to run properly with LwESP.

Defines

LWESP_MIN_AT_VERSION_MAJOR_ESP8266: Minimal major version for ESP8266

LWESP_MIN_AT_VERSION_MINOR_ESP8266: Minimal minor version for ESP8266

LWESP_MIN_AT_VERSION_PATCH_ESP8266: Minimal patch version for ESP8266

LWESP_MIN_AT_VERSION_MAJOR_ESP32: Minimal major version for ESP32

LWESP_MIN_AT_VERSION_MINOR_ESP32: Minimal minor version for ESP32

LWESP_MIN_AT_VERSION_PATCH_ESP32: Minimal patch version for ESP32

LWESP_MIN_AT_VERSION_MAJOR_ESP32_C3: Minimal major version for ESP32-C3

LWESP_MIN_AT_VERSION_MINOR_ESP32_C3: Minimal minor version for ESP32-C3

LWESP_MIN_AT_VERSION_PATCH_ESP32_C3: Minimal patch version for ESP32-C3