Configuration

Standard Library

The Library Reference is configured at compile time using defines named CONFIG_*. The default configuration includes most functionality, as most application wants that. If an application has special requirements, for example memory constraints, it has to be configured to remove unnecessaray functionality.

Search order

Highest priority first.

Simba build system

  1. Command line as CDEFS_EXTRA="<configuration variable>=<value>".
  2. A file named config.h in the application root folder.
  3. The default configuration file, src/config_default.h.

PlatformIO

  1. The variable build_flags in platformio.ini as build_flags = -D<configuration variable>=<value>.
  2. A file named config.h in the application source folder src.
  3. The default configuration file, src/config_default.h.

Arduino IDE

  1. A file (also called a tab) named config.h in the sketch.
  2. The default configuration file, src/config_default.h.

Variables

All configuration variables are listed below. Their default values are defined in src/config_default.h.

Defines

CONFIG_SYS_CONFIG_STRING
CONFIG_SYS_SIMBA_MAIN_STACK_MAX

Main thread stack size for ports with a fixed size main thread stack.

CONFIG_ASSERT

Assertions are used to check various conditions during the application execution. A typical usage is to validate function input arguments.

CONFIG_DEBUG

Include more debug information.

CONFIG_FS_CMD_DS18B20_LIST

Debug file system command to list all DS18B20 sensors on the bus.

CONFIG_FS_CMD_ESP_WIFI_STATUS

Debug file system command to print the Espressif WiFi status.

CONFIG_FS_CMD_FS_APPEND

Debug file system command to append to a file.

CONFIG_FS_CMD_FS_COUNTERS_LIST

Debug file system command to list all counters.

CONFIG_FS_CMD_FS_COUNTERS_RESET

Debug file system command to set all counters to zero.

CONFIG_FS_CMD_FS_FILESYSTEMS_LIST

Debug file system command to list all registered file systems.

CONFIG_FS_CMD_FS_LIST

Debug file system command to list all registered file systems.

CONFIG_FS_CMD_FS_FORMAT

Debug file system command to format a file system.

CONFIG_FS_CMD_FS_PARAMETERS_LIST

Debug file system command to list all parameters.

CONFIG_FS_CMD_FS_READ

Debug file system command to read from a file.

CONFIG_FS_CMD_FS_REMOVE

Debug file system command to remove a file.

CONFIG_FS_CMD_FS_WRITE

Debug file system command to write to a file.

CONFIG_FS_CMD_I2C_READ

Debug file system command to read from a i2c bus.

CONFIG_FS_CMD_I2C_WRITE

Debug file system command to write to a i2c bus.

CONFIG_FS_CMD_LOG_LIST

Debug file system command to list all log objects.

CONFIG_FS_CMD_LOG_PRINT

Debug file system command to create a log entry and print it. Mainly used for debugging.

CONFIG_FS_CMD_LOG_SET_LOG_MASK

Debug file system command to set the log mask of a log object.

CONFIG_FS_CMD_NETWORK_INTERFACE_LIST

Debug file system command to list all network interfaces.

CONFIG_FS_CMD_PIN_READ

Debug file system command to read the current value of a pin.

CONFIG_FS_CMD_PIN_SET_MODE

Debug file system command to set the mode of a pin.

CONFIG_FS_CMD_PIN_WRITE

Debug file system command to write a value to a pin.

CONFIG_FS_CMD_PING_PING

Debug file system command to ping a host.

CONFIG_FS_CMD_SERVICE_LIST

Debug file system command to list all services.

CONFIG_FS_CMD_SERVICE_START

Debug file system command to start a service.

CONFIG_FS_CMD_SERVICE_STOP

Debug file system command to stop a services.

CONFIG_FS_CMD_SETTINGS_LIST

Debug file system command to list all settings.

CONFIG_FS_CMD_SETTINGS_READ

Debug file system command to read the value of a setting.

CONFIG_FS_CMD_SETTINGS_RESET

Debug file system command to reset the settings to their original values.

CONFIG_FS_CMD_SETTINGS_WRITE

Debug file system command to write a value to a setting.

CONFIG_FS_CMD_SYS_CONFIG

Debug file system command to print the system configuration.

CONFIG_FS_CMD_SYS_INFO

Debug file system command to print the system information.

CONFIG_FS_CMD_SYS_UPTIME

Debug file system command to print the system uptime.

CONFIG_FS_CMD_SYS_REBOOT

