Nut/OS offers three configuration utilities.
The file UserConf.mk contains a few entries, which are used by the make utility during the rebuild process. It's a plain text file and may be edited manually.
This simple procedure was quite satisfying for Nut/OS 3.4, supporting two similar target CPUs, two host operating systems and two compilers only. However, with the new version 3.5 and upcoming 4.0 of Nut/OS, which is currently under development, many things will completely change. It will be much more configurable, support several target platforms including 32-bit microcontrollers and should not require manual source code modifications when ported to different hardware designs. Obviously the existing configuration tools (or their users) will reach the limits.
Some time had been spent to search the web for similar but more advanced tools and such a tool had been found, the eCos Configuration Tool Version 2. It provides a very versatile GUI based on the highly portable wxWidgets class library. In addition, the configuration rules are based on the Tcl (Tool Command Language, pronounced tickle), which offers capabilities far beyond those simple name=value configurations.
However, the brighter the light, the darker the shadows. The eCos tool makes heavy use of C++ templates, which are difficult to understand and are sometimes difficult to port. Similar, Tcl is heavy stuff too. The author of this preview (quoting Joan Armatrading: Me, myself and I) spent days to make it work on W2K. One really weird part was, that you need to run VC++ in the cygwin environment. Still there had been tons of warnings from the compiler. (Everybody who knows me, is aware, that I hate compiler warnings more than stepping into dog shit.) Beside that, I do not know much about Tcl, but several weeks before starting this project, I stumbled over Lua, a simple and well documented script language designed and implemented by a team at Tecgraf, PUC-Rio, Brazil. The initial intention was, to use Lua as a script language for programming Ethernut applications. I still have no idea, if this is possible, but Lua would also make a good replacement for Tcl as a configuration language.
Nevertheless, the eCos configuration tool is great and exactly what I had been looking for. Within a few days, all the Tcl stuff had been removed. Some days later, the Lua interpreter had been included. Several weeks later the code started working somehow. Bugs had been fixed mainly by throwing things out. As a result, we have code, which is working in most parts, but lost many of its original features. Some are not useful for Nut/OS, others may be re-implemented again later. After having prepared the skeleton, we now hope that more developers will jump in. Of course, I'm aware, that most embedded system developers are not interested in GUI programming. Anyway, if you think this is something for you, please subscribe to the En-Nut-Discussion mailing list to contact us.
The configuration tool is included in the Nut/OS 3.9.1 preview, which is available in the download section.
For insiders: Get the latest development version from CVS HEAD.
When creating a Win32 shortcut, make sure to set the working directory to the parent directory of your Nut/OS installation. If you installed Nut/OS in c:\ethernut\nut, then c:\ethernut is the perfect working directory. Or open a DOS window, change to the parent directory and enter nutconf.
When started, a file selection dialog is presented. Navigate to the nut/conf directory, where you should have copied the script files, select the configuration file for your board and press Open. On my German W2K installation, it looks like this.
Here's the same dialog running on Linux:
If you are using an original Ethernut board, then select
Next the main configuration window will receive the focus.
Sometimes the main window fails to display properly. Drag the window borders, so that the whole view looks similar to the one presented here. The tree on the left side will not be visible, that's still OK. Make sure, that the window part for the tree is large enough. Then terminate the configuration window and open it again. After opening the sample configuration, the tree should be visible. If not or if you completely messed things up, open your Win32 registry editor and remove the complete key at \HKEY_CURRENT_USER\Software\egnite\NutConf. Linux users may remove the hidden file .NutConf in the home directory. This will reset anything to its default.
Next we need to configure the local host environment. If you didn't follow the recommendations for subdirectories above, then the configuration utility may have failed to load the component repository. No big deal, we will configure everything right now. Select Edit/Settings from the main menu. The settings notebook will appear.
The first page contains one item only, the path to the so called repository file, name repository.nut. This file contains the main Lua Script and defines the configuration capabilities of the system. You may use the browse button to locate this file.
Let's have a look to the second settings page by clicking on the Build tab.
Usually the configurator will set the first directory to the include subdirectory in the build tree, if this entry had been left empty. Thus, if you add any special path, you may have to add the include dir of the build tree too.
If you are familiar with rebuilding previous Nut/OS releases, you will notice a significant change in this new release. Now we distinguish between the source directory and the build directory.
The big advantage is, that in most cases the source directory will not require any changes. The configuration tool will create all configuration dependant files in the build directory. And this is also the directory, where the Makefiles are placed and executed and the final binaries are created. By changing the build directory, you are able to create different build environments from the same source tree. Or you may select different source trees as well.
Note, that pressing the browse button allows you to create new directories.
The last item on this page specifies the directory, where the resulting Nut/OS libraries will be installed. ImageCraft users should set this to the ImageCraft library path (e.g. c:/icc/lib). For GCC it is a good idea to keep the libraries within the build tree.
On the third page of the settings notebook we specify the paths of the tools to use. Nut/OS comes with its own set of tools located in tools/win32 and tools/linux. This path should be first, followed by one or more paths required by the compiler. Add
Entries on the last page of the settings notebook are used to create
a sample application directory. Nut/OS comes with a few samples, which
demonstrate its capabilities. The configurator can create a new directory
for you, copying the sources from the source tree and creating templates
for the Makefiles. Such a directory is also quite usefull when writing
your own Nut/OS applications.
When done with the settings dialog, press OK. The settings will be stored in the Windows registry or a configuration file in the Linux home directory. In case you changed the repository file, you need to stop and restart the configurator now.
Hopefully you can finally see the full component tree in the main window. When using standard Ethernut boards and loading the related configuration, you won't need to change any settings in the component tree except selecting the correct compiler under Tools. You may then skip the rest of this chapter and move forward to build the Nut/OS libraries.
Currently there are four different types of components.
The first library module is named nutarch and is something special. Right now, it doesn't represent a real library. Thus, the underlying modules don't represent source code modules neither. The purpose of this tree branch is to offer some general options, which influence all other components. If you look to the previous screenshot, you will notice, that the microcontroller, which is typically selected after loading a configuration file, had been deselected. As a result, all other libraries are greyed out, because they are disabled. If you select any CPU, they will be at least partly re-enabled.
Furthermore, modules and options may be disabled or enabled depending on specific options being activated or deactivated. Such dependencies are defined in the Lua configuration scripts.
Options, which the user can activate or deactivate are called boolean options. You can change their state by clicking on the check box. Other options and even some boolean options do have values. You can change the option value by clicking into the second column of the component tree.
The property window on the upper right shows the value and some other interesting informations about the currently selected option. These properties are used when finally creating the build directory.
Building Nut/OS Libraries
If this step fails, then the best chance for detecting the problem is by doing it manually. Go to a shell prompt or DOS window, change to the build directory and type make clean first and then make install.
Creating a Directory for Nut/OS Applications
This step doesn't make much sense for ImageCraft users, who can simply load prepared projects contained in the appicc directory.
When selecting Build/Create Sample Directory on the main menu and confirming the information popup, the configurator will create a new or update an existing directory for application development and fill in a few ready-to-run samples. It is recommended to use these samples as templates for your own projects.
ETHERNUT 1.x NOTE
Under the Hood
As described above, the Nut/OS configuration is based on two main items, the component repository and configuration. Both are specified by Lua scripts, which are not yet fully using the language and the resulting capabilites. Right now the usage is limited to filling Lua variables, which are then retrieved by the configuration tool.
The repository consists of several files. The main file is named repository.nut by default and specifies additional files to be included. All these files are located in the conf directory.
The second group of files specify option values. Again written in Lua, each file contains option settings for a specific target hardware. The file ethernut2.conf serves as a simple example. Users may load this file as a template, modify certain values and store the new configuration in a new configuration file. It is expected, that hardware vendors will provide ready to use Nut/OS configurations.
As you can see in the .conf files, configurations look quite simple. They can be limited to the old name=value scheme. In fact, the repository scripts are not that difficult either. They just add some kind of structure by using Lua arrays. They may look a bit weird first, because Lua recognizes two types of array indices, enumerated and named. It is always a good idea, to look into the Lua language definition and try a few samples using a ready build Lua interpreter.
The following table lists all named array indices known by the Configurator.
The Configurator's Source Code
First of all, care has been taken not to force everyone using a either a GUI or rewriting the whole thing. Actually no C++ code directly calls any Lua code. Instead, a C wrapper (did you know that such things exist?) protects C++ from Lua and vice versa. This way, it should be possible to create a simple command line tool written in C and re-use the interpreter interface as well as the parts which create the final build tree.
In any case, you need the Lua source code, which can be downloaded from the Lua download page. Version 5.02 was used for the configuration preview.
If you decided to build the GUI version, you need to download the wxWidget source code from here. While the Lua interpreter will compile almost immediately without problems, it may take some time to set all the required compile options for wxWidgets. Best try some samples included in the wxWidgets distribution before taking the big step to the Nut/OS configuration tool. If you fail, try to get help from the wxWidgets' mailing list on wxWidgets related items. Do not post wxWidgets related questions to the Nut/OS mailing list unless they are closely related to the configuration tool. The same applies for Lua related problems.