Running Contiki with uIPv6 and SICSlowpan support on Atmel RAVEN hardware
[Tutorials]

This tutorial explains how to run Contiki with IPv6 and 6lowpan support on Atmel RAVEN hardware. More...

This tutorial explains how to run Contiki with IPv6 and 6lowpan support on Atmel RAVEN hardware.

Table of contents

Introduction
Hardware requirements
Software requirements
Demo Overview
Compiling, installing, configuring
Running the basic demo
Advanced use
Known issues
Annex

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.

Hardware requirements

To run the demo, you will need at least

Note:
Links to detailed hardware documentation are in Annex - Atmel products detailed documentation

Software requirements

To install the demo you need:

Instructions to install these tools are in the section Software setup details.

To run the demo, you need:

Note:
On windows XP, if ipv6 support is not enabled, enable it by typing in a shell: 
ipv6 install

Demo Overview

Network Architecture

The network comprises:

In the basic demo, you can:

tutorial-raven-basic.jpg

Compiling, installing, configuring

Compiling the binaries for RAVEN and RZ USB stick

The binaries needed are:

To compile each of them, type in Cygwin: 

cd c:/contiki/examples/webserver-ipv6-raven
make

cd c:/contiki/platform/avr-ravenlcd
make

cd c:/contiki/examples/ravenusbstick
make

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 Using an external board for power and Debug.

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.

Programming the boards

What you need to do

Hardware connections

tutorial-raven-jtag.jpg
tutorial-raven-connections.jpg

To load the binary on each AVR in Windows

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

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

Running the basic demo

Setting up the router

On Linux
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 

ifconfig

and checking the addresses of interface usb0

If it does not, add it manually: 

ip -6 address add fe80::0012:13ff:fe14:1516/64 scope link dev usb0

Configure the IP addresses on usb0 

ip -6 address add aaaa::1/64 dev usb0

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) 

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; 
    };
};
Note:
This values have been carefuly chosen to work on platform using a 16bit clock.

Restart the radvd daemon. Example command: 

/etc/init.d/radvd restart

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

echo 1 > /proc/sys/net/ipv6/conf/all/forwarding

On Windows

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 

ipv6 if

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

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

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

To do so, type: 

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

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.

Pinging the RAVEN board from the router

On Windows (Cygwin shell) or Linux, type 

ping6 -n 5 aaaa::11:22ff:fe33:4455

or 

ping6 -s aaaa::1 aaaa::11:22ff:fe33:4455

The router is sending 5 echo requests to the RAVEN board. The RAVEN board answers with 5 echo replies.

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.
For more information about the LCD menu, please see RZRAVEN LCD 3290p.

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.
For more information about the LCD menu, please see RZRAVEN LCD 3290p.

Advanced use

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:

Debug Connection

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:

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.

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:

x2:xx:xx:ff:fe:xx:xx:xx

where x can take any hexadecimal value. Read the section below to change the MAC address on one device.

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

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

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

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

Setting the fuses manually

In case you need to reset the fuses on one AVR, do the following:

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 RZRAVEN USB Stick (Jackdaw) documentation for more details about using Wireshark.

Programming Flash, Fuses, EEPROM from a Linux machine

One can use avrdude to load the binaries in Linux.

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

#define SICSLOWPAN_CONF_COMPRESSION SICSLOWPAN_CONF_COMPRESSION_HC1

with 

#define SICSLOWPAN_CONF_COMPRESSION SICSLOWPAN_CONF_COMPRESSION_HC01

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.

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.

Known issues

RZ USB Stick Link local address not created on Linux

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 

ifconfig

If the interface usb0 does not have an IPv6 address starting with fe80::, add it manually by typing: 

ip -6 address add fe80::0012:13ff:fe14:1516/64 scope link dev usb0

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

Annex

Annex - Additional Documentation

Annex - Atmel products detailed documentation

RAVEN evaluation and starter kits

RAVEN AVRs and Wireless transceivers

Additional hardware

Buying the hardware (part number ATAVRRZRAVEN and ATJTAGICE2)

Software setup details

Contiki
Download Contiki code from http://www.sics.se/contiki and extract the source code. We assume the directory you extract to is c:/contiki.

Cygwin

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

WinAVR
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/

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

Generated on Mon Apr 11 14:23:56 2011 for Contiki 2.5 by  doxygen 1.6.1