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 disables0
support for ESP8266 AT commands.
-
LWESP_CFG_ESP32
Enables
1
or disables0
support for ESP32 AT commands.
-
LWESP_CFG_ESP32_C2
Enables
1
or disables0
support for ESP32-C2 AT commands.
-
LWESP_CFG_ESP32_C3
Enables
1
or disables0
support for ESP32-C3 AT commands.
-
LWESP_CFG_ESP32_C6
Enables
1
or disables0
support for ESP32-C6 AT commands.
-
LWESP_CFG_OS
Enables
1
or disables0
operating system support for ESP library.Note
Value must be set to
1
in the current revisionNote
Check OS configuration group for more configuration related to operating system
-
LWESP_CFG_MEM_CUSTOM
Enables
1
or disables0
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_freeNote
Function declaration follows standard C functions
malloc, calloc, realloc, free
. Declaration is available inlwesp/lwesp_mem.h
file. Include this file to final implementation fileNote
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
or8
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 disables0
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 toNULL
.
-
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 disables0
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 disables0
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 disables0
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 disables0
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 disables0
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 disables0
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 disables0
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 disables0
listing all available CMDs during reset/restore operation.
Connection settings.
Defines
-
LWESP_CFG_IPV6
Enables
1
or disables0
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 disables0
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 disables0
manualTCP
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 disables0
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 disables0
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 disables0
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 disables0
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 disables0
support for DNS functions.
-
LWESP_CFG_WPS
Enables
1
or disables0
support for WPS functions.
-
LWESP_CFG_SNTP
Enables
1
or disables0
support for SNTP protocol with AT commands.
-
LWESP_CFG_SNTP_AUTO_READ_TIME_ON_UPDATE
Enables
1
or disables0
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 disables0
support for hostname with AT commands.
-
LWESP_CFG_FLASH
Enables
1
or disables0
support for system flash with AT commands.
-
LWESP_CFG_PING
Enables
1
or disables0
support for ping functions.
-
LWESP_CFG_MDNS
Enables
1
or disables0
support for mDNS.
-
LWESP_CFG_SMART
Enables
1
or disables0
support for SMART config.
-
LWESP_CFG_WEBSERVER
Enables
1
or disables0
support for Web Server feature.
-
LWESP_CFG_BLE
Enables
1
or disables0
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 disables0
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 disables0
NETCONN sequential API support for OS systems.See also
Note
To use this feature, OS support is mandatory.
-
LWESP_CFG_NETCONN_RECEIVE_TIMEOUT
Enables
1
or disables0
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
Configuration of Bluetooth Low Energy.
Configuration of Bluetooth Classic.
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.
-
LWESP_CFG_ESP8266