Harald: 1 revision imported

2016-10-27T16:02:54Z

1 revision imported

Daniel: /* Makefile */

2009-03-12T16:39:26Z

‎Makefile

New page

[[Image:eir10c-overview.png|upright|400px|thumb|Elektor Internet Radio 1.0 C]]

== Test Environments ==

{| class="smalldiv"
| style="background-color:#F6F9ED" | Board
| style="background-color:#F6F9ED" | Nut/OS
| style="background-color:#F6F9ED" | YAGARTO
| style="background-color:#F6F9ED" | Tera Term
|-
| EIR 1.0 C
| 2.6.4
| 20080928
| 4.61
|}

== Description ==

On this page you will learn how to setup an '''E'''lektor '''I'''nternet '''R'''adio development and testing environment.

Your EIR comes with the webradio software installed and ready-to-use. So if you just want to use it as a radio you're done. Please consult the documents on the EIR CD for further assistance e.g. on how to use the web interface.

This guide concentrates on how to upload applications to Your EIR and consists of two sections .

*In the first section You will learn the '''easiest way''' on how to use the examples from nutwiki and your own applications.
*The [[#Repitutorium: Restoring the webradio firmware|second section]] is a step-by-step style tutorial that uses the workflow from section one and explaines You how to '''restore the webradio firmware''' in case you have deleted or overwritten it.

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.

Screencasts:

# [[Image:flashvideo.png|16px]] [http://ethernut.de/arc/screencasts/EIR10CONFIGURATOR.htm Screencast Part 1] The Nut/OS Configurator
# [[Image:flashvideo.png|16px]] [http://ethernut.de/arc/screencasts/EIR10PREP.htm Screencast Part 2] Preparations
# [[Image:flashvideo.png|16px]] [http://ethernut.de/arc/screencasts/EIR10COMPILE.htm Screencast Part 3] Compiling the source code
# [[Image:flashvideo.png|16px]] [http://ethernut.de/arc/screencasts/EIR10SAMBA.htm Screencast Part 4] Using SAM-BA / Uploading
# [[Image:flashvideo.png|16px]] [http://ethernut.de/arc/screencasts/TERATERM.htm Screencast Part 5] Serial Communications / TeraTerm

== Required Tools ==

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

Visit this page to download the latest version for Win32: 
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!

=== AT91 In-system Programmer (ISP)===
[http://www.atmel.com/dyn/products/tools_card.asp?tool_id=3883 AT91 ISP] provides an open set of tools for programming the AT91SAM7 and AT91SAM9 ARM-based microcontrollers.

It includes the SAM Boot Assistant ('''SAM-BA'''), which we will be using to upload applications to EIR.

Download: [http://www.atmel.com/dyn/products/tools_card.asp?tool_id=3883 http://www.atmel.com/dyn/products/tools_card.asp?tool_id=3883] + Installation Guide
=== YAGARTO ===
[http://winavr.sourceforge.net/index.html WinAVR] is a very fast, self-contained GCC toolchain for ARM for Windows.

It includes Binutils, Newlib, GCC compiler, and the Insight debugger.

An installation guide can be found [http://www.yagarto.de/howto/yagarto1/index.html here]

Download: [http://sourceforge.net/project/showfiles.php?group_id=211530&package_id=254273 http://sourceforge.net/project/showfiles.php?group_id=211530&package_id=254273]

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

=== 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/]

=== 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

== The Nut/OS Configurator ==

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

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

''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]] C:\ethernut-4.6.4\nutconf.exe
2. Select and open the configuration file:
[[Image:winpath.png|24px]] C:\ethernut-4.6.4\nut\conf\eir10c.conf
3. Click on Menubar: '''Edit > Settings''' 
* Goto Tab: '''Build'''
** Choose Platform: '''arm-gcc'''
** Choose Build Directory: '''nutbld_eir10c'''
* Goto Tab: '''Tools'''
** Enter Tool Paths: '''c:\ethernut-4.6.4\nut\tools\win32;c:\yagarto\bin;''' (Do not forget the last semicolon and modify paths if you used other locations as described above.)
* Goto Tab: '''Samples'''
** Choose Application Directory: '''nutapp_eir10c'''
** Choose Programmer: '''arm-jom'''
* Click '''OK'''
4. In the Nut/OS Components tree (left)
* Expand Tools
** Expand GCC Settings
*** Click on ARM Linker Script
**** Choose '''at91sam7se512_rom''' from the dropdown menu.
By choosing the Linker Script, you specify, in which kind of memory your application will run.
We are using 'at91sam7se512_rom' here, because we are going to upload the application via a Bootloader (in ROM) directly into FLASH and run it in there.

5. Click on Menubar: '''Build > Build Nut/OS''' 
* Say '''OK''' 2 times.
6. Click on Menubar: '''Build > Create Sample Directory''' 
* Say '''OK'''

 
'''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.
 

Nut/OS Configurator built a customized version for your needs and put it in:
[[Image:winpath.png|24px]] C:\ethernut-4.6.4\nutbld_eir10c\

Additionally it created an Sample Application Directory with source codes ready to compile:
[[Image:winpath.png|24px]] C:\ethernut-4.6.4\nutapp_eir10c\

== Preparations ==

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

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

Create a new directory "'''testcode'''" in
[[Image:winpath.png|24px]] C:\ethernut-4.6.4\nutapp_eir10c\

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:
[[Image:winpath.png|24px]] C:\ethernut-4.6.4\nutapp_eir10c\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. 
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 -lnutarch -lnutdev -lnutarch -lnutnet -lnutfs -lnutcrt
TARG = $(PROJ).hex
PARM = $(PROJ).eep

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

include ../Makerules

clean:
-rm -f $(OBJS)
-rm -f $(TARG) $(ITARG) $(DTARG)
-rm -f $(PROJ).eep
-rm -f $(PROJ).obj
-rm -f $(PROJ).map
-rm -f $(SRCS:.c=.lst)
-rm -f $(SRCS:.c=.bak)
-rm -f $(SRCS:.c=.i)
</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:
[[Image:winpath.png|24px]] C:\ethernut-4.6.4\nutapp_eir10c\testcode\

=== Configuration Files ===
The files
* Makedefs
* Makerules
from
[[Image:winpath.png|24px]] C:\ethernut-4.6.4\nutapp_eir10c\
are essential.
By building a new Nut/OS and a new sample directory (nutapp_eir10c) 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_eir10c" as recommended) every time you build a new Nut/OS!

=== Path environment ===
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:
C:/ethernut-4.6.4/nut/tools/win32;c:/yagarto/bin;

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

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

Because every time you close the command line prompt your PATH variable gets lost, 
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:/yagarto/bin;%PATH%

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

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

=== Connecting ===

To connect your EIR

*Use a standard USB cable to connect the EIR board to any free USB port on your PC.
*Connect EIR`s DB-9 RS232 port to an available COM port using the serial cable.
*Use one twisted pair cable to connect Ethernut's RJ-45 connector to the hub / switch / router and the other twisted pair cable to connect the hub / switch / router with the
network adapter in the PC. If you are not using a hub or switch, then directly
connect the EIR board with the PC’s network adapter using a twisted pair
cross cable.
*Connect the power supply to the barrel connector on the EIR board.
*Apply power to the EIR 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/eir_um_1_0_6.pdf Hardware Manual]

== Compiling and Using the Bootloader==

Basically, the workflow is as following.

# Compiling the source code.
# Erasing EIR's flash storage by a jumper setting
# Using SAM-BA to upload the binaries to the EIR flash storage

=== Compiling ===

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

1. Open a command line window.

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

3. Enter:
[[Image:winpath.png|24px]] SET PATH=c:/ethernut-4.6.4/nut/tools/win32;c:/yagarto/bin;%PATH%
or
[[Image:winpath.png|24px]] ARM
if you are using a batch file.

4. Enter:

make clean

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

You should get something like:
rm -f testcode.o
rm -f testcode.hex testcode.bin testcode.elf
rm -f testcode.eep
rm -f testcode.obj
rm -f testcode.map
rm -f testcode.lst
rm -f testcode.bak
rm -f testcode.i

If not, you maybe left out step 3.

5. Enter:
make install

This should get you something like:

arm-elf-gcc -c -mcpu=arm7tdmi -Os -mthumb-interwork -fomit-frame-pointer -Wall -Wstrict-prototypes
-fverbose-asm -Wa,-ahlms=testcode.lst -DELEKTOR_IR1 -I../../nutbld_eir10c/include
-I../../nut/include testcode.c -o testcode.o
testcode.c: In function 'main':
testcode.c:11: warning: implicit declaration of function '_ioctl'
testcode.c:18:2: warning: no newline at end of file
arm-elf-gcc testcode.o -mcpu=arm7tdmi
-nostartfiles -T../../nut/arch/arm/ldscripts/at91sam7se512_rom.ld -Wl,-Map=testcode.map,
--cref,--no-warn-mismatch -L../../nutbld_eir10c/lib
-Wl,--start-group ../../nutbld_eir10c/lib/nutinit.o -lnutpro -lnutos -lnutarch -lnutdev -lnutarch
-lnutnet -lnutfs -lnutcrt -Wl,--end-group -o testcode.elf
arm-elf-objcopy -O ihex testcode.elf testcode.hex
arm-elf-objcopy -O binary testcode.elf testcode.bin

This command compiled the source code and generated the binary files beside some other files in
[[Image:winpath.png|24px]] C:\ethernut-4.6.4\nutapp_eir10c\testcode\

=== Erasing the Flash Storage ===

On the EIR board connect pins 34 and 36 of K3 (Port C) using a 2.54 mm jumper.

Press the reset button and remove the jumper. This erases the flash storage and also activates the SAM-BA boot loader.

'''Note:'''This procedure has to be done everytime before using SAM-BA.

[[Image:eir_j1.jpg|300px]]

=== Using SAM-BA ===

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

1. Launch SAM-BA

2. In the popup dialog:
* Selct the connection should say '''\usb\ARM0'''
If not, try to deplug and plug the USB cable again. Try to erase the flash again. Then restart SAM-BA
* Select your board: '''AT91SAM7SE512-EK'''
* Press: '''Connect'''

3. In the SAM-BA main window
* In the tab '''Flash'''
** Send file name: Browse to: [[Image:winpath.png|24px]] C:\ethernut-4.6.4\nutapp_eir10c\testcode\testcode.bin
** Press: '''Send File''' This initiates the actual uploading process.
** Press: '''Compare sent file with memory''' to make sure, your file was transfered correctly.
** In the section: '''Scripts'''
*** Choose: '''Boot from Flash (GPNVM2)'''
*** Press: '''Execute'''
* Quit SAM-BA

4. Reset Your EIR by depressing and releasing the reset switch behind the USB connector.

== Serial Communications / Tera Term ==

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

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 see the output imediately, as the app is stored in flash.

== Repitutorium: Restoring the webradio firmware ==

=== Description ===

This is a brief tutorial on how to restore the original webradio firmware using the methods explained above.

=== Workflow ===

1. Download the most recent '''webradio firmware''' from [http://ethernut.de/en/hardware/eir/index.html http://ethernut.de/en/hardware/eir/index.html] under 'Software'

2. Use the '''Nut/OS Configurator''' to build a Nut/OS for EIR. Also create a sample directory. [ [[#The Nut/OS Configurator|Details]] ]

3. Decompress the webradio .zip file and copy the resulting folder 'webradio' to the application directory. (\nutapp_eir10c\webradio\)

4. Now You have the '''choice'''. The webradio package comes with source code and pre-compiled binaries. So:
* If you want to use the pre-compiles binaries proceed to step 5.
'''or'''
* If you want to compile the '''sources''' (.h, .c) by yourself do the following: (Note, that a Makefile is provided)
** In a '''command line prompt''':
*** '''Change to''' the webradio directory
*** Set the path variable to: '''c:/ethernut-4.6.4/nut/tools/win32;c:/yagarto/bin;''' [ [[#Path environment|Details]] ]
*** Use the commands <code>make clean</code> to clean and <code>make all</code> to '''compile''' the webradio source files. [ [[#Compiling|Details]] ]
** You should end up with a bunch of files including '''webradio.bin'''

5. Erase the Flash memory and activate SAM-BA bootloader [ [[#Erasing the Flash Storage|Details]] ]

6. Launch SAM-BA
* Connect to your board via USB
* Choose '''webradio.bin''' as your file to send.
* Compare sent file with memory.
* Execute the script Boot from Flash (GPNVM2).
[ [[#Using SAM-BA|Details]] ]

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

* When entering the tool paths in the Configurator, do not forget the semicolon at the end of the line!
* 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 bash 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!
* Use 'at91sam7se512_rom' as ARM Linker Script (Nut/OS Configurator), when using the SAM-BA method.

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

== External Links ==

[http://ethernut.de/pdf/eir_um_1_0_6.pdf] EIR 1.0 Hardware Manual (Mai 2008)

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

[http://www.egnite.de/fileadmin/presse/071081-UK_Webradio.pdf] Elektor Article on EIR (April 2008, issue 376) [ [http://www.egnite.de/fileadmin/presse/071081-D_Webradio.pdf GER] ]

[http://ethernut.de/en/hardware/eir/index.html] EIR 1.0 section on ethernut.de

[http://www.myway.de/ElectronicFreak/EIR.html] Christian Schöning created a document about how to use the EIR with Eclipse (German language).

[http://www.yagarto.de/] YAGARTO site with lots of HowTos e.g. debugging.

[http://www.gnuarm.org/] Similar to YAGARTO, but additionally supports Mac OS X.

[http://www.vlsi.fi/] The website of VLSI Solution Oy, who offers the VS1053 audio codec.

 

[[Category:Code Snippets]]

{{Languages}}

← Older revision	Revision as of 16:02, 27 October 2016
(No difference)

Elektor Internet Radio 1.0 - Revision history

Harald: 1 revision imported

Daniel: /* Makefile */