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_C2: Enables 1 or disables 0 support for ESP32-C2 AT commands.

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

LWESP_CFG_ESP32_C6: Enables 1 or disables 0 support for ESP32-C6 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_MANUAL_TCP_RECEIVE

Enables 1 or disables 0 manual TCP data receive from ESP device.

Normally ESP automatically sends received TCP data to host device in async mode. When host device is slow or if there is memory constrain, it may happen that processing cannot handle all received data.

When feature is enabled, ESP will notify host device about new data available for read and then user may start read process

Note

This feature is only available for TCP/SSL connections.

LWESP_CFG_CONN_MIN_DATA_LEN

Minimal buffer in bytes for connection receive allocation.

             Allocation will always start with (up to) \ref LWESP_CFG_CONN_MAX_DATA_LEN
             and will continue with trial down to this setting up until allocating is successful.

Note

This feature is used together with LWESP_CFG_CONN_MANUAL_TCP_RECEIVE

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

LWESP_CFG_CONN_ALLOW_START_STATION_NO_IP

Enables (1) or disabled (1) option to start connection event if station does not have valid IP address (is not connected to another access point)

When enabled, starting a connection as a client can be successful even, if ESP-AT station isn’t connected to another access point. This feature is only used if ESP is in access point mode and another station connects to it.

Note

Value is set to 0 to keep backward compatibility.

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

Enables 1 or disables 0 automatic time read from the device when time gets updated.

Latest version of ESP-AT, starting from v3.0 supports, when enabled, to receive +TIME_UPDATED notification, when ESP device got new time via SNTP protocol.

When this option is enabled, command will be send to the ESP device requesting new time for each new TIME UPDATED event.

Note

LWESP_CFG_SNTP shall be enabled and SNTP configured on ESP device

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

LWESP_CFG_FLASH: Enables 1 or disables 0 support for system flash 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.

LWESP_CFG_BLE: Enables 1 or disables 0 support for Bluetooth Low Energy.

Note

This feature only works for some of Espressif devices, that support AT BLE commands

LWESP_CFG_BT: Enables 1 or disables 0 support for Bluetooth Classic.

Note

This feature only works for some of Espressif devices, that support AT BT commands

Configuration of netconn API module.

Defines

LWESP_CFG_NETCONN

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