Belcarra Technologies (2005)  Corp.

BeagleBone USB TestDrive Guide


Beaglebone USB TestDrive Guide

Belcarra has created Beagle TestDrive, an edition of Belcarra’s USB Testdrive for the BeagleBone Black to allow rapid prototyping of networking over USB protocols.   Testdrive uses the Beaglebone as a proxy for an OEM device on the device side of the USB link.  Matching demo editions of Belcarra USBLAN for Windows are automatically installed from Windows Update as necessary.

The Beaglebone Black (summarized by beagleboard.org:)

... are low-cost, fan-less single-board computers based on low-power Texas Instruments processors featuring the ARM Cortex-A series core with all of the expandability of today's desktop machines, but without the bulk, expense, or noise.

Beagle TestDrive is provided as a MicroSD SDHC image. The Beaglebone Black can boot TestDrive without modifying the onboard firmware.

Features of Beagle Testdrive

External information

Parts list

Supplementary Tools

The following supplementary tools are needed to write an SD image under Windows.

The following tool is useful to find the Testdrive device over an Ethernet segment from a control PC, which may be a different PC from the test PC

For run-time testing, the following tool is recommended (but not essential since other standard tools  are supported by Testdrive):

Running the Beagleboard

Built-in firmware and SD firmware

The Beagleboard by default boots Debian from the built-in (on board) firmware. The SD slot can be used to boot an alternate environment, such as TestDrive.

The Testdrive SD image is a modified version of Debian as follows:

Setting up the SD

Note: this is not the only way to download, unpack, and program the SD image. Standard  tools in Linux or Cygwin work as well. Users familiar with those environments may prefer to use those methods.

Establishing a control connection to Testdrive

Access to the TestDrive command line uses the secure shell (SSH) from a control PC, which may be the host (test) PC or a different machine running any popular OS. A second machine is recommended since it gives an independent view of what the TestDrive Beaglebone is doing.

If the control PC is running Windows, an SSH client such as PUTTY will be needed.

Assume that a DHCP service is available on the Ethernet segment.  Assume for illustration purposes that the server assigns DHCP addresses beginning at 192.168.0.100 (a common arrangement). In any case there will be a starting address and the server will assign addresses starting there.  The TestDrive ssh server also listens on IPv6 (see example below).

The next step is to ssh to likely addresses of  the board as assigned by DHCP.  If MDNS service  is available, then the Testdrive Beagleboard is accessible via the symbolic name beagletestdrive.local:

ssh debian@beagletestdrive.local

For Windows, MDNS, is available in Windows if Apple’s Bonjour is installed (see above). Here’s an example of Bonjour-facilitated access under Windows.

$ ssh debian@beagletestdrive.local

The authenticity of host 'beagletestdrive.local (fe80::564a:16ff:fef0:a1b6%17)' can't be established.

ECDSA key fingerprint is 64:8b:4f:73:0d:de:ff:a8:48:aa:d9:5c:c4:2f:d4:be.

Are you sure you want to continue connecting (yes/no)? yes

Warning: Permanently added 'beagletestdrive.local,fe80::564a:16ff:fef0:a1b6%17' (ECDSA) to the list of known hosts.

Debian GNU/Linux 7 \n \l

BeagleBoard.org Debian Image 2016-07-04

Enhanced to have multiple USB network protocols: see /home/debian/bin

Support/FAQ: http://elinux.org/Beagleboard:BeagleBoneBlack_Debian

default username:password is [debian:Testdrive]

debian@beagletestdrive.local's password:enter Testdrive as the password here

Last login: Tue Jul 19 20:40:43 2016 from 192.168.0.102

If BonJour/MDNS is not available, it becomes necessary to hunt for the Beagleboard. Two main methods are available

  1. Try various IP addresses starting with the base address assigned by DHCP (see above)
  2. Look in the DHCP leases table for a MAC address of the following form 54:4A:16:xx:xx:xx

To test a particular IP address try to SSH to it like the following test access for IP address 192.168.0.109:

ssh debian@192.168.0.109

If that address is not online, Windows will report “no route to destination”. If the address is not a Linux machine (as Testdrive is), then the ssh request will likely be refused.  In the final case, as shown above Testdrive will offer a login and tell you the password.

The special user debian

All operations should be conducted logged in as user debian.  That’s why the ssh login is for that user.  That user is allowed to perform all privileged operations by prefixing privileged commands with sudo.  Here’s an example:

sudo ifdown usb0

