Digi AnywhereUSB 2/8/24 Plus - USB Debug Logging Procedure for Troubleshooting Compatibility Issues with USB Devices

USB Debug Logging Wizard procedure

Create a debug log file with the USB Debug Logging Wizard

Please see this link to the AnywhereUSB Plus user guide for information on creating a debug log file with the USB Debug Logging Wizard.

Create a debug log file with the USB Debug Logging Wizard

USB Debug Logging procedure via the Manager

Important Notes:

1. The USB debugging guidance which follows is meant to be used with the Digi AnywhereUSB Plus (2, 8, 24) line of products only.
2. This guidance requires DAL OS/firmware version 20.11.32.168 (or later) (this guidance may not work/will provide less than optimal logging results if an earlier version of firmware is in use).

***The latest Digi AnywhereUSB Plus OS/firmware can be obtained here as necessary, when firmware update is needed prior to the following guidance***

Overview of Test Procedure (i.e. best practices for providing best logs for issue analysis):

• Increase the maximum size of a captured log
• Start the usbtrace
• Connect to a Group (USB device not connected yet)
• Plug in USB device of behavior under investigation
• Get the device to fail/replicate the problem behavior
• Collect usbtrace and support-report files as quickly as possible after issue replication
• Copy/paste the AnywhereUSB Manager's "System Messages" output into a file
• Provide all information gathered to Digi Int'l Tech Support in a zip file (via email) for analysis of problem behavior with USB device

USB Debug Logging Procedure for Digi AnywhereUSB Plus products

1.  Physically unplug any/all USB devices from your Digi AnywhereUSB Plus product (hereafter referred to as "Hub").  Be sure to note which USB device(s) are currently plugged into which USB port(s) of the Hub as you unplug the devices. This is to ensure each of the devices gets plugged back into it's proper USB port when the testing procedure is complete, thus restoring normal operation prior to the test.
 

2. Ensure the AnywhereUSB Manager software installed is the most recent version available here.
 

• Uninstall the previous version of AnywhereUSB Manager software first when updating the AnywhereUSB Manager is needed.

3. Open the AnywhereUSB Manager client/software, and  verify you're not connected to any Groups on your Hub.  If a Group is currently connected, right-click that Group, then chose the "Disconnect from Group" option.

Before continuing, the Status displayed for all Groups should be "No one is using this group" (see below):



4. From the Hub's Web User Interface (WebUI) menu, access the System --> AnywhereUSB Configuration page, then slide the Enable USB debug logging option into the "on" position, and use the Apply button in the upper-right corner of the page to make the settings change take effect.



Note:  The Enable USB debug logging feature will turn "off" again if Hub is rebooted - do not reboot the Hub until this testing procedure is complete.

5. Whether or not your Hub is being managed with Digi Remote Manager®, the Central Management option should be turned "off" from the Hub's WebUI menu under System --> Device Configuration --> Central Management, then hitting Apply (see image below).  Disabling Central Management is useful to produce the best logging results, by removing logfile traffic associated with this service temporarily (see Important Note below the following image): 



(Important Note:  The Central Management option setting is persistent across reboots - Digi recommends re-enabling Central Management for all Hubs being provisioned on the Digi Remote Manager IoT Device Management/Monitoring platform.

6. Under the Hub's WebUI menu, open System --> Administration --> Terminal to access the Hub's built-in Console/CommandLine Interface (hereafter referrred to as "CLI"), then login as the admin user.  If Shell access has been enabled for the admin login on your device, select the Admin CLI option (see below).



Note:  Establishing an SSH connection to the Hub in order to access the CLI can be used instead of the WebUI's Terminal option, when preferred.

7.  The Hub's default log size is short where this troubleshooting is concerned, and may wrap quickly after usbtrace is started in the following step (Example:  with the default setting "3000", a log can fill in 70 seconds with typical usbtrace-enabled debug traffic).

The debug log size should therefore be increased to increase the liklihood of capturing the event of interest with the following CLI command:

> config system log local max_size 60000

(Important Note:  The max_size configuration change is persistent across reboots - Digi recommends changing this value back to the default value (3000) after this procedure is complete, and the results have been provided to Digi Tech Support for analysis.  The value can be reverted to default by returning the value of 60000 back to 3000, using a command similar to the above.

8.  Start the usbtrace debug log with the following CLI command:

> system usbtrace start

9. In the AnywhereUSB Manager client software, connect to whichever Group(s) will allow access to the USB port(s) where the USB device(s) under investigation will be plugged into (in the next step).

***The next four steps are time-sensitive:  Steps 12 - 14 must be completed as soon after the issue has been reproduced (Steps 10 and 11) as possible***

10. Plug the USB device(s) with the "behavior of interest" being tested for  into the USB port(s) which will be necessary to replicate the issue.

11.  Take any additional steps necessary to reproduce the "failed" state (i.e. the status or issue you're troubleshooting),  such as connecting to the USB device with an application which uses the USB device, etc.

12. When the "issue" occurs, immediately take note of the time shown on a local wall clock, phone, etc., and if possible, the amount of time it took to reproduce that state or issue after the usbtrace began.  This allows your "behavior of interest" to be cross-referenced within the logfiles created during the next few steps.

13. From the WebUI "Terminal" window, use the following CLI commands (usbtrace will be running) to first stop the usbtrace debugging process, then save the output to a file called capture1.pcap:

  system usbtrace stop
> system usbtrace save capture1.pcap

14. While still in the Terminal window, capture a Support Report and write it to the  /etc/config/usbtrace folder using the following command:

> system support-report path /etc/config/usbtrace

(All of the preceding CLI commands are visible within the screenshot below)



15. Exit the Terminal  mode with command "exit", then "q" for quit as shown below:

> exit

Disconnected from Admin CLI
Access selection menu:
a: Admin CLI
s: Shell
q: Quit

Select access or quit [admin] : q

16.  Access the File System area via the Hub's WebUI menu as follows:

• Go to System --> Administration --> File System
• Select/highlight the usbtrace folder
• Use the arrow-curving-right icon to Enter directory.

Opening usbtrace folder:


17. Download the capture1.pcap and digi-support... files by highlighting each of the two filenames in turn, then selecting the Download file icon:



18. In the AnywhereUSB Manager client software menu, access the Help area, then select the Create Support File option.  The resulting file is called awusbmanager_support.bin, which can be found under Documents of the User's home directory (example:  C:\Users\<user>\Documents\awusbmanager_support.bin.  Take note of the location of the awusbmanager_support.bin file, so that it can be included within the zip file attached to your email reply to Digi Tech Support in the following step.



19. If possible, add the capture1.pcap, digi-support... Support Report file, and the awusbmanager_support.bin file into a .zip file, then attach the zip file to your email reply for Digi Technical Support within the Digi Tech Support case documenting the issue.

If the resulting .zip file is too large for email, the Digi Tech Support Engineer your working with can provide a Box folder so you can upload the files - please coordinate as necessary.

Important Note:  Be sure to include the time when the replicated issue occurred (Step 12) in your email with the logs etc attached, so that the behavior of interest can be cross-referenced within the logfiles you're providing.