osd-contiki/doc/tutorial-raven.txt

/**
\addtogroup tutorials
@{
*/

/**
 * \defgroup tutorialraven Running Contiki with uIPv6 and SICSlowpan support on Atmel RAVEN hardware
 * @{
This tutorial explains how to run Contiki with IPv6 and 6lowpan
support on Atmel RAVEN hardware.


\section toc Table of contents
\ref introduction<br>
\ref hardware<br>
\ref software<br>
\ref overview<br>
\ref installation<br>
\ref running<br>
\ref advanced<br>
\ref issues<br>
\ref annex<br>

<HR>
\section introduction Introduction
This tutorial explains how to run Contiki with IPv6 and 6lowpan
support on Atmel RAVEN evaluation kit (ATAVRRZRAVEN) hardware. We
present basic example system architecture and application scenarios,
as well as instructions to run more advanced demos.

<HR>
\section hardware Hardware requirements

To run the demo, you will need at least
\li one AVR RAVEN board, which embeds an ATmega1284P and an
ATmega3290P micro controller (MCU) as well as an AT86RF230 
802.15.4 radio chip.
\li one RZ USB stick, which embeds an AT90USB1287 MCU and
an AT86RF230 802.15.4 radio chip.
\li one PC running Windows to program the chips. For the demo
itself, a PC running Linux or Windows.
\li one On-chip programming platform. We recommend Atmel JTAGICE
mkII.

\note Links to detailed hardware documentation are in
\ref annex_hardware

<HR>
\section software Software requirements
To install the demo you need:
\li Contiki 2.3 or later source code, installed in a directory. In 
the rest of this tutorial we assume the directory is c:/contiki
\li Cygwin with "make" utility installed.
\li AVR Studio 4.14 or later
\li WinAVR20080610 or later
\li Windows drivers installed for the JTAGICE mkII.

Instructions to install these tools are in the section \ref annex_software.<br>

To run the demo, you need:
\li one PC running Linux with kernel 2.6.24 or later, with support for the
following kernel modules: IPv6, usbnet, cdc_ether, cdc_acm, rndis_wlan.
\li OR one PC running Windows with IPv6 support. If you use Windows XP,
you need Service Pack 3 installed.

\note
On windows XP, if ipv6 support is not enabled, enable it by typing
in a shell:
\verbatim
ipv6 install
\endverbatim


<HR>
\section overview Demo Overview

\subsection overview_architecture Network Architecture
The network comprises:
\li a PC acting as an IPv6 router with an 802.15.4 interface
and an Ethernet interface.
\li a RAVEN board acting as an IPv6 host.

In the basic demo, you can:
\li Ping the RAVEN Board from the router
\li Ping the router from the RAVEN board, using the RAVEN board
menu
\li Browse the web server running on the RAVEN board. The server
displays the live temperature measured from the board temperature
sensor

\image html tutorial-raven-basic.jpg
<HR>
\section installation Compiling, installing, configuring

\subsection installation_compiling Compiling the binaries for RAVEN and RZ USB stick
The binaries needed are:
\li c:/contiki/examples/webserver-ipv6/webserver6.elf file for the RAVEN board ATmega1284P
\li c:/contiki/platform/avr-ravenlcd/ravenlcd_3290.elf file for the RAVEN board ATmega3290P
\li c:/contiki/examples/ravenusbstick/ravenusbstick.elf file for the RZ USB Stick AT90USB1287

To compile each of them, type in Cygwin:
\verbatim
cd c:/contiki/examples/webserver-ipv6-raven
make TARGET=avr-raven webserver6.elf
\endverbatim
\verbatim
cd c:/contiki/platform/avr-ravenlcd
make
\endverbatim
\verbatim
cd c:/contiki/examples/ravenusbstick
make
\endverbatim


\subsection installation_hw Installing the hardware
To power the RAVEN, put the EXT/BAT jumper in BAT position.
This will enable power on batteries. If you want to power 
the RAVEN externally, check instructions in 
\ref advanced_externalboard.

The RZ USB Stick needs to be plugged in the PC you will run 
the demo on. If you plan to run the demo on a Windows PC, you
will need to install drivers once contiki is loaded on the 
stick. Until then, you can exit any driver installation popup.

\subsection installation_loading Programming the boards
<b>What you need to do</b><br>

\li On the RAVEN board, program the binaries on both AVR ATmega.
\li On the RZ USB Stick, load the binary on the AT90USB1287

<b>Hardware connections</b><br>
\li Connect the JTAG connectors to the JTAGICE as described in 
the picture below.

\image html tutorial-raven-jtag.jpg
\li Connect the JTAGICE mkII to a Windows PC through USB.
\li To program (load) each AVR, you will need to connect the 
JTAGICE JTAG connector to the JTAG pins corresponding to the 
AVR you want to program, as shown in the picture below.

\image html tutorial-raven-connections.jpg 


<b>To load the binary on each AVR in Windows</b><br>

\li Launch AVR Studio and exit any popup window.
\li Connect the JTAG pins of the JTAGICE into the JTAG connector of
the target processor.
\li In AVR Studio, click on "Tools"->"Program AVR"->"Auto Connect"
\li Go to the "Main tab"
\li In the "Programming mode and target settings" list, select JTAG
\li Select the processor type in the "Device" list and click
"Read Signature". If the Device signature is read properly,
it means AVR Studio is properly connected to the AVR.
\li Go to the "Program" tab
\li In the "ELF Production file format" section,
browse to the binary, then click program

\verbatim
For webserver6.elf, set the processor to ATmega1284P
For ravenlcd_3290.elf, set the processor to ATmega3290P
For ravenusbstick.elf, set the processor to AT90USB1287

\endverbatim

Once the RZ USB Stick is programmed, unplug it from the PC.
Note this programmed the fuses, EEPROM, and FLASH all at once.



<HR>
\section running Running the basic demo
\subsection running_router Setting up the router
<b>On Linux</b><br>
Plug the RZ USB Stick in the PC. It should appear as a USB
network interface (e.g. usb0).

usb0 should automatically get an IPv6 link local address, i.e. 
fe80::0012:13ff:fe14:1516/64. Check this is the case by typing 
\verbatim
ifconfig
\endverbatim
and checking the addresses of interface usb0

If it does not, add it manually:
\verbatim
ip -6 address add fe80::0012:13ff:fe14:1516/64 scope link dev usb0
\endverbatim

Configure the IP addresses on usb0
\verbatim
ip -6 address add aaaa::1/64 dev usb0
\endverbatim

Install the radvd deamon and configure it so the usb0
interface advertises the aaaa::/64 prefix as on link
and usable for address autoconfiguration.


Radvd configuration (usually in /etc/radvd.conf)
\verbatim
interface usb0
{
    AdvSendAdvert on;
    AdvLinkMTU 1280;
    AdvCurHopLimit 128;
    AdvReachableTime 360000;
    MinRtrAdvInterval 100;
    MaxRtrAdvInterval 150;
    AdvDefaultLifetime 200;
    prefix AAAA::/64
    {
        AdvOnLink on;
        AdvAutonomous on;
        AdvPreferredLifetime 4294967295; 
        AdvValidLifetime 4294967295; 
    };
};
\endverbatim
\note This values have been carefuly chosen to work on platform using
a 16bit clock.

Restart the radvd daemon. Example command:
\verbatim
/etc/init.d/radvd restart
\endverbatim

If you get a message that radvd won't start as forwarding isn't enabled,
you can run this as root:

\verbatim
echo 1 > /proc/sys/net/ipv6/conf/all/forwarding
\endverbatim

<b>On Windows</b><br>

Plug the RZ USB Stick in the PC. A "new hardware installation"
window should pop up. If it does not, go to "Control Panel"->
"Add Hardware". Choose "Install the driver manually", then
select the search path C:\\contiki\\cpu\\avr\\dev\\usb\\INF. Finish
the installation. 

You now need to get the "interface index" of the USB Stick 
interface (noted [interface index] in the following) and the 
Ethernet interface (noted [ethernet interface index] in the 
following).

In a DOS or Cygwin shell, type 
\verbatim
ipv6 if
\endverbatim

As an example, the output might look something like this:

\verbatim
...
Interface 7: Ethernet
 ...
 link-layer address: 02-12-13-14-15-16
 preferred link-local fe80::12:13ff:fe14:1516, life infinite
 ...
Interface 4: Ethernet: Local Area Connection
 ...
 link-layer address: 00-1e-37-16-5d-83
 preferred link-local fe80::21e:37ff:fe16:5d83, life infinite
 ...
...
\endverbatim

Note the link-layer address associated with interface 7 is the USB Stick. Hence
[interface index] is 7, [ethernet interface index] is 4 and [ethernet
link-local address] is fe80::21e:37ff:fe16:5d83.

Then you need to
\li Set the USB Stick interface as an advertising interface
\li Configure a global IP address on the USB Stick interface
\li Add a default route through the Ethernet interface
\li Set the aaaa::/64 prefix as "on link" and published on the USB Stick
interface.

To do so, type:
\code
ipv6 ifc [interface index] advertises forwards
ipv6 adu [interface index]/aaaa::1
ipv6 rtu ::/0 [ethernet interface index]/[ethernet link-local address]
publish
ipv6 rtu aaaa::/64 [interface index] publish
\endcode


\subsection running_raven Booting the RAVEN boards

Reboot the RAVEN board.
The PC sends router advertisements and the RAVEN Board configures 
an IPv6 global address based on them. The PC global addresses 
were set above. Communication is ready.

\subsection running_ping1 Pinging the RAVEN board from the router
On Windows (Cygwin shell) or Linux, type
\verbatim
ping6 -n 5 aaaa::11:22ff:fe33:4455
\endverbatim
or
\verbatim
ping6 -s aaaa::1 aaaa::11:22ff:fe33:4455
\endverbatim
The router is sending 5 echo requests to the RAVEN board. The RAVEN board
answers with 5 echo replies.

\subsection running_ping2 Pinging the router from the RAVEN board
To send a ping from the RAVEN to the router you need to use the
RAVEN's joystick and LCD screen. Initially, the LCD screen should
print CONTIKI - 6LOWPAN in a loop. You can navigate the LCD menu by
using the small joystick just below its lower right corner. To 'ping'
push the joystick twice to the right. The RAVEN board sends 4 echo
requests to the router, which answers by 4 echo replies.<br>
For more information about the LCD menu, please see \ref lcdraven.

\subsection running_browse Browsing the RAVEN board web server
In a Web browser, point to http://[aaaa::0011:22ff:fe33:4455].
Then click on 'Sensor Readings'. If no temperature is displayed it
means that you need to start the temperature update %process on the
RAVEN. To do so you must use the RAVEN's LCD menu and
joystick. Starting from the CONTIKI - 6LOWPAN display navigate to TEMP
and then to SEND. You can pick either ONCE or AUTO, but in any
case you always need to reload the webpage to see the latest temperature
reading. <br>
For more information about the LCD menu, please see \ref lcdraven.

<HR>
\section advanced Advanced use
\subsection advanced_externalboard Using an external board for power and Debug
To power the RAVEN boards externally and enable debug output
on RS232, you can use the stk500 board together with the raven.

Power:
\li Set the 'EXT/BAT' jumper on the RAVEN board to EXT
\li Attach pin 2 on the bottom strip to GND of your STK500
\li Attach pin 1 on the bottom strip to VTG of your STK500
\li Power the STK500

Debug Connection
\li Attach pin 4 of the leftmost I/O header to pin 'TXD' on your STK500
\li Connect the STK500's "RS232SPARE" port to a RS232 port on a PC
\li Connect a terminal program (e.g. hyper terminal on Windows,
minicom on Linux) to the RS232 port on the PC at 57600 Baud,
with parity 8N1, no flow control
\li The raven board will output debug messages to the terminal

\note To enable specific debugging messages, edit the source
file you are interested in (e.g. core/net/uip-nd6-io.c for
Neighbor Discovery messages debug) and set the macro DEBUG to 1.
Then recompile the code, load the new binary on the board and
restart the RAVEN.

The following image shows this connection, with the red and black
being VCC and GND. The green wire is debug out:

\image html raven_detail.jpg

\note The output to the RS232 converts will only be about
3V, but they are expecting a signal swinging up to VTG, or by
default 5V. You may have to set VTG to 3.3V and power the Raven
from another source, making sure the GNDs of both the STK500
and your external source are connected together.

\subsection advanced_details Understanding the setup
There is no widely available 802.15.4 and 6lowpan stack for PCs.
As a temporary solution and to be able to connect IPv6 hosts
such as RAVEN boards to IP networks, we implemented a "bridge"
function on the RZ USB Stick. The RZ USB stick bridges 802.15.4
packets to Ethernet (The Ethernet interface is emulated on the
USB port).

As Ethernet frames and addresses are very different
from 802.15.4 ones, a few adjustements are needed on addresses
and some neighbor discovery packets. As a consequence, 802.15.4
MAC addresses configured on both the RAVEN boards and the RZ USB
stick must have the format:<br>
\verbatim
x2:xx:xx:ff:fe:xx:xx:xx
\endverbatim
where x can take any hexadecimal value.
Read the section below to change the MAC address on one device.

\subsection advanced_eeprom Change a device MAC address

You can change the MAC address of a RAVEN board or the RZ USB 
Stick by setting the 8 first bytes of the EEPROM, following 
the convention above. You can do this three ways. 

The first is to set EEPROM bytes directly in an AVR Studio project, in
Debug mode

\li compile the binary file for RAVEN, as explained in \ref installation
\li Connect the JTAG pins of the JTAGICE into the JTAG connector of
the target processor.
\li IN AVR Studio, go to File->open, select the binary just created
\li The Debug mode should start
\li Click on View->memory
\li select EEPROM in the menu, then just type in the first 8 bytes
the target MAC address

The second is to reprogram the whole EEPROM individually from the 
Flash and Fuses.

\li Connect the JTAG pins of the JTAGICE into the JTAG connector of
the target processor.
\li In AVR Studio, click on "Tools"->"Program AVR"->"Auto Connect"
\li Go to the "Program" tab
\li In the "EEPROM" section, click on "Read" and save the EEPROM 
content in a file (in hex format)
\li Edit this file with a text editor, change the value of the 
first 8 bytes, save
\li In the "EEPROM" section, check the path to the "Input Hex file"
is the one to the file you just modified and click on "Program". 

The third is to modify the default value in the code:

\li Edit the file contiki-raven-main.c in the directory
platform\avr-raven. You will see the MAC address set in a line like:

\code
/* Put default MAC address in EEPROM */
uint8_t mac_address[8] EEMEM = {0x02, 0x11, 0x22, 0xff, 0xfe, 0x33, 0x44, 0x55};
\endcode