Without the sudo prefix, this operation would not succeed.

In addition to this, the network utilities iperf and iperf3 (see below) are available to user debian.

Beagle Testdrive USB Network Testing

Previous sections have shown how to write a TestDrive SD, boot the Beagle with it in the SDHC slot, and login to Testdrive.  The system is very flexible as to USB network protocol, hardware parameters (vendor ID, product ID, etc), but as shipped it is ready to use immediately.  Later sections discussion optional customization steps .

So now we get down to the main activity: network tests, relying principally on the iperf3 tool.  Other standard tools are also part of TestDrive.

A USB network test begins with the USB network configuration selected as described above. This may require a reboot.

Start with the USB cable unplugged.

  1. Login to the TestDrive system as described above via the Ethernet network interface, not the USB interface.
  2. Run a test tool in server mode, either on the Beagle or on the PC. Some common possibilities are described in detail below.
  3. Connect the USB  cable
  4. Run a matching client test tool on the other end of the link.

Testing with iperf3

The tool iperf3 is an extremely flexible and durable network testing tool, and suitable for endurance and performance testing of network links.  It has many tunable parameters, too many to mention here, but the default running modes are very useful without any tuning.  The full iperf/iperf3 story is documented here.

Step 3 of the procedure in the previous section calls for running a test tool in server mode. The following commands do this for the iperf3 tool, either on the PC or the Beagle.  

iperf3 -s -p 5000

iperf3 -s -p 5000 -i 60

These commands are variants. The first is the basic version. It listens on TCP and UCP ports 5000, and after a connection with a client, summarizes activity every second.

The second command increases the reporting interval to 60 seconds (the maximum).

If this command is run on the PC, Windows Firewall will request the user’s permission to use the ports. Otherwise, there is no difference between the Beagle and Windows commands.

Examples of client-side iperf3 tests

Assuming that the iperf3 server is running on the USB link, we can give examples as long as we know the IP address of the other end of the link.  These examples work on the PC side of the link and assume that the Beagle/Testdrive side of the link has IP address 169.254.1.2.

The examples below show commands initiated from the host, but the optional --reverse flag allows the device to be the effective client.

After a test is concluded, another test can be run without restarting the iperf3 server.

A one hour test using TCP

iperf3 -c 169.254.1.2 -p 5000 -t 3600 -i 60 

In detail, this connects to IP address 169.254.1.2 on TCP port 5000, and reports at intervals of 60 seconds for a total test time of 3600 seconds.

A one-hour test with 4 parallel TCP streams

iperf3 -c 169.254.1.2 -p 5000 -t 3600 -i 60 -P 4

This adds the -P 4 (parallel 4) option from earlier versions of iperf.  So this means 4 client streams.

initiates an hour-long test with reporting at 1-minute intervals. To run a UDP-based test simply insert the extra argument -u after the IP address.

A one-hour TCP test with the device as the effective client

iperf3 -c 169.254.1.2 -p 5000 -t 3600 -i 60 --reverse

This is a reverse-direction test, where the “server” sends data which is echoed by the client.

Note that the familiar -d (bidirectional) flag from iperf now has a different meaning (debug) and bidirectional is no longer available as such   However the same effect is available by running two iperf sessions, one using the --reverse flag.

A 10 hour reverse direction test with UDP using 10 streams

iperf3 -c 169.254.1.2 -u -p 5000 -t 36000 -i 600 -P 10  --reverse

Combined tests

The four previous examples can all be entered into four separate command windows and run in parallel.

Web based testing.

The Beaglebone uses port 80 for internal purposes. However, port 8080 is allocated to the internal web-server.  In addition, as a web client, the utilities wget and curl are available.

TestDrive USB Configuration

When TestDrive boots, a stored USB network configuration is activated. The parameters of this configuration consist of the following information:

As shipped, the active stored configuration is rndis-nodhcp, meaning the RNDIS protocol is selected with the fixed IP address 169.254.1.2  (no DHCP client active).

All the various stored configurations are designed to use Belcarra USBLAN for Windows , and the hardware ID’s are set to correspond to assignments for the Demo version of USBLAN, which is freely available, but only works for 30 minutes at a time (needs a replug event to work again).

Stored configurations use other protocols with or without the DHCP server option for USBLAN (see USBLAN OEM manual for details about that). However, TestDrive streamlines this process and changing protocols and options is as simple as changing a different stored configuration.

See below for how to change the active storage configuration and how to create new configurations.

