Nut/OS development for purists

A graphical user interface may not always be available. Sometimes, you may only have a command line interface to a remote computer. Or, due to compatibility problems, the GUI tools may simply fail to build or may crash when you try to start them. Or, you may want to build Nut/OS automatically, using scripts or batch files.

This document will explain, how to develop Nut/OS applications without using any visual tools. It is assumed, that you have already installed the toolchain (compiler, linker etc.). Furthermore, a text editor will be required.

Installation

On Linux and OS X, the Nut/OS installation is command line based anyway and the executables will be build during the installation.

On Windows PCs only the GUI based installer is available, which includes readily built executables. To install Nut/OS on a remote computer, you need to install Nut/OS on a local computer first. You can then copy the installation directory to the remote PC. You don't need to set any special system settings or registry entries.

Specifically on Windows, you need to make sure, that all required tools can be located via the PATH environment variable. This includes the Nut/OS tools directory (nut\tools\win32) as well as the compiler tools.

For AVR based boards, when using WinAVR as your toolchain, you may set the PATH to something like

PATH=C:\ethernut\nut\tools\win32;C:\WinAVR\bin;C:\WinAVR\utils\bin;%PATH%

When developing ARM applications using YAGARTO:

PATH=C:\ethernut\nut\tools\win32;"C:\Program Files\yagarto\bin";%PATH%

The exact paths on your system will probably differ. On Linux and OS X, the executables should had been copied to a reachable bin directory during installation.

Configuration

The GUI based Nut/OS Configurator allows to load board configuration files, modify them and store them, overwriting the existing configuration or creating a new configuration file. Furthermore, based on the current configuration, it creates a target specific build tree with all required Makefiles and a number of C header files. Last not least, the Configurator is used to create a target specific application tree, containing samples and Makefiles, which you can use as a template for your own applications.

While the GUI based executable is named nutconf, it command line counterpart has the name nutconfigure. This version is controlled by a number of command line options, which are listed when called with option -?.

nutconfigure -?
Usage: nutconfigure OPTIONS ACTIONS
OPTIONS:
-a<dir>  application directory (./nutapp)
-b<dir>  build directory (./nutbld)
-c<file> configuration file (./nut/conf/ethernut21b.conf)
-i<dir>  first include path ()
-j<dir>  last include path ()
-l<dir>  library directory ()
-m<type> target platform (avr-gcc)
-p<type> programming adapter (avr-dude)
-q       quiet (verbose)
-s<dir>  source directory (./nut)
-r<file> repository (./nut/conf/repository.nut)
ACTIONS:
create-buildtree
create-apptree

Only two functions are supported by the command line version of the Configurator:

Creating a build tree
Creating an application (sample) tree

The most important parameter is -c, which specifies the configuration file of the target board. Here are the commands to create the build directories for various Ethernuts. Before running any of them, you must first change to the Nut/OS installation directory (parent of the source directory nut). Note, that only one of the listed commands can be used, creating the tree for one of the boards only. If you concurrently want to build Nut/OS for several boards, you need to specify unique build and application tree names for each board (options -a and -b).

nutconfigure -cnut/conf/ethernut13h.conf -lnutbld/lib -mavr-gcc create-buildtree                
nutconfigure -cnut/conf/ethernut21c.conf -lnutbld/lib -mavr-gcc create-buildtree
nutconfigure -cnut/conf/ethernut31c.conf -lnutbld/lib -marm-gcc create-buildtree
nutconfigure -cnut/conf/ethernut50c.conf -lnutbld/lib -marm-gcc create-buildtree

Creating application trees can be done with the related commands:

nutconfigure -cnut/conf/ethernut13h.conf -lnutbld/lib -mavr-gcc create-apptree                
nutconfigure -cnut/conf/ethernut21c.conf -lnutbld/lib -mavr-gcc create-apptree
nutconfigure -cnut/conf/ethernut31c.conf -lnutbld/lib -marm-gcc create-apptree
nutconfigure -cnut/conf/ethernut50c.conf -lnutbld/lib -marm-gcc create-apptree

You cannot use the command line tool to modify existing or create new board configurations. If you need to do this, use your text editor and directly modify the related configuration file, located in nut/conf.

Building Nut/OS binaries

This is quite simple. First change to the build tree you created in the previous chapter and run make to build and install the Nut/OS libraries:

cd nutbld
make clean all install

To build application binaries, change to the application's directory withing the application tree that you created in the previous chapter and run make again:

cd ../nutapp/events
make clean all

If all worked as expected, you will find the binary in the current directory, usually in 3 different formats:

Elf format, with extension .elf
Raw binary format, with extension .bin
Intel hex format, with extension .hex

Depending on your platform, different formats may be available.

Uploading binaries to the target

Tools for uploading binaries to the target board are usually available as command line tools.

Debugging

Unfortunately, Atmel doesn't provide any information about the 8-bit AVR debug interface. AVR Studio is the only tool, that can handle it and it is not available on the command line.

You can use GDB for ARM based targets. It takes some time to become familiar with, but it's worth a try. You will be astonished, how sophisticated this tool is.