Installing and using TestDrive-Panda |
Loading a USB Networking protocol
Setting up a USB networking protocol to be automatically loaded at boot time.
Belcarra supports a testing environment for testing Networking over USB protocols. This paper explains the Testdrive PandaBoard distribution (available here), how to install it and how to use it. .
Introduction
Testdrive Panda is a version of the the Precise Ubuntu distribution modified in small ways to facilitate testing with the following standard networking over USB protocols
- CDC ECM (Ethernet Control Model)
- CDC EEM (Ethernet Emulation Model, a simplified version of ECM especially suitable for smart devices which are not connected to an external network)
- CDC NCM (Network Control Model, a modernized version of ECM)
- Microsoft RNDIS
- CDC ECM subset (used by certain deficient USB systems). The OMAP USB system is fully capable but this option forces the use of the subset.
Requirements
- An SD card 4GB or 8GB (16GB might work but has not been tested)
- A release file for Testdrive-Panda which will have a name like testdrive-panda-yyyy-mm-dd-hh-mm.tgz
- The most recent version of the script write-testdrive-panda.sh
Preliminary activities
These instructions will work on an Ubuntu desktop system
- Insert your SD card into your card reader. This should cause the creation of one or more new devices in /dev/sdxy. The value of x in /dev/sdxy is your drive letter. You can perform the following command
ls /dev/sd*
before and after inserting the card
- Once the drive letter has been determined change your working directory to the location of the Testdrive archive (about 800MB in size)
- Make sure the current user is root or in the sudo group
- Make sure the write-testdrive-panda.sh script is in the current $PATH
- Make your SSH public key available in a file (optional)
- Issue the following commands. Note that the exact archive name will vary
#Capture the archive name to the shell variable ARCHIVE
ARCHIVE=testdrive-panda-yyyy-mm-dd-hh-mm.tgz
LETTER=c # Typical value Your actual drive letter will vary
write-testdrive-panda.sh -a authfile $LETTER $ARCHIVE hostname
Please note that this process takes some time -- up to 20 minutes depending on hardware used, and when it is finished a message is printed on the screen saying that it is safe to remove the card. Removing the card before that will have unpredictable, likely disastrous consequences. Fortunately, you can repair the card simply by re-running the script -- but this time waiting for the very end.
The installation process does the following
- erases all previous contents of the SD card
- partitions the SD card with a small FAT32 partition at the beginning and a ext4 partition for the remainder of the card
- installs the contents of the testdrive distribution on the card
- if the optional hostname is specified, that name is inserted in /etc/hosts and /etc/hostname, replacing the default hostname of precise1.
- If the optional authfile is specified, that file is installed as authorized_keys2 for the users root and testdrive. Therefore these users of the Panda can be accessed by ssh without using a password.
Features
After doing all this, you will have a command line “server” version of Ubuntu for the Pandaboard.
It is modified in the following small ways
- An updated kernel
- Kernel configured to use ECM/EEM instead of RNDIS
- NCM available
- The iperf utility is installed
- Test files for web testing are available in /var/www
- The avahi mDNS daemon is installed (see remote access using mDNS below).
Logging in
The user testdrive has no password and is enabled to do anything via the sudo command.
Note the first login prompt is sometimes overwritten (hidden) by various system messages. Just press Enter to get another. This version of Ubuntu uses serial and and Ethernet access methods only. This is a “server” edition (no support for a monitor, mouse, keyboard, etc).
Remote access using mDNS
The Avahi mDNS daemon advertises a host called hostname.local where hostname is the name that is specified at installation time (see above). This can changed by modifying the following two files:
- /etc/hosts
- /etc/hostname
However, the easiest way to set the mDNS name is to use the hostname option (3rd argument of write-testdrive-panda.sh) during installation
If the hostname installation option is not used, then the mDNS name will be precise1.local.
After a unique name is selected, the next thing is to specify the SSH authorized_keys2 file. With these two items used in tandem, the Pandaboard can be accessed without a password over the Ethernet port, and also without knowing its IP address as follows:
ssh -l root precise1.local # Using the default name
Loading a USB Networking protocol
Five networking over USB protocols are supported
- The script ecm supports CDC ECM
- The script eem supports CDC EEM
- The script ncm supports CDC NCM
- The script rndis supports MIcrosoft’s Remote NDIS (RNDIS) protocol
- The script subset supports the de facto unofficial subset of CDC ECM used for certain USB hardware subsystems which lack necessary features to fully support CDC ECM. Even though the Pandaboard’s USB subsystem is fully capable of supporting CDC ECM, this simulates other hardware which has this limitation.
Gathering information
The first step is to determine the protocol. The protocol can be one of the following coded values
- ecm
- eem
- ncm
- rndis
- subset
Next, determine the VendorID in hex digits (no 0x prefix). For Belcarra, this will be 15ec .
Next, determine the Product ID in hex digits. A typical value for a Belcarra demo driver is d031
Finally (optionally) determine a serial number, which is just a series of decimal digits.
At the conclusion of this process, 4 values have been set:
PROTOCOL
VENDOR
PRODUCT
SERIAL
The last value, SERIAL might be the empty string, in which case no SerialNumber string will be included in the Configuration Descriptor.
Setting up a USB network link
Using the four values gathered in the previous section, simply issue a command as follows:
$PROTOCOL $VENDOR $PRODUCT $SERIAL
Examples
ecm 15ec d031 # ECM protocol for 15ec/d031 no serial number
eem 15ec d035 1000 # EEM protocol for 15ec/d035 serial # 1000
ncm 15ec d031 # NCM protocol for 15ec/d031 no serial number
rndis 15ec d037 1001 # RNDIS protocol for 15ec/d037 serial number 1001
subset 15ec d031 2000 # ECM subset for 15ec/d031 serial number 2000
In each case, if a network protocol is already loaded, its module is first unloaded before loading the new network module with parameters as requested.
Module parameters
These parameters are all specified automatically, but are noted here for completeness
Parameter | module(s) | value(s) | default | description |
use_eem | g_ether | 0/1 | 0 | 0 for ECM, 1 for EEM |
idVendor | g_ether/g_ncm | 16-bit hex | 0 (not a reasonable value) | Vendor ID, up to 4 hex digits |
idProduct | g_ether/g_ncm | 16-bit hex | 0 (not a reasonable value) | Product ID, up to 4 hex digits |
iSerialNumber | g_ether/g_ncm | String of decimal digits | empty string (no serial number) | Serial Number |
force_ecm_subset | g_ether | 0/1 | 0 (do not use the subset) | 1 to use the ECM subset |
use_rndis | g_ether | 0/1 | 0 | 1 to use RNDIS |
Setting up a USB networking protocol to be automatically loaded at boot time.
To enable USB networking to automatically load at boot time, simply write the four values above to the file /etc/usb/usb-network.conf
Example of contents of this file
PROTOCOL=ncm
VENDOR=15ec
PRODUCT=d031
SERIAL=1000
Similarly, to prevent automatic loading at boot time, set PROTOCOL to an invalid value, rename the file, or put #’s at the beginning of each line (these lines are read into part of the boot scripts).
Guide to network testing
Three types of network testing are suggested:
Flood ping
The flood ping is a good tool to stress-test a network link for stability and endurance
The iperf utility
The iperf utility is very useful for establishing complex measurements of a link. For instance a web test (see next section) can establish the effective speed of a web transfer, but we do not know how much TCP/IP traffic was really sent in each direction. iperf can be used to get profiles of traffic shapes. In addition, iperf tests can be run over a long period of time, up to a few hours, limited by the stability of the Windows version of iperf.
Web tests
The Apache2 web server is started
Shutdown
Once all tests have been run, the system can be shut down via sudo
sudo shutdown -y -g0
You can also reboot the board as follows
sudo reboot
Additional Documentation
- Belcarra USB TestDrive - an overview of Belcarra’s Overo USB Test Environment, a Linux based test system based on the Gumstix Overo board.
- USB TestDrive Setup - an overview of USB Device testing using Belcarra’s Overo USB Test Environment.
- Windows USB TestDrive Setup - an overview of setting up a Microsoft Windows system (10, 8.1, 7) to do testing of USB devices with tools such as Apache and Cygwin.
- USBLAN 2.4 OEM Manual - Link to download a .pdf with technical details of architecture, configuration, customization and debug scenarios for USBLAN release 2.4.
Related Sites
- Belcarra Technologies - design, implementation and support of high performance USB networking solutions
- Belcarra Composite Device Framework - USB client driver and management system
- Belcarra USBLAN - USB Class driver for Microsoft Windows
Copyright ©2005-2013 Belcarra Technologies (2005) Corp.
www.belcarra.com info@belcarra.com
Document Created: June 2013