doc/ravenusbstick-docs.txt

   1 /**
   2
   3 \ingroup platform
   4 \defgroup usbstick RZRAVEN USB Stick (Jackdaw)
   5
   6 \image html ravenusb_medium.jpg
   7
   8 \section introduction Introduction
   9
  10 This document explains the Raven USB Stick when operated on an IPv6 network. The
  11 USB Stick allows the computer, and outside networks, to communicate with low-cost
  12 embedded nodes. The "RZUSBSTICK" hardware, when loaded with the Contiki "ravenusbstick"
  13 example, forms the complete device described here. This combination of hardware and
  14 firmware is henceforth referred to as the "Jackdaw".
  15
  16 \section capabilities Capabilities
  17
  18 The Jackdaw supports multiple operating systems, customizing itself to OSes as
  19 needed. The overall idea for a network interface is to emulate an ethernet interface.
  20 Data is passed to the Jackdaw as if it was an ethernet port, however the Jackdaw
  21 passes this data over the air to end nodes.
  22
  23 The Jackdaw can function as an 802.15.4 sniffer, and can sniff the raw 802.15.4 frame
  24 at the same time it is providing network functionality.
  25
  26 In addition to the network interface, the Jackdaw can enumerate a USB serial port
  27 at the same time. This serial port can be used to pass debug messages, or to change
  28 operating parameters as needed. Note that WindowsXP SP2 or lower does not support this,
  29 the serial port will only be enumerated on Linux or WindowsXP SP3. Windows Vista should
  30 work with minor modification to the INF files.
  31
  32 Finally the Jackdaw has the ability to show up as a USB mass storage drive. This is used
  33 to load drivers onto a PC without needing any other hardware, such as a driver disk. The
  34 amount of storage is very limited at around 59 Kbyte, sufficent for a few driver files.
  35
  36 \section pluging Plugging It In
  37
  38 When plugging the Jackdaw in, several things occur in sequence:
  39
  40   - Attempt to appear as a network interface with a serial port. If this fails (drivers don't load),
  41     it then unmounts itself and waits a few seconds.
  42   - Attempt to appear as just a network interface. If this fails as well, it again unmounts itself.
  43   - Finally mounts as a mass storage device
  44
  45 If the device has never before been plugged in, you will end up with an unformatted USB mass storage device.
  46 You can format this as you would a normal drive - on Windows right click and select "format". If the device
  47 has previously been formatted, or was programmed from a preformatted flash image, you will end up with a new drive
  48 which contains the drivers needed to have the device work on Windows.
  49
  50 \subsection loaddrivers Loading Drivers
  51
  52 Windows should prompt you for drivers for the device. Simply point it to location "C:\contikisrc\cpu\avr\dev\usb\INF" Where
  53 the directory "c:\contikisrc" is where the Contiki source code is on your computer.
  54
  55 If you have a Jackdaw with a formatted mass storage section, with the drivers on it, you can simply wait until that drive shows
  56 up. Then point the Windows "new hardware found" Wizard to this new drive, which should have three .INF files in it.
  57
  58 \section setup Setting Up
  59
  60 \subsection Linux
  61
  62 The Jackdaw has excellent support in Linux. The first thing to check is that it was detected. Plug it in, and check the output of 'dmesg'.
  63 You should see something like:
  64
  65 \verbatim
  66 usb 5-2: new full speed USB device using uhci_hcd and address 29
  67 usb 5-2: configuration #1 chosen from 1 choice
  68 rndis_host 5-2:1.0: dev can't take 1338 byte packets (max 1338), adjusting MTU to 1280
  69 usb0: register 'rndis_host' at usb-0000:00:1d.3-2, RNDIS device, 02:12:13:14:15:16
  70 cdc_acm 5-2:1.2: ttyACM0: USB ACM device
  71 usb 5-2: New USB device found, idVendor=03eb, idProduct=2021
  72 usb 5-2: New USB device strings: Mfr=1, Product=2, SerialNumber=3
  73 usb 5-2: Product: RZRAVEN USB DEMO
  74 usb 5-2: Manufacturer: Atmel
  75 usb 5-2: SerialNumber: 1.0.0
  76 \endverbatim
  77
  78 You can then check that it was assigned a link-local address. Run 'ifconfig' and observe the output, looking for the line about usb0:
  79
  80 \verbatim
  81 usb0      Link encap:Ethernet  HWaddr 02:12:13:14:15:16
  82           inet6 addr: fe80::12:13ff:fe14:1516/64 Scope:Link
  83           UP BROADCAST RUNNING MULTICAST  MTU:1280  Metric:1
  84           RX packets:131 errors:131 dropped:0 overruns:0 frame:131
  85           TX packets:169 errors:0 dropped:0 overruns:0 carrier:0
  86           collisions:0 txqueuelen:1000
  87           RX bytes:30429 (29.7 KiB)  TX bytes:28290 (27.6 KiB)
  88 \endverbatim
  89
  90 The address that starts with "fe80" is the link-local address. If this wasn't automatically assigned, you can assign one as such:
  91
  92 \verbatim
  93 ip -6 address add fe80::12:13ff:fe14:1516/64 scope link dev usb0
  94 \endverbatim
  95
  96 If you wish to see how to generate router advertisements in Linux see the \ref tutorialraven .
  97
  98 You will also notice the line mentioning ttyACM0, that is the 'debug' interface. You can connect any terminal emulator to it such
  99 as gtkterm. Simply set the port to "dev/ttyACM0". See the \ref DebugPort section for more information.
 100
 101 \subsection Windows XP
 102
 103 Once the drivers are installed, you should see the device show up in "Network Connections". You should see something like this:
 104
 105 \image html ravenusb_network_connections.png
 106
 107 Right-click on this, and hit "Properties".
 108
 109 Click the "Install" button. Select "Protocol" as the type of network component, and hit "Add". The manufacture is "Microsoft" and the network protocol
 110 is "TCP/IP version 6". Hit OK.
 111
 112 Then in the window "This connection uses the following items:", uncheck everything EXCEPT "Microsoft TCP/IP version 6". Hit OK and get out
 113 of that dialog. We can no longer do anything graphically, as WindowsXP doesn't have support for IPv6 through anything but
 114 the command-line interface.
 115
 116 If you wish to see how to configure Windows to generate router advertisements, see the \ref tutorialraven.
 117
 118 You may additionally see a debug port enumerate. This will show up as a serial port, which can be checked by going to the Device Manager and seeing if an "Atmel Raven USB Debug Port" shows up under "Ports (COM & LPT)". If so, you can connect a terminal emulator such to this port. A simple one that is recommended is "Br@y++ Terminal".
 119
 120 \section DebugPort Debug Port Useage
 121
 122 The Jackdaw enumerates a CDC serial port. This is typically used by USB<-->Serial converters, however in this case it simply emulates a serial port. Since there is no physical serial port, the setting of the baud rate does not matter.
 123
 124 The Jackdaw sends both a LF and CR after every line, so you should disable any terminal emulator options that add extra CR's.
 125
 126 With the port connected, strike the 'h' key to bring up the main menu. It should look something like this:
 127
 128 \verbatim
 129 ********** Jackdaw Menu ******************
 130 *                                        *
 131 * Main Menu:                             *
 132 *  h,?             Print this menu       *
 133 *  m               Print current mode    *
 134 *  s               Set to sniffer mode   *
 135 *  n               Set to network mode   *
 136 *  6               Toggle 6lowpan        *
 137 *  r               Toggle raw mode       *
 138 *  u               Switch to mass-storage*
 139 *                                        *
 140 * Make selection at any time by pressing *
 141 * your choice on keyboard.               *
 142 ******************************************
 143 \endverbatim
 144
 145 <b>Network mode</b><br>
 146 Network mode is the default mode. In this mode addresses inside IP packets will be adjusted to reflect the network they
 147 are on. For instance inside a Router Advertisement message, the link-layer address on the ethernet side will be 6 bytes.
 148 On the 802.15.4 side it will be 8 bytes. This allows both systems to accept this IP packet as valid.
 149
 150 <b>Sniffer mode</b><br>
 151 In sniffer mode, the IP packets themselves are left unchanged. This means that you won't be able to form a network, as
 152 the computer's IP stack will not understand why the link-layer addresses are 8 bytes. It is only expecting 6 bytes, as
 153 it is assuming an ethernet layer.
 154
 155 <b>6lowpan enabled/disabled</b><br>
 156 Enabling or Disabling 6lowpan changes if the USBStick will decode 6lowpan messages into valid IPv6 messages and send
 157 them over the ethernet interface. Enabled by default.
 158
 159 <b>raw mode enabled/disabled</b><br>
 160 If raw mode is enabled, every 802.15.4 frame that comes in will be sent to the computer raw. It will be sent as an
 161 ethernet frame, with the ETHTYPE set to 0x809A. Note this is not an IEEE standard, so to use this device as a
 162 802.15.4 sniffer needs some extra work, described in the \ref Wireshark section. Also for every 802.15.4 packet
 163 that is sent out over the RF port is sent out over ethernet as well.
 164
 165 <b>Mass Storage</b><br>
 166 This will switch the device to \ref MassStorageMode
 167
 168 \section Wireshark Using Wireshark
 169
 170 When using the Jackdow with 6lowpan, you can
 171 simply operate Wireshark as normal. Select the interface as the USB Stick, on Linux this will likely be "usb0", and on Windows
 172 it will just call the interface "Atmel". You will see pure IPv6 packets, with traffic such as ICMPv6, TCP, or UDP.
 173
 174 If you have raw mode enabled (it is by default), you will also see 802.15.4 information. You may see many 802.15.4 packets
 175 for one IP packet due to fragmentation. You can also put either 'ipv6' or 'wpan' in the filter box at the top of Wireshark
 176 to filter out everything but IPv6 or 802.15.4 traffic. Also, for received frames the 802.15.4 data will come BEFORE the IPv6
 177 packet. For transmitted frames, the 802.15.4 data will come AFTER the IPv6 packet. You can see that in the following, where
 178 messages from the same source are boxed:
 179
 180 \image html wireshark_explained.png
 181
 182 Note that Wireshark does have support for 802.15.4, but you need version 1.1.2 or later. See \ref annex_wireshark for download instructions.
 183
 184 \note 802.15.4 packets transmitted from the Jackdaw will come up as having "Bad FCS". This is because the FCS is added automatically by the
 185 radio chip, and is not known to the microcontroller on the Jackdaw. Hence some padding bytes are added to allow you to see where the FCS would go.
 186 The 802.15.4 packet was generated from the IPv6 packet directly. The only way to actually sniff the real over the air data is to use a second Jackdaw
 187 as just a sniffer.
 188
 189 Also be sure to use the features of wireshark to make life easier! You can colorize packets based on various things, including
 190 destination and source addresses. The following example colourizes packets destined for different addresses differently, quickly
 191 letting you see message flow. You could furthur colorize based on the message type, to allow you to see 802.15.4 packets and
 192 IPv6 packets in different colors. The following example has the 'source_eth' and 'dest_eth' rules at the top of the order, you
 193 may want to put them lower so you still see other colourizations such as bad TCP, checksum errors, etc.
 194
 195 \image html wireshark_color.png
 196
 197 \section MassStorageMode Mass Storage Mode
 198
 199 The mass storage mode provides a small amount of storage by using part of the internal flash of the AVR. This will get
 200 erased every time the AVR is reprogrammed.
 201
 202 The Jackdaw can end in mass storage mode in three ways. It can fail all other modes and end up there, it can be forced
 203 there through the debug port, or it can be forced there through a hardware switch. see the \ref hardwareforce section.
 204
 205 Once in mass storage mode, you will have to format the device. This can be done by right-clicking on it and hitting
 206 format, or if you attempt to open the drive Windows will ask you to format it. Once it is formatted you can store a few INF
 207 files on it! If you read the FLASH back from the AVR, you now have an image with a preformatted drive with those INF files
 208 on it already!
 209
 210 \section hardwareforce Forcing Jackdaw to certain Modes
 211
 212 The Jackdaw has several operating modes, and very limited inputs to switch between them. Hence it auto-switches to what
 213 it feels is the most useful mode, but it's not always right. Hence an override is provided to allow you to use it in other
 214 modes.
 215
 216 This override is to short two pads on the back of the Jackdaw. Note that only a somewhat conductive short is needed, a moist finger should be plenty of conductivity. The pads to short are visible below the"A" in the "ATMEL" logo. There will be three pads - only short the two closest to the "ATMEL" logo. Or as below:
 217
 218 \image html ravenusb_shortpins.jpg
 219
 220 Short them when plugging in the Jackdaw, and it enters "reverse logic mode". If it doesn't, you either might have
 221 not enough conductivity, or you might be shorting to the third pad too much.
 222
 223 In "reverse logic mode" it will stay in the main mode (Network interface + Serial debug port) if it doesn't see the
 224 driver loading on the host computer. This mode is needed for Windows Vista, where you have to keep the hardware plugged in while
 225 installing drivers.
 226
 227 If the driver DOES load OK, it will remount itself as a mass storage device. The idea is that you can hold the Jackdaw a specific
 228 way when plugging in and it will mount as mass storage. Note that it will FIRST mount as a network interface for a few seconds
 229 before switching.
 230
 231 One problem with this is Windows XP SP2: it will never exit the first (network + debug) mode, and you don't have a debug
 232 port to switch to mass storage mode. You can either upgrade to SP3, or uncomment this line in platforms\ravenusbstick\contiki-raven-default-init-lowlevel.c:
 233
 234 \code
 235 #define WINXPSP2
 236 \endcode
 237
 238 \section Address Translation
 239
 240 Addresses on the 802.15.4 network are 8 bytes long, and addresses on an ethernet network are 6 bytes long. This provides some problems for
 241 bridging the two networks. This should be done by routing the IP packets between the ethernet and 802.15.4 network, but the current
 242 code does not have support for routing.
 243
 244 As a temporary solution, addresses are "translated" when passing through the Jackdaw. This generates valid ethernet addresses from the
 245 802.15.4 addresses, and valid 802.15.4 addresses from ethernet addresses. Note this also includes translating addresses which are
 246 inside IP packets. Certain messages, such as various neighbor discovery messages, include a link-layer address. An IP stack which
 247 is expecting an ethernet-sized address will get confused by the different size, and vis-versa.
 248
 249 Details of the translation can be found in the \ref sicslowinterop documentation. It is important to remember this is a temporary solution
 250 until proper routing is implemented.
 251
 252 \section Annex
 253
 254 \subsection annex_wireshark Wireshark download
 255
 256 \li Check the latest stable release at http://www.wireshark.org/ - it may already be revision 1.1.2 or later.
 257 \li You can apply a patch to Wireshark sources earlier than 1.1.2 and rebuild it yourself, see https://bugs.wireshark.org/bugzilla/show_bug.cgi?id=2938
 258 \li You can download the latest sources or prebuild binary from http://www.wireshark.org/download/automated/ - be sure to get SVN revision 26352 or later. For win32 there are three types of binaries, the "normal" installer will have a name like "wireshark-win32-1.1.2-SVN-26354.exe".
 259 \li You can download a prebuilt version of Wireshark 1.0.3 at http://www.newae.com/download/wireshark-setup-1.0.3-jackdaw.exe
 260
 261
 262 \note
 263 For some reason the author list is crazy, i'm not sure how to stop this! It should follow this text...
 264
 265 */