Debug file system command to reboot the system uptime.

CONFIG_FS_CMD_THRD_LIST

Debug file system command to list threads’ information.

CONFIG_FS_CMD_THRD_SET_LOG_MASK

Debug file system command to set the log mask of a thread.

CONFIG_FS_CMD_USB_DEVICE_LIST

Debug file system command to list all USB devices.

CONFIG_FS_CMD_USB_HOST_LIST

Debug file system command to list all USB devices connected to the USB host.

CONFIG_FS_PATH_MAX

The maximum length of an absolute path in the file system.

CONFIG_MONITOR_THREAD

Start the monitor thread to gather statistics of the scheulder.

CONFIG_PREEMPTIVE_SCHEDULER

Use a preemptive scheduler.

CONFIG_PROFILE_STACK

Profile the stack usage in runtime. It’s a cheap operation and is recommended to have enabled.

CONFIG_SETTINGS_AREA_SIZE

Size of the settings area. This size MUST have the same size as the settings generated by the settings.py script.

CONFIG_SHELL_COMMAND_MAX

Maximum number of characters in a shell command.

CONFIG_SHELL_HISTORY_SIZE

Size of the shell history buffer.

CONFIG_SHELL_MINIMAL

Minimal shell functionality to minimize the code size of the shell module.

CONFIG_SHELL_PROMPT

The shell prompt string.

CONFIG_SOCKET_RAW

Raw socket support.

CONFIG_SPIFFS

SPIFFS is a flash file system applicable for boards that has a reasonably big modifiable flash.

CONFIG_START_CONSOLE

Start the console device (UART/USB CDC) on system startup.

CONFIG_START_CONSOLE_DEVICE_INDEX

Console device index.

CONFIG_START_CONSOLE_UART_BAUDRATE

Console UART baudrate.

CONFIG_START_CONSOLE_USB_CDC_CONTROL_INTERFACE

Console USB CDC control interface number.

CONFIG_START_CONSOLE_USB_CDC_ENDPOINT_IN

Console USB CDC input endpoint.

CONFIG_START_CONSOLE_USB_CDC_ENDPOINT_OUT

Console USB CDC output endpoint.

CONFIG_START_CONSOLE_USB_CDC_WAIT_FOR_CONNETION

Wait for the host to connect after starting the console.

CONFIG_START_FILESYSTEM

Configure a default file system.

CONFIG_START_FILESYSTEM_ADDRESS

Configure a default file system start address.

CONFIG_START_FILESYSTEM_SIZE

Configure a default file system size.

CONFIG_START_NETWORK

Setup the ip stack and connect to all configured networks.

CONFIG_START_NETWORK_INTERFACE_WIFI_CONNECT_TIMEOUT

WiFi connect timeout is seconds.

CONFIG_START_NETWORK_INTERFACE_WIFI_SSID

SSID of the WiFi to connect to.

CONFIG_START_NETWORK_INTERFACE_WIFI_PASSWORD

Password of the WiFi to connect to.

CONFIG_START_SHELL

Start a shell thread communication over the console channels.

CONFIG_START_SHELL_PRIO

Shell thread priority.

CONFIG_START_SHELL_STACK_SIZE

Shell thread stack size in words.

CONFIG_STD_OUTPUT_BUFFER_MAX

Maximum number of bytes in the print output buffer.

CONFIG_SYSTEM_TICK_FREQUENCY

System tick frequency in Hertz.

CONFIG_THRD_CPU_USAGE

Calculate thread CPU usage.

CONFIG_THRD_ENV

Each thread has a list of environment variables associated with it. A typical example of an environment variable is “CWD” - Current Working Directory.

CONFIG_THRD_IDLE_STACK_SIZE

Stack size of the idle thread.

CONFIG_THRD_SCHEDULED

Count the number of times each thread has been scheduled.

CONFIG_THRD_TERMINATE

Threads are allowed to terminate.

CONFIG_USB_DEVICE_VID

USB device vendor id.

CONFIG_USB_DEVICE_PID

USB device product id.

lwIP

Use config.h to fully configure lwIP and all of its modules. You do not need to define every option that lwIP provides; if you do not define an option, a default value will be used. Therefore, your config.h provides a way to override much of the behavior of lwIP.

By default Simba overrides a few of the variables in src/inet/lwipopts.h.

Module support (Code size)

Enabling and disabling modules

You can tune your code size by only compiling the features you really need. The following is a list of what gets compiled in “out of the box” with lwIP.

