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.
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):
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:
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.
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
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.
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.
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.
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.
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.
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.
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.
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.
iperf3 -c 169.254.1.2 -u -p 5000 -t 36000 -i 600 -P 10 --reverse
The four previous examples can all be entered into four separate command windows and run in parallel.
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.
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.
Here are some examples with comments
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
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.
ifconfig usb0 169.254.1.2 netmask 255.255.255.248 up
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.
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.
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.
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
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.
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.
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.