(new in 0.10) The configurator is used to configure your eLua image by specifying the various modules and components that will be part of the eLua firmware image, as well as their specific parameters. It replaces the old configuration mechanism (based on editing platform_conf.h files) with a number of improvements:

The configurator works by reading a Lua based board configuration file and generating the corresponding C header file (which for the most part has the same role as the platform_conf.h file that was used before the configurator). The board name is given by the board argument to build_elua (see this link for more details about building your eLua image). The configurator looks for a file named <board>.lua in two locations:

After finding <board>.lua in one of these locations, the configurator runs and generates the corresponding header file in boards/headers/board_<board>.h. The files under boards/headers are also not part of the eLua source tree, so they can be edited manually if needed (see here for more details). After this, the configurator is done and the build process continues with the usual steps (compiling and linking the source files).

The build is configured using a Lua file. The Lua file contains code that must return the board configuration as a regular Lua table. An example for the mbed board is given below:

As can be seen, a configuration for a board contains a number of sections:

The next section will explain each of the above items (and some that are not present in the above mbed configuration file) in detail. Please keep in mind that the best way to understand the configurator (besides reading this document) is to look at the existing configurations in board/known.

The CPU is given by the cpu key in the configuration table. The CPU must be already known to the build system. A list of the known CPUs can be found in the build_data.lua file in the platform_list table.

The various components that will be part of the eLua firmware image are given as a table under the components section in the main configurator table. The list of components known to the configurator, as well as their configuration parameters are listed in the table below. Some parameters have default values; if this is the case, the default values are written in bold. Also, some parameters are required, others are optional. Optional parameters are written over a grey background. All the required timer ID attributes that are not specified in the configuration default to the system timer ID.

As can be seen in the table above, some of the parameters are common to more than one component. For example, CON_UART_ID is shared between sercon, xmodem and term. It is enough to define a shared attribute only once (in one of the components). For example:

If you were to redefine a shared attribute to a different value:

you’d get a warning from the configurator:

Besides the generic components in the table above, each platform can specify its own list of platform-specific components:

The config section contains various build time configuration data. The list of the known configuration data items, as well as their parameters are listed in the table below. Some parameters have default values; if this is the case, the default values are written in bold. Also, some parameters are required, others are optional. Optional parameters are written over a grey background.

Besides the generic configuration items in the table above, each platform can specify its own list of platform-specific configuration items:

The configurator has support for fine-grained selections of the Lua modules that are going to be part of the eLua firmware. It knows how to handle generic modules and platform specific modules (see here for more details about generic and platform specific modules). The modules are specified by the modules section of the configuration file:

The module chooser knows how to differentiate between 3 categories of modules:

Besides the names above, the group name all can be used in both platform and generic:

A module name can be prefixed with a dash (-) if that module must be excluded from the image instead of being included. Generally, this makes sense only when a group name (all, all_lua or all_elua) is also used in the list of modules. A few examples will help clarify this:

Include all the modules (generic and platform specific) in the image.

Include the Lua modules math, io and string and the eLua modules uart and pio in the image.

Include all the Lua modules, as well as the eLua generic modules uart and pd. Also include all the platform specific modules.

Include all the Lua modules except debug and all the generic eLua modules except net and can in the image. Also include the LM3S platform specific disp module, which will be accesible via lm3s.disp. Of course, this only works if the platform corresponding to the board is LM3S. For a list of the currently available platform-specific modules, check the status page.

As previously explained, the configurator compiles the Lua board description file into a C header file (board_<board>.h) that is later used to compile the eLua firmware. If additional headers must be included in the generated header file, they can be specified in the headers section:

Besides the macros generated by the configurator, it is sometimes useful to add other macros to the board_<board>.h file. These can be specified in the macros section. If present, macros must be a table with two kinds of keys:

For example, this definition:

will be compiled into this:

The eLua cpu module has support for exposing various CPU related constants as keys in the cpu table. These are used, for example, to access the generic interrupt components from Lua. The CPU constants in this module are generally defined by the various eLua platforms, but there is support in the configuration file to add new CPU constants if needed. These are specified as part of the cpu_constants section. Much like the macro configurator, there are two types of constants that can be given in cpu_constants:

For example, this definition:

will be compiled into this:

The build section of the configurator contains options that will be passed directly to the builder. The following keys of the build table are recognized by the builder: target, allocator, optram, boot, romfs, cpumode, bootloader (note that allocator is also inferred automatically from the number of non-contigours RAM regions specified in the configuration data section). For more details about these options, see the documentation on invoking the build system.

If a custom build configuration (one that is not present in boards/known) is needed, one way to handle this is to write the new configuration file from scratch. However, starting from a known configuration and customizing it might be a better way to approach this task. The main thing to remember is that configurations are written in Lua, so you can use Lua code to manipulate them directly. For example, suppose that your hardware is almost identical to an mbed board, but the console is on UART1 instead of UART0. You could simply copy _boards/known/mbed.lua to boards/custom (remember that boards/custom is not part of source control, so this is the place to put your custom configuration files) and modify the uart attribute of sercon. If you want to avoid duplication, you can simply "inherit" the basic mbed configuration and change only what you need:

Of couse, you can use any kind of Lua code in the configuration file. You can download the configuration from the Internet, make the whole configuration process interactive by asking the user to enter the configuration parameters at build time and so on.

While the configurator is designed to cover the complete set of eLua build configuration parameters, there might be rare occasions when there is a need to edit the generated configuration file manually, in order to cover functionality not provided by the configurator. There is a simple way to do this in conjuction with the build system:

You need to be familiar with the eLua internals in order to properly modify the configuration file, so using this method carelessly might render your image unbuildable or unusable.