View source for Ethernut 1.3 H

[[Image:enut13.png|upright|thumb|400px|Ethernut 1.3 H]]

== Test Environments ==

{| class="smalldiv"
| style="background-color:#F6F9ED" | Board
| style="background-color:#F6F9ED" | Nut/OS
| style="background-color:#F6F9ED" | WinAVR
| style="background-color:#F6F9ED" | Tera Term
|-
| 1.3 H
| 2.6.4
| 20080610
| 4.61
|}

== Description ==

On this page you will learn how to setup an Ethernet 1.3 development and testing environment.

You will learn the '''easiest way''' on how to use the examples from nutwiki and your own applications.
This Guide is not supposed to be a complete manual but as a Quick Start Guide, teaching one of the many methods to get an application running on your Ethernut board.

Immediatly after working through this document, you have the competence to test the examples featured by nutwiki.

Additionally all major topics are also covered in screencasts (Win only).

# [[Image:flashvideo.png|16px]] [http://ethernut.de/arc/screencasts/ENUT13CONFIGURATOR.htm Screencast Part 1] The Nut/OS Configurator
# [[Image:flashvideo.png|16px]] [http://ethernut.de/arc/screencasts/ENUT13PREP.htm Screencast Part 2] Preparations
# [[Image:flashvideo.png|16px]] [http://ethernut.de/arc/screencasts/ENUT13BURN.htm Screencast Part 3] Compiling and Burning
# [[Image:flashvideo.png|16px]] [http://ethernut.de/arc/screencasts/TERATERM.htm Screencast Part 4] Serial Communications / TeraTerm
<br>

== [[Image:winpath.png|24px]] Required Tools for Windows ==
=== Nut/OS ===
Of course you need the latest version of Nut/OS.