Setting up a USB network configuration

Here are some examples with comments

Example 1 Activate a stored configuration.

There are numerous stored USB network configurations in Testdrive as shipped, and others can be defined as needed.  They are found in directory /home/debian/usb.

The following command makes the contents of /home/debian/usb/usb.rndis-nodhcp the active configuration at the next reboot.

usbsetup -s rndis-nodhcp

The change takes effect when the boot is power-cycled or  the following command is issued

sudo reboot

Example 2: Immediate temporary configuration change..

Set up protocol EEM with VID=0x15EC PID=0xD041 dynamically, DHCP enabled. The eem command first removes any USB network modules already running, and then sets up the EEM protocol according to the command line parameters.  Here is a complete sequence of commands:

eem 15ec d041 #Tear down whatever’s running and install eem

[connect USB cable to PC]

sudo ifdown usb0

sleep 5

sudo ifup usb0

Likewise, there are ecm, ncm, and rndis commands that do the same thing for their respective protocols.

Note that the ifup command runs a DHCP client. For a fixed IP address, use the lower level ifconfig command as follows:

ifconfig usb0 169.254.1.2 netmask 255.255.255.248 up

Example 3: Create a new stored configuration

This example sets up a new stored configuration called demo2, using protocol ECM with VID=0x15EC PID=0xD042, no DHCP.  Since there is no DHCP, use fixed IP address 169.254.100.2.

  1. In subdirectory usb of /home/debian, create a new file called for example usb.demo2.  Put the following lines in usb.demo2. Note the lack of the 0x prefix in the hex values

VID=15ec

PID=D042

FIXEDIP=169.254.100.2

This creates the demo2 stored configuration,  but it is not yet active. To make it active, issue the following command:

usbsetup -s demo2

The configuration takes effect at the next reboot.

Predefined network configurations.

As shipped, Testdrive has a wide range of stored configurations. The active one is rndis-nodhcp.  A complete list follows.

:

These configurations all have demo drivers available from Windows Update. These are automatically downloaded and installed as necessary. As noted in the OEM Manual for USBLAN, the demo version of USBLAN, active on the special vendor ID’s D041 and D042  have forced DHCP choices:

Those are USBLAN choices -- to activate the DHCP server or not.  This choice should be matched with a choice on the Beagle to run a DHCP client on usb0 or not. The presets all make sane choices in this regard.  For instance: ncm-nodhcp chooses VID D042 and turns off the DHCP client on usb0.

On the PC, if DHCP is disabled, then new Network Connection should be assigned the fixed IP address 169.254.1.1. This is the choice for the built in configurations.  This is the same IP address as the DHCP server, when active, assigns.  So this is a good choice for all the tests.

The pre-selected configuration, when the SD is freshly written, is rndis-nodhcp, the RNDIS protocol with the USBLAN DHCP server inactive/disabled, and the fixed IP address 169.254.1.2 on the Beagle  side.

Control access

Standard Debian/wheezy uses the USB link as a control access link.  TestDrive, however, is a USB test system, and must maintain independent use of the USB link, including having it disabled at times.

Therefore, primary control access is through the Ethernet network interface. This of course relies on an independent power source, not the USB cable .

Nevertheless TestDrive is setup to use Belcarra USBLAN Demo version, which is automatically installed from WIndows Update as necessary with no user action needed[1].  This creates a new network interface in the Windows Device Manager.

As long as any of the predefined USB network configurations are in use, it will be possible to access  the Beaglebone over the USB link as follows from the test PC.

ssh debian@169.254.1.2

Customizing Testdrive

For many purposes, TestDrive comes ready to be used, without making any changes.  Changing the USB Network profile has already been discussed.  A few other minor points may be of interest.

Fixed IP address for the Ethernet interface

As noted, if MDNS is not available, an initial search for the Ethernet IP address of Testdrive may be necessary.  Once found, it will likely seldom change, but even this inconvenience can be overcome by assigning the Ethernet interface eth0 a fixed IP address. This can be achieved by modifying the file /etc/network/interfaces. Modifications take effect on the next boot. This is potentially dangerous.  Might be useful to backup the SD image first.

Multiple Testdrive boards

If you have 2 or more boards on the network, then you can change their symbolic names as follows:

Change /etc/hostname and /etc/hosts to include a new name for additional boards.


Copyright ©2005 - 2016 Belcarra Technologies (2005) Corp


[1] On some machines administrative action is needed to permit the device updates from WIndows Update.