Installation

§1.  Introduction

In this document we will explain step by step how to install NutDAC in a computer. It assumes that you are familiar with NutOS up to the point where you know how to install it, compile and play with the sample applications that came with it. This is not a guide about NutOS.

As you might already know NutDAC is divided in NutDAC_Micro and NutDAC_GUI, written in C and Java respectively, and thus they require specific installation instructions.

Versions used for this tutorial

§2.  Installation of NutDAC_Micro

There are no binary libraries that one can use straight and link code from, the whole NutDAC_Micro source code has to be installed because the libraries need to be configured and compiled specifically for each individual application. But NutDAC_Micro itself does not require much to be installed. The whole package can be seen as a bunch of NutOS programs organized in a more or less complex directory structure with makefiles for automating the compilation process.

The easiest way to install NutDAC_Micro is to simply copy its whole directory structure to the same directory where you configured NutOS to place the sample applications (let's assume that it is ~/ethernut/nut-app/), and then let it know where it has been placed. In the following we present step by step instructions:

  • First make sure the you have NutOS installed and that you can compile its sample applications. This will require in turn that you have correctly installed a toolchain for the microcontroller of your board and some basic GNU tools used in development environments (like make, sh, etc.). (WINDOWS users, please read the Notes on Windows installation)
  • Uncompress the NutDAC_Micro-x.xx.tar file and copy the NutDAC_Micro directory to the directory where NutOS places its sample applications
  • Create the NUTDAC_MICRO_HOME environment variable pointing to the root directory of the NutDAC_Micro folder.
    • In linux, for example
      jose@Aut-019:~/ethernut/nut-app/NutDAC_Micro$ NUTDAC_MICRO_HOME=/home/jose/ethernut/nut-app/NutDAC_Micro
      jose@Aut-019:~/ethernut/nut-app/NutDAC_Micro$ export NUTDAC_MICRO_HOME
      you might want to add this commands to your ~/.profile file (or ~/.bashrc, for example) so you don't have to type them each time you log in.
    • In Windows XP, Start->Control Panel->System->Environment Variables. You will have to restart your computer, or at least open a new command line after the variable is set.

That is all. To verify that everything is correct you can try to compile the libraries

jose@Aut-019:~/ethernut/nut-app/NutDAC_Micro$ make
You will see many warnings telling that "Using default nutdac-config header". This is perfectly fine at this point, as the libraries are being compiled with a default configuration file that should not be used in particular applications (more on this later). You can also try to compile the examples with
jose@Aut-019:~/ethernut/nut-app/NutDAC_Micro$ make examples
(Note that for each example the whole NutDAC_Micro will be compiled once, so compiling all the applications might take a while in slow computers)

For a detailed example of how create a NutDAC_Micro based project check the Creating new applications tutorial.

§2.1  Notes on Windows installation

Theoretically, as already explained, installing NutDAC_Micro should be as easy as copying it to the nut-app directory and set an environment variable. However, we have detected in Windows some issues related to the development environment that are worth some comments. If you had troubles installing NutDAC_Micro in Windows, read this. Otherwise you can skip it.

Known issues

Linux vs. Windows paths
In general, if you are using a native compiler, it is usually a good idea to use also a native build of the GNU tools required in a generic development environment (like make, sh, etc.). Otherwise you might encounter path representation related problems (e.g. "c:\dir" of Windows against "/dir" of Linux). These tools are sometimes distributed within the toolchain packages that provide the compilers. That is the case of WinAVR, whereas YAGARTO provides a separate package for them, YAGARTO tools.

Being said that, we recommend:

  • If you want to develop software for AVR and ARM, the Ethernut project recommends WinAVR and YAGARTO. They both provide native compilation of many tools (but not all, at least WinAVR has some programs that need cygwin dlls). In this case use the windows shell for compilation of your programs.
  • If you use toolchains that require cygwin, like GnuARM, then use the cygwin shell as well
  • If you have cygwin installed with its path in the system path, and if you have also installed native toolchains (YAGARTO and/or WinAVR), be sure that the cygwin path is not added before the paths of the toolchains. If you need cygwin's path in the beginning, at least remove the make from the cygwin installation.
  • If you use a mixture of native and non native chaintools (i.e. WinAVR and GnuARM), most likely you will have problems derived of the difference of path representations when you call the compiler or other tools. Good luck.

Infinite loops when running make
WinAVR (at least version 20100110) and YAGARTO tools (version 20100703) come with a version of the sh shell program (2.04) that behaves strangely: it produces infinite loops when calling a second make from a makefile with the -f option.

To reproduce this simply create a Makefile in any directory containing the following target

all: 
	echo "Makefile 1";  
	$(MAKE) -f Makefile2;

Then execute

make

or even more interesting

jose@Aut-019:~/ethernut/nut-app/
C:ethernut-4.8.7nutapptest>sh
sh-2.04$ make -f blah

In both cases you will get an infinite loop in which the Makefile that you have created is always used. Note that you don't need to even create the Makefile2 file, neither invoke make with a name of an existing makefile from within the sh shell.

This problem is not show when compiling NutOS or its examples, but it does show when trying to compile NutDAC_Micro sources.

The workaround is to use a version of sh that does not show this problem. Here we have several possibilities:

  • Install MinGW including the MSYS basic system, with which you will have sh version 3.1. Then add the path to the MSYS binaries to your system path (in my case C:\MinGW\msys\1.0\bin). In order to make sure that when sh is invoked the one used is the one from MinGW, either a)add it in the beginning or b)add it at the end and delete (or rename) the sh binaries from WinAVR and YAGARTO (under utils\bin and bin directories respectively)
  • Another possibility is to install cygwin and the version of sh that comes with it (3.2). Then add the bin directory of your cygwin installation (C:\cygwin\bin in my case) to the path of your system. In order to ensure that the sh used is the one from cygwin and not from WinAVR or YAGARTO, you can either:
    • Add the cygwin path before the paths for WinAVR and YAGARTO tools. In this case remember to NOT to install make from cygwin.
    • Add the cygwin path at the end and rename or delete the sh.exe files from WinAVR and YAGARTO tools