Visit this page to download the latest version for Win32:<br>
Download: [http://ethernut.de/en/download/index.html http://ethernut.de/en/download/index.html]

Nut/OS for Windows features an installer which will do most of the work for you.

It is recommended to install the ethernut folder directly on the root directory: 
 [[Image:winpath.png|24px]] C:/ethernut-4.6.4/ 
'''Note:''' All paths in this guide refer to that location and will be referred to as "ethernut folder/directory" or "/ethernut-4.6.4"

=== Tera Term ===
[http://ttssh2.sourceforge.jp/ Tera Term] is a so called terminal emulator. We use it to communicate via COM with the board.

Download: [http://sourceforge.jp/projects/ttssh2/releases/ http://sourceforge.jp/projects/ttssh2/releases/]

=== WinAVR ===
[http://winavr.sourceforge.net/index.html WinAVR] (pronounced "whenever") is a suite of executable, open source software development tools for the Atmel AVR series of RISC microprocessors hosted on the Windows platform.

It includes the GNU GCC compiler for C and C++. 

Download: [http://sourceforge.net/project/showfiles.php?group_id=68108 http://sourceforge.net/project/showfiles.php?group_id=68108]

It is recommended to install the WinAVR folder directly on the root directory:
 [[Image:winpath.png|24px]] C:/winavr/
'''Note:''' All paths in this guide refer to that location!

=== Text Editor ===
You can use any text editor you want.
Some recommended ones include:
* [http://www.eclipse.org/ Eclipse] Open Source
* [http://www.e-texteditor.com/ The e Text Editor] Commercial, Trial

== [[Image:linuxpath.png|24px]] Required Tools for Linux==

=== Essential Tools ===
The following GNU tools are required to configure and build a minimal Nut/OS development environment: 
* C compiler 4.1 or later
* Binutils 2.18 or later
* Autoconf 2.61
* Automake 1.10

=== AVR cross toolchain ===
Furthermore, you need a so called cross toolchain, which allows us to create binaries on a Linux host, which will later run on our target board. When developing for 8-bit AVR, we need 
* GNU Compiler Collection for AVR
* GNU Binary Utilities for AVR
* AVRDUDE programmer software

=== WxWidgets ===
[http://www.wxwidgets.org/ wxWidgets] is a cross-platform C++ GUI framework, required for Nut/OS configurator GUI.

=== Lua ===
[http://www.lua.org/ Lua] is an embeddable scripting language, which is used here to specify the configuration rules. This is also required for Nut/OS configurator to run.

=== Nut/OS ===
Of course you need the latest version of Nut/OS.

Visit this page to download the latest source code package for Linux (Debian):<br>
Download: [http://ethernut.de/en/download/index.html http://ethernut.de/en/download/index.html]

It is recommended to create a new folder named "ethernut" in your home directory and copy the source code package in to this directory before unpacking it. The complete sequence of shell command for installing Nut/OS is:
[[Image:linuxpath.png|24px|right]] 
 mkdir ~/ethernut
 cp ethernut-4.6.4.tar.bz2 ~/ethernut
 cd ~/ethernut
 tar -xjf ethernut-4.6.4.tar.bz2
 ln -s ethernut-4.6.4 nut
 cd nut/
 ./configure
 make
 sudo make install
'''Note:''' All paths in this guide refer to that location and will be referred to as "ethernut folder/directory" or "/ethernut"

http://www.ethernut.de/en/documents/debian.html provides more informations about installing Nut/OS on Linux.

=== Minicom ===
[http://alioth.debian.org/projects/minicom/ Minicom] is a so called terminal emulator. We use it to communicate via COM with the board.

== The Nut/OS Configurator ==

[[Image:flashvideo.png|64px]][http://ethernut.de/arc/screencasts/ENUT13CONFIGURATOR.htm Screencast Part 1]

In order to build an optimized Nut/OS for you needs you have to configure it.

''In some examples from nutwiki you are asked to setup something in the Nut/OS configurator. This is the time and place to do so.''


In general the workflow is as following:

1. Start the Nut/OS Configurator:
[[Image:winpath.png|24px|right]] 
 Start &gt; Programs &gt; Ethernut 4.6.4 &gt; Configurator

[[Image:linuxpath.png|24px|right]]
 cd ~/ethernut
 nutconf
2. Select and open the configuration file for your board:
 ethernut103.conf for old Ethernuts with ATmega103
 ethernut13f.conf for Ethernut 1.3 Rev-F and earlier
 ethernut13g.conf for Ethernut 1.3 Rev-G and later

3. Click on Menubar: '''Edit > Settings'''<br>
* Goto Tab: '''Build'''
** Choose Platform: '''avr-gcc'''
** Choose Build Directory: '''nutbld_enut13'''
* Goto Tab: '''Tools'''
** [[Image:winpath.png|24px]] Enter Tool Paths: '''c:\ethernut-4.6.4\nut\tools\win32;c:\winavr\utils\bin;c:\winavr\bin;''' (Win only, left bank on Linux)<br>
* Goto Tab: '''Samples'''
** Choose Application Directory: '''nutapp_enut13'''
** Choose Programmer: '''avr-dude'''
* Click '''OK'''
4. Click on Menubar: '''Build > Build Nut/OS'''<br>
* Say '''OK''' 2 times.
5. Click on Menubar: '''Build > Create Sample Directory'''<br>
* Say '''OK'''

<br>
'''Note:''' You should create a new sample directory every time you build a new system, even if you do not want to use the samples. There are two files named
* Makerules
* Makedefs
in that directory, that are necessary for every application to compile.
<br><br>

Nut/OS Configurator built a customized version for your needs and put it in:
 \ethernut-4.6.4\nutbld_enut13\

Additionally it created an associated Sample Application Directory with source codes ready to compile:
 \ethernut-4.6.4\nutapp_enut13\

== Preparations ==

[[Image:flashvideo.png|64px]][http://ethernut.de/arc/screencasts/ENUT13PREP.htm Screencast Part 2]

=== Application Directory ===
First of all we need a home for our application. 

Create a new directory "'''testcode'''" in
 \ethernut-4.6.4\nutapp_enut13\

You can, of course, use any names you want.

=== Editing ===
1. Write your application code, or for testing purposes, paste in an example code from nutwiki in a plain text file.

2. Save it as <code>testcode.c</code> in:
 \ethernut-4.6.4\nutapp_enut13\testcode\

'''Note:''' Make sure, that in your Windows folder options, the setting 'Hide file extensions for unknown file types' is deactivated! If not, you will create .txt files instead of .c or Makefiles, when saving in the Editor!

=== Makefile ===
For our applications to compile, we need a makefile.

This is used and interpreted by a tool called GNU Make, which we will use later.

Makefiles may differ from application to application, but the following is a general purpose one, which will work for basic applications.<br>
Later, when you are familiar with Nut/OS and makefiles you can create your own ones.

'''Note''', that in this example makefile, the project name,
<source lang="text">
PROJ = testcode
</source>
has to be identical to the name of your application's <code>.c</code> file!

<source lang="text">
PROJ = testcode

include ../Makedefs

SRCS =  $(PROJ).c
OBJS =  $(SRCS:.c=.o)
LIBS =  $(LIBDIR)/nutinit.o -lnutpro -lnutos -lnutnet -lnutfs -lnutcrt -lnutdev -lnutarch
TARG =  $(PROJ).hex

all: $(OBJS) $(TARG) $(ITARG) $(DTARG)

include ../Makerules

clean:
	-rm -f $(OBJS)
	-rm -f $(TARG) $(ITARG) $(DTARG)
</source>
'''Note''', when copy and pasting the above Makefile: the spaces before '''-rm...''' have to be '''tabs''' instead of normal spaces!



Create a plain text file and paste in the code above. 

Call it <code>Makefile</code> (Without any file extension) and save it to:
 \ethernut-4.6.4\nutapp_enut13\testcode\

=== Configuration Files ===
The files
* Makedefs
* Makerules
from
 \ethernut-4.6.4\nutapp_enut13\
are essential.
By building a new Nut/OS and a new sample directory (nutapp_enut13) these files get updated. 
Your application directory (testcode) will remain untouched.

(If you used different paths, note, that the configuration files have to be located in the top directory of the apllication directory.)

'''Note:''' You have to build a new sample directory and move 'Makedefs' and 'Makerules' to your application's parent directory (if your app directory is not already a subfolder of "nutapp_enut13" as recommended) every time you build a new Nut/OS!

=== Path environment (Win only) ===


Every command line session has its own PATH variable. 

Applications like GNU Make look up paths in that variable.

We need to add to the path variable our tools:
 [[Image:winpath.png|24px]] C:/ethernut-4.6.4/nut/tools/win32;c:/winavr/utils/bin;c:/winavr/bin;

To do so, we could enter in the command line prompt:
 SET PATH=c:/ethernut-4.6.4/nut/tools/win32;c:/winavr/utils/bin;c:/winavr/bin;%PATH%

(The <code>%PATH%</code> at the end appends the original content of the PATH variable to the newly set.<br>
By leaving that out the PATH gets overwritten.)

Because every time you close the command line prompt your PATH variable gets lost,<br>
there is a better way to handle it.


1. Create a plain text file and enter:
 SET PATH=c:/ethernut-4.6.4/nut/tools/win32;c:/winavr/utils/bin;c:/winavr/bin;%PATH%

2. Name it <code>AVR.bat</code> and save it to:
 [[Image:winpath.png|24px]] C:\ethernut-4.6.4\nutapp_enut13\testcode\

This is called a Batch file.<br>
Everytime you type in <code>AVR</code> in the <code>testcode</code> directory now, the PATH variable gets set.<br>
You have to execute <code>AVR</code> every time after you open a new command line window.<br>
If you do not, GNU Make will not find the tools.<br>

=== Connecting ===

To connect your Ethernut 1.3

*Connect the SP DUO to Ethernut's JTAG connector
*Connect the SP DUO to an available COM port of your computer using the serial cable.
*Connect the power supply to the barrel connector on the Ethernut board. The
Ethernut board is equipped with its own rectifier bridge and voltage regulator.
Therefore the polarity of the barrel connector isn't important.
*Apply power to the Ethernut board by connecting the power supply to an
electrical outlet. When the board is powered up, the red power LED should go
on.


For further details have a look at the [http://ethernut.de/pdf/enhwm13e.pdf Hardware Manual]

== Compiling and Burning ==

[[Image:flashvideo.png|64px]][http://ethernut.de/arc/screencasts/ENUT13BURN.htm Screencast Part 3]

Now its time to compile.

1. Open a command line window.[[Image:winpath.png|24px]] / Shell window [[Image:linuxpath.png|24px]]

2. Change to
 [[Image:winpath.png|24px]] C:\ethernut-4.6.4\nutapp_enut13\testcode\

 [[Image:linuxpath.png|24px]] ~/ethernut-4.6.4/nutapp_enut13/testcode/

3. Enter: Windows only!
<div class="konsole">[[Image:winpath.png|24px]] SET PATH=c:\ethernut-4.6.4\nut\tools\win32;c:\winavr\utils\bin;c:\winavr/bin;%PATH%</div>
or
<div class="konsole">[[Image:winpath.png|24px]] AVR</div>
if you are using a batch file.

4. Enter:

 <div class="konsole">make clean</div>

''This tells "Make" to clean up the directory with respect to the rules made in the Makefile''

You should get something like:
<div class="konsole">
rm -f testcode.o

rm -f testcode.hex testcode.bin testcode.elf<br>
rm -f testcode.eep<br>
rm -f testcode.obj<br>
rm -f testcode.map<br>
rm -f testcode.lst<br>
rm -f testcode.bak<br>
rm -f testcode.i<br>
</div>
If not, you maybe left out step 3.

=== 'Make Burn' ===
1. Connect your Ethernut 1.3. (for further details take a look at the [http://ethernut.de/pdf/enhwm13e.pdf Hardware Manual])
* Power Supply
* COM to SP DUO to JTAG

2. Enter:
<div class="konsole"> make burn</div>

This '''compiles''' the necessary files for you '''and''' a tool called avr-dude '''burns''' the binaries onto your Ethernut board's flash storage.

''To configure avr-dude, please edit the following file:''<br>
 \ethernut-4.6.4\nut\app\Makeburn.avr-dude

[[Image:winpath.png|24px]]
'''BURNPORT=com1'''(2,3..etc.)
[[Image:linuxpath.png|24px]]
'''BURNPORT=/dev/ttyS0'''(1,2,3..etc.)

== Serial Communications / Tera Term ==

[[Image:flashvideo.png|64px]][http://ethernut.de/arc/screencasts/TERATERM.htm Screencast Part 4]

Done. All you have to do now, is to connect the serial cable to the Ethernut's COM Port and start '''TeraTerm''' or any other serial communications tool.

Configure TeraTerm with the follwing settings:
*Menubar > Setup > Serial port...
**Baud rate: '''115200'''
**Data: '''8Bit'''
**Parity: '''None'''
**Stop: '''1bit'''
**Flow control: '''none'''
**Transmit delay: '''0''';'''0'''


Now reset your Ethernut board and you will (hopefully) see the output.

== Important things to remember ==
In order to not get frustrated remember:

* Make sure, that the setting 'Hide file extensions for unknown file types' is deactivated in you Windows folder options. Otherwise, 'Editor' won't create proper .c or Makefiles.
* In the Makefile, make sure, that the project name is identical to your <code>.c</code> file's name!
* Update the PATH variable every time you open a new command line prompt! Write a batch file for that.
* You have to build a new sample directory and move 'Makedefs' and 'Makerules' from there to your application's parent directory every time you build a new Nut/OS with the Configurator! 
* To configure avr-dude and toggle the COM port for example, please edit the following file: <code>c:\ethernut-4.7.4\nut\app\Makeburn.avr-dude</code>

== See also ==
* [[Nut/OS Examples]]
* [[Hello World!]] Example

== External Links ==

[http://ethernut.de/pdf/enhwm13e.pdf] Ethernut 1.3 Rev-G Hardware Manual (November 2005)

[http://ethernut.de/pdf/enswm24e.pdf] Ethernut Software Manual (November 2005)


<br>

[[Category:Code Snippets]]

{{Languages}}