Testing the Mbed OS USB device

Setup

Before running tests, please make sure to use a top-level requirements.txt file to install all the required Python modules.

pip install -r requirements.txt

Additional, platform-specific setup is described below. See also Known issues.

Windows

1. Install a generic USB driver for two test devices.
   1. Download Zadig application from the Zadig website.
   2. Unplug the Mbed device.
   3. Open Zadig.
   4. Select Device -> Load Preset Device.
   5. Open TESTS/usb_device/basic/zadig_conf/mbed_os-usb_test_device1.cfg
   6. Choose libusb-win32 (v1.2.6.0) driver.
   7. Select Install Driver and click it.
   8. Select Device -> Load Preset Device.
   9. Open TESTS/usb_device/basic/zadig_conf/mbed_os-usb_test_device2.cfg
   10. Choose libusb-win32 (v1.2.6.0) driver.
   11. Select Install Driver and click it.
   12. Close Zadig.
   13. Plug both USB interfaces (DAPLink and USB device).

Linux

1. Install the hidapi Python module, otherwise some USB HID test cases will be skipped. This module is not installed during the initial setup due to external dependencies for Linux.

   For Debian-based Linux distros, the dependencies can be installed as follows (based on module's README):

   apt-get install python-dev libusb-1.0-0-dev libudev-dev
   pip install --upgrade setuptools

   To install the hidapi module itself, please use the attached requirements.txt file:

   pip install -r TESTS/usb_device/hid/requirements.txt

2. Update the udev rules for Mbed USB CDC device as follows (source):

   sudo tee /etc/udev/rules.d/99-ttyacms.rules >/dev/null <<EOF
   ATTRS{idVendor}=="1f00" ATTRS{idProduct}=="2013", ENV{ID_MM_DEVICE_IGNORE}="1"
   ATTRS{idVendor}=="1f00" ATTRS{idProduct}=="2012", ENV{ID_MM_DEVICE_IGNORE}="1"
   EOF
   sudo udevadm control --reload-rules

   This will prevent the ModemManager daemon from automatically opening the port and sending the AT commands, which it does for every new /dev/ttyACM device registered in system.

Mac

No setup method has been verified for this platform.

Running tests

1. Plug both USB interfaces (DAPLink and USB device) to your host machine.
2. An additional macro USB_DEVICE_TESTS is needed to be defined when running tests:

    mbed test -t <toolchain> -m <target> -DUSB_DEVICE_TESTS -n *-tests-usb_device-*

Known issues

Insufficient user permissions on a Linux machine

Some of the tests require privileged access to the USB device. Running these as an unprivileged user will manifest with either of the following errors:

• [HTST][INF] Device not found

• [HTST][INF] TEST ERROR: Failed with "The device has no langid". Tried 20 times.

Solution

Execute tests with elevated permissions using sudo:

mbed test -t <toolchain> -m <target> -DUSB_DEVICE_TESTS -n tests-usb_device-* --compile
sudo mbed test -t <toolchain> -m <target> -n *-tests-usb_device-* --run -v

Note only the mbed test --run command requires sudo. You can still mbed test --compile as a normal user.

Alternative solution

Add an udev rule to set the ownership of the device node as shown here.

Data toggle reset test fails on a Linux machine

The tests-usb_device-basic / "endpoint test data toggle reset" test fails with the following error:

[HTST][INF] TEST FAILED: Data toggle not reset when calling
ClearFeature(ENDPOINT_HALT) on an endpoint that has not been halted.

Implementations of the xHCI driver prior to version 4.17 of the Linux kernel did not have the functionality necessary to test "endpoint test data toggle reset". Even though the data toggle is correctly reset on the device side, the host side will not be synchronized and the test will falsely fail.

Solution

Make sure that at least one of the following prerequisites is met:

• using the Linux kernel 4.17 or newer,
• using the eHCI USB driver instead of xHCI.

Changing the USB driver may be as simple as updating one of the BIOS settings on your machine. If you'd rather avoid rebooting, you can try using setpci command.

Further reading

1. the Linux kernel patch adding missing xHCI behavior,
2. LKML discussion explaining the details of this issue.

Mass storage tests are skipped on some targets

The tests-usb_device-msd test outputs the following message:

[CONN][RXD] SKIP: Not enough heap memory for HeapBlockDevice creation

Solution

A device with at least 70 kB of RAM is required to run this test. The FAT32 filesystem cannot be mounted on a device smaller than 64 kB.

The test can be easily extended to use any block device available in Mbed.

Windows 8/10: Mass storage tests are failing on test file read

By default Windows 8 and 10 access and write to removable drives shortly after they are connected. It's caused by drive indexing mechanisms. Because disk used in test has only 64kB its content can be easily corrupted by writing large files, what actually was encountered during test runs.

To prevent Windows from writing to removable drives on connect drive indexing can be turned off with the following procedure:

• Start the program "gpedit.msc"
• Navigate to "Computer Configuration \ Administrative Templates \ Windows Components \ Search"
• Enable the policy "Do not allow locations on removable drives to be added to libraries."

Isochronous endpoints are skipped in loopback tests

Unresolved

Serial tests fail intermittently on a Linux machine

Unresolved

You may want to connect the device directly to the host machine with no hubs on the way.