To be sure that this worked, open a new console and type

C:>sh
sh-3.1$

you should see that the version is 3.1 or 3.2, depending on what you did, but not 2.04, the one coming from WinAVR or YAGARTO.

If you know any better way to overcome these problems, we are opened for suggestions. Please let us know.

Fresh installation

Summarizing, if you are installing NutOS and NutDAC_Micro completely from the scratch, here is a step by step installation process that worked for us:

  • If you want to use Ethernut2 install WinAVR package. It includes the GNU utilities necessary in a development environment (make, sh, etc.). It will add its bin and utils/bin directories to the beginning of the system PATH.
  • If you want to use Ethernut3 install YAGARTO. It will add its bin directory to the end of the system PATH. It will add its bin directory to the system PATH. You will not need YAGARTO tools.
  • Install MinGW including the MSYS basic system and add its bin directory (in my case C:\MinGW\msys\1.0\bin) to the beginning of the windows PATH environment variable.

Now you should be able to install NutOS and NutDAC. Should you encounter other problems, please let us know.

§3.  Installation of NutDAC_GUI

NutDAC_GUI is distributed as a jar library and as source code.

Using the jar library does not require any special installation: simply add to your classpath the directory where you placed NutDAC_GUI-x.x.jar . If you are planning to use charts in a GUI you will also need JChart2d and its required third party libraries. You can get them straight from the JChart2D project or from the NutDAC_GUI sources, where they are all distributed as independent libraries (under the ext/lib directory). Using the version coming with NutDAC_GUI sources has the advantage of being tested already, but might contain some issues fixed in newer versions of JChart2D.

If you want NutDAC_GUI source code simply download the NutDAC_GUI-x.x.x.tar.bz2 (or zip) to a folder where you can call a java compiler from and uncompress it. As mentioned earlier, it already comes with all the necessary 3rd party libraries located in the ext/lib directory. NutDAC_GUI uses Ant to automate the build process, so if you don't have it you need to install it first.

To compile the library type

jose@Aut-019:~/PEM-workspace/NutDAC_GUI$ ant
Buildfile: build.xml

init:
    [mkdir] Created dir: /home/jose/PEM-workspace/NutDAC_GUI/bin
    [mkdir] Created dir: /home/jose/PEM-workspace/NutDAC_GUI/lib

build:
     [exec] java version "1.6.0_20"
     [exec] Java(TM) SE Runtime Environment (build 1.6.0_20-b02)
     [exec] Java HotSpot(TM) Server VM (build 16.3-b01, mixed mode)
    [javac] Compiling 66 source files to /home/jose/PEM-workspace/NutDAC_GUI/bin

BUILD SUCCESSFUL Total time: 3 seconds
You can create the jar library with

jose@Aut-019:~/PEM-workspace/NutDAC_GUI$ ant makejarFat

The newly created NutDAC_GUI-x.x.x.jar library will be placed into the NutDAC_GUI/lib/ directory. This jar file does NOT contain JChart2d neither its required 3rd party libraries.

For a detailed example of how create a NutDAC_GUI based project check the Creating new applications tutorial.