\li Change this value, recompile and reprogram the elf on the board.

\subsection advanced_fuses Setting the fuses manually

In case you need to reset the fuses on one AVR, do the following:
\li In AVR Studio, click on "Tools"->"Program AVR"->"Auto Connect"
\li Go to the "Fuses" tab
\li In the lower part of the window, set the EXTENDED,
HIGH, LOW fuses to the following values
\verbatim
0xFF, 0x99, 0xE2 for the ATmega1284P on the RAVEN board
0xFF, 0x99, 0xE2 for the ATmega3290P on the RAVEN board
0xFB, 0x99, 0xDE for the AT90USB1287 on the USB Stick
\endverbatim
\li In the same tab, Click on "Program"
\subsection advanced_capture Observing packets with Atmel Wireless Services or Wireshark
To view packets being sent over the air, you can use Atmel AVR
Wireless Services in Sniffer Mode, with the RZ USB Stick. You need
the software preinstalled on the RZ USB Stick to do this. Packets
are sent on channel 24. Links to detailed information about
AVR Wireless Services is provided with the RZ USB Stick.

See the \ref usbstick documentation for more details about using Wireshark.

\subsection adavanced_linux Programming Flash, Fuses, EEPROM from a Linux machine

One can use avrdude to load the binaries in Linux.