Default inclusions:

  • ARP (LWIP_ARP)
  • IP and fragmentation (IP_FRAG) and reassembly (IP_REASSEMBLY)
  • Raw IP PCB support (LWIP_RAW)
  • UDP (LWIP_UDP) and UDP-Lite (LWIP_UDPLITE)
  • TCP (LWIP_TCP) – this is a big one!
  • Statistics (LWIP_STATS)

Default exclusions:

  • DHCP (LWIP_DHCP)
  • AUTOIP (LWIP_AUTOIP)
  • SNMP (LWIP_SNMP)
  • IGMP (LWIP_IGMP)
  • PPP (PPP_SUPPORT)

If you would like to change this, then you just need to set the options listed below. For example, if you would like to disable UDP and enable DHCP, the following config.h file would do it:

/* Disable UDP */
#define LWIP_UDP 0

/* Enable DHCP */
#define LWIP_DHCP 1

Memory management (RAM usage)

Memory pools

In an embedded environment, memory pools make for fast and efficient memory allocation. lwIP provides a flexible way to manage memory pool sizes and organization.

lwIP reserves a fixed-size static chunk of memory in the data segment, which is subdivided into the various pools that lwip uses for the various data structures. For example, there is a pool just for struct tcp_pcb’s, and another pool just for struct udp_pcb’s. Each pool can be configured to hold a fixed number of data structures; this number can be changed in the config.h file by changing the various MEMP_NUM_* values. For example, MEMP_NUM_TCP_PCB and MEMP_NUM_UDP_PCB control the maximum number of tcp_pcb and udp_pcb structures that can be active in the system at any given time.

It is also possible to create custom memory pools in addition to the standard ones provided by lwIP.

Dynamic allocation: mem_malloc

lwIP uses a custom function mem_malloc for all dynamic allocation; therefore, it is easy to change how lwIP uses its RAM. There are three possibilities provided out-of-the-box:

  1. (default) lwIP’s custom heap-based mem_malloc. By default, lwIP uses a statically-allocated chunk of memory like a heap for all memory operations. Use MEM_SIZE to change the size of the lwIP heap.
  2. C standard library malloc and free. If you wish to have lwIP use the standard library functions provided by your compiler/architecture, then define the option MEM_LIBC_MALLOC.
  3. Memory pools. lwIP can also emulate dynamic allocation using custom memory pools (see that chapter for more information). This involves the options MEM_USE_POOLS and MEMP_USE_CUSTOM_POOLS and a new custom file lwippools.h.

Understanding/changing memory usage

lwIP uses memory for:

  • code (depending on your system, may use ROM instead of RAM)

  • statically allocated variables (some initialized, some not initialized)

  • task stack

  • dynamically allocated memory

    • heap
    • memp pools

Unless you use a C library heap implementation (by defining MEM_LIBC_MALLOC to 1), dynamically allocated memory must be statically allocated somewhere. This means you reserve a specific amount of memory for the heap or the memp pools from which the code dynamically allocates memory at runtime.

The size of this heap and memp pools can be adjusted to save RAM:

There are 3 types of pbufs:

  • REF/ROM, RAM and POOL. PBUF_POOL_SIZE * PBUF_POOL_BUFSIZE only refers to type POOL.
  • RAM pbufs are allocated in the memory defined by MEM_SIZE (this memory is not used much aside from RAM pbufs) - this is the heap and it is allocated as mem_memory.
  • REF/ROM pbufs as well as pcbs and some other stuff is allocated from dedicated pools per structure type. The amount of structures is defined by the various MEMP_NUM_ defines. Together, this memory is allocated as memp_memory and it includes the pbuf POOL.

However, if you define MEMP_MEM_MALLOC to 1 in your config.h, every piece of dynamically allocated memory will come from the heap (the size of which is defined by MEM_SIZE). If you then even define MEM_LIBC_MALLOC to 1, too, lwIP doesn’t need extra memory for dynamically allocated memory but only uses the C library heap instead. However, you then have to make sure that this heap is big enough to run your application.

To tweak the various MEMP_NUM_ defines, define LWIP_STATS=1 and LWIP_STATS_DISPLAY=1 and call stats_display() to see how many entries of each pool are used (or have a look at the global variable lwip_stats instead).

Fine-tuning even more

To see the options that you can set, open 3pp/lwip-1.4.1/src/include/lwip/opt.h. This file is fully commented and explains how many of the options are used.