Changes between Version 28 and Version 29 of WARPLab/QuickStart


Ignore:
Timestamp:
Aug 22, 2013, 3:28:57 PM (11 years ago)
Author:
welsh
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • WARPLab/QuickStart

    v28 v29  
    33= Quick Start =
    44
    5 === System Requirements ===
     5== System Requirements ==
    66 * Review the [wiki:../Requirements WARPLab 7 System Requirements]
    77 * Review the [wiki:../../GettingStarted Getting Started Guide] for hardware basics
    8 
    9 === Setting up the WARPLab 7 Framework ===
     8[[br]]
     9== Setting up the WARPLab 7 Framework ==
    1010 1. Download the latest WARPLab Reference Design Release ([wiki:../Downloads Download]) and unzip it to a location of your choosing.
    1111 1. Open MATLAB and change the current path to the {{{M_Code_Reference}}} directory from the downloaded archive.
    1212 1. Run {{{wl_setup}}} on the MATLAB command line.
    1313 1. Follow the prompts to configure your WARPLab environment.
    14 
    15 === Hardware Setup ===
     14[[br]]
     15== Hardware Setup ==
    1616 * For your PC:
    1717  1. Assign one of your NICs to the manual IP address specified in the {{{wl_setup}}} step above (default 10.0.0.250)
    … …  
    2424   1. The bottom green LED will blink until the Ethernet link is up
    2525   1. All four green LEDs will blink when the node is ready to accept commands from MATLAB
    26 
    27 === Examples ===
     26[[br]]
     27== Examples ==
    2828 1. Confirm everything is ready by copying and pasting the following lines to the MATLAB command line:
    2929{{{
    … …  
    4646
    4747 2. If the previous stepped work, you should now try one of the [wiki:../Examples M-Code Examples].
    48 
     48[[br]]
    4949== Getting Help ==
    5050There are a few resources for getting help with using WARPLab for your own designs:
    … …  
    53531. The [wiki:../Reference/Utility#wl_cmd_doc wl_cmd_doc] is a function that will display documentation for a particular command.
    54541. The WARP forums ([http://warpproject.org/forums/]) are a great place to ask questions.
    55 
     55[[br]]
     56== Additional Tools ==
     57
     58=== WARPLab MEX UDP Transport (WARPLab 7.3.0 and later)===
     59
     60By default, WARPLab will use built-in java routines for performing network I/O.  However, this has some performance limitations as can be seen by our Read IQ / Write IQ [http://warpproject.org/trac/wiki/WARPLab/Benchmarks benchmarks].  Therefore, we have developed a custom WARPLab MEX UDP transport in order to provide a high performance transport for data transfer operations.  The WARPLab MEX UDP transport can provide dramatically faster performance while leaving the usage of WARPLab otherwise identical.
     61
     62To install the WARPLab MEX UDP Transport, please perform the following steps:
     63
     64NOTE: Make sure your repository is updated to the WARPLab 7.3.0 (or later) release.  The repository contains a compiled binary for Windows 7 64-bit.  For other platforms, compile the wl_mex_udp_transport mex function (see [wiki:/howto/MEX_Compile How-To Compile MEX] for more information).
     65
     66  1. Locate the WARPLab MEX UDP Transport source in one of the following locations:
     67    1. {{{<Your Installed WARP Repository Directory>\PlatformSupport\wl_mex_udp_transport}}}
     68    1. [source:/PlatformSupport/wl_mex_udp_transport /PlatformSupport/wl_mex_udp_transport]
     69    1. {{{svn co http://warpproject.org/svn/WARP/PlatformSupport/wl_mex_udp_transport}}}
     70  1. Add the wl_mex_udp_transport folder to your MATLAB path. The wl_mex_udp_transport folder should contain wl_mex_udp_transport.m and the wl_mex_udp_transport.mex binary (i.e. wl_mex_udp_transport.mexw64)
     71{{{
     72addpath('<wl_mex_udp_transport folder>');
     73}}}
     74  1. Verify wl_mex_udp_transport is recognized by running {{{wl_mex_udp_transport('version');}}} on the MATLAB command line. The output should print the version number.  For example:
     75{{{
     76>> wl_mex_udp_transport('version');
     77Loaded wl_mex_udp_transport version 1.0.0a
     78WARPLab MEX UDP Transport v1.0.0a (compiled Aug 21 2013 09:46:30)
     79Copyright 2013, Mango Communications. All rights reserved.
     80Distributed under the WARP license:  http://warpproject.org/license 
     81}}}
     82  1. Re-run the [wiki:../Reference/Utility#wl_setup 'wl_setup'] function in {{{M_Code_Reference}}}. One prompt will be to select which type of transport you want to use. If you have added a compatible, compiled wl_mex_udp_transport to your path, the script will list it as an option you can select. 
     83
     84NOTE: simply re-running 'wl_setup' and selecting java is sufficient for switching back to the built-in java routines. You do not need to explicitly remove wl_mex_udp_transport from your MATLAB path.
     85
     86[[br]]
    5687== Tips ==
     88
    5789=== MATLAB Object Oriented Syntax ===
    5890Throughout the WARPLab MATLAB code, you will see a mix of equivalent ways of calling methods to various objects. Suppose you have an object {{{obj}}} in your workspace and that object has a method {{{method}}}. You can call this method in two completely equivalent ways:
    … …  
    69101
    70102As a more concrete example, consider the quick start step above that called the command {{{wl_nodeCmd(nodes,'identify');}}}. An equivalent way of issuing this command to the nodes in the network is {{{nodes.wl_nodeCmd('identify');}}}
    71 
    72 
     103----
    73104=== Jumbo Frames ===
    74105The WARP hardware design supports Ethernet packets up to 9000 bytes. Any Ethernet packet larger than 1500 bytes is considered a "jumbo frame" and support for these jumbo frames among consumer NICs and switches is limited. To see if your hardware supports jumbo frames, increase the MTU setting on your computer to the maximum allowed setting. Then, two tests can determine the maximum usable payload: (a) a ping test, and (b) a WARPLab test.
    75 
     106----
    76107==== Ping Test ====
    77108Once the MTU on your machine is raised to its maximum, you can use pings from your computer to determine whether your switch and NIC can actually send and receive jumbo frames. Make sure you have a board configured with the WARPLab bitstream and a DIP switch of '0' (making its IP address 10.0.0.1).
    … …  
    1261578008 bytes from 10.0.0.1: icmp_seq=1 ttl=32 time=3.071 ms
    127158}}}
    128 
     159----
    129160==== WARPLab Test ====
    130161If the ping test indicates that your PC and your Ethernet switch support jumbo frames, the next step is to see if WARPLab works with jumbo frames. When node objects are first set up in a WARPLab script, they run a test with their associated boards to see what maximum payload size can be supported. First, re-run the [wiki:../Reference/Utility#wl_setup 'wl_setup'] function in {{{M_Code_Reference}}} and select that you would like to enable jumbo frame support. Next, ensure one WARP board is programmed with the WARPLab bitstream and configured with DIP switch '0'. Then, copy and paste the following lines to the MATLAB command line:
    … …  
    138169This will display the payload size the WARPLab has configured itself to use. For one of our PCs, this value returns as {{{8960}}}, showing the jumbo frame support is correctly working.
    139170
    140 ==== Known Hardware Compatibility ====
     171[[br]]
     172== Hardware Compatibility ==
     173
    141174It is impossible to form a definitive list of hardware that is compatible with jumbo frame support, but we will maintain a list of observed setups and their compatibility. If you try jumbo frames and have a hardware setup that does or does not work with them, please post to [http://warpproject.org/forums/ the WARP forums] so we can add them to the list.
    142175
    … …  
    155188 * Apple 2010 Macbook Pro, OSX 10.8.3, Broadcom 5764-B0
    156189
    157 
    158 
    159 
     190[[br]]
     191== Other Information ==
    160192
    161193=== pnet Toolbox ===
     194
     195'''NOTE:  The PNET toolbox will not be supported in WARPLab 7.4.0 or later.'''
     196
    162197By default, WARPLab will use built-in java routines for performing network I/O. pnet, a custom UDP mex toolbox for matlab, is also supported, but the latest version is required. pnet can offer modestly higher performance than the built-in java routines, but the usage of WARPLab is otherwise identical. Note: these performance gains are negligible for jumbo frame packets near 9000 bytes on length. If you want to use pnet, please perform the following steps:
    163198 1. Install the updated pnet IP/UDP toolbox for MATLAB