\subsection advanced_hc01 Using HC01 Header Compression Scheme
IETF Internet Draft draft-hui-6lowpan-hc-01 defines a stateful
header compression mechanism (called HC01) which will soon
deprecate the stateless header compression mechanism (called
HC1) defined in RFC4944. HC01 is much more powerfull and flexible,
in particular it allows compression of some multicast addresses
and of all global unicast addresses.

Contiki is compiled by default with HC1 support. To use HC01
instead, edit platform/xxx/contiki-conf.h (replace xxx with avr-raven,
then avr-ravenusb.)
and replace the line<BR>
\code
#define SICSLOWPAN_CONF_COMPRESSION SICSLOWPAN_CONF_COMPRESSION_HC1
\endcode
with
\code
#define SICSLOWPAN_CONF_COMPRESSION SICSLOWPAN_CONF_COMPRESSION_HC01
\endcode

Recompile and load Contiki for both the RAVEN ATmega1284P and RZ USB 
Stick.

If you capture packets being sent over the air (on the 802.15.4
network), you will see that much more packets are compressed than
when HC1 is used. Overall, packets sent are much smaller.

\subsection advanced_network Building a more complete network
You can integrate the RAVEN boards and RZ USB stick to a more
complete IPv6 network by connecting the PC which you plug the RZ
USB Stick in to any IPv6 network with correct routing configured.

This way, you will be able to reach the RAVEN boards (to read
sensor data for example) from anywhere within this IPv6 network,
or even any IPv4 network if v4 to v6 translation mechanisms are
used between both networks.

You can also have several RAVEN boards in your setup. If you do so,
be sure to configure different MAC addresses on each board.



<HR>
\subsection issues Known issues
<b>RZ USB Stick Link local address not created on Linux</b><br>

When plugging the RZ USB Stick in a Linux PC, it should
automatically configure a link local address
(fe80::0012:13ff:fe14:1516/64 with default MAC address). On some Linux
distributions, it seems to fail. To check this, in a terminal,
type
\verbatim
ifconfig
\endverbatim
If the interface usb0 does not have an IPv6 address starting
with fe80::, add it manually by typing:
\verbatim
ip -6 address add fe80::0012:13ff:fe14:1516/64 scope link dev usb0
\endverbatim

<b>make version issues</b><br>
You need to use the "make" executable from WinAVR. There 
are compilation issues with GNU make coming with Cygwin.

<HR>
\section annex Annex

\subsection annex_contikiDocs Annex - Additional Documentation

\li USB Stick Platform:     \ref usbstick
\li User interface on Raven:\ref lcdraven
\li Wireless libraries for Atmel Radio: \ref wireless
\li MAC for Atmel Radio:    \ref macdoc
\li IPv6 Implementation: \ref uip6 
\li 6lowpan Implementation: \ref sicslowpan

\subsection annex_hardware Annex - Atmel products detailed documentation
<b>RAVEN evaluation and starter kits</b><br>
\li ATAVRRZRAVEN evaluation kit:
http://www.atmel.com/dyn/products/tools_card.asp?tool_id=4291
\li AVR RAVEN board:
http://www.atmel.com/dyn/products/tools_card.asp?tool_id=4395
\li RZ USB Stick:
http://www.atmel.com/dyn/products/tools_card.asp?tool_id=4396

<b>RAVEN AVRs and Wireless transceivers</b><br>
\li ATmega 1284P MegaAVR:
http://www.atmel.com/dyn/products/product_card.asp?part_id=4331
\li ATmega 3290P LCD AVR:
http://www.atmel.com/dyn/products/product_card.asp?part_id=4059
\li AT90USB1287 USB AVR:
http://www.atmel.com/dyn/products/product_card.asp?part_id=3875
\li AT86RF230 802.15.4 Transceiver:
http://www.atmel.com/dyn/products/product_card.asp?part_id=3941

<b>Additional hardware</b><br>
\li ATSTK500 evaluation kit
http://www.atmel.com/dyn/products/tools_card.asp?tool_id=2735
\li ATEVK1100 evaluation kit
http://www.atmel.com/dyn/products/tools_card.asp?tool_id=4114
\li AVR JTAGICE mkII debugging platform
http://www.atmel.com/dyn/products/tools_card.asp?tool_id=3353

<b>Buying the hardware (part number ATAVRRZRAVEN and ATJTAGICE2)</b><br>
\li For the U.S. you can use http://www.atmel.com/contacts/distributor_check.asp
\li Digikey http://www.digikey.com/
\li Spoerle http://www.spoerle.com/en/products 
\li Lawicel http://www.lawicel-shop.se


\subsection annex_software Software setup details
<b>Contiki</b><br>
Download Contiki code from http://www.sics.se/contiki and
extract the source code. We assume the directory you extract 
to is c:/contiki.

<b>Cygwin</b><br>
\li Download Cygwin from http://www.cygwin.com
\li Launch the setup executable
\li Follow the instructions until you reach the Window "Cygwin 
Setup - Select Packages"
\li In this window, expand the "Devel" item and 

<b>AVR Studio</b><br>
Download and install AVR Studio from
http://www.atmel.com/dyn/products/tools_card.asp?tool_id=2725

<b>WinAVR</b><br>
WinAVR which contains a number of AVR tools
such as the avr-gcc compiler.

Download and install WinAVR latest version from
http://winavr.sourceforge.net/ 

<b>JTAGICE mkII Drivers</b><br>
Plug the JTAGICE mkII in a USB port of a windows PC. Follow the
indications to install the Windows drivers automatically.


*/
/** @} */
/** @} */