microsoft · usivagna · Nov 25, 2025
diff --git a/README.md b/README.md
@@ -1,10 +1,72 @@
-# Bus tools for Windows
+# Bus I/O Tools for Windows
 
-This repo contains the scripts and tools to help discover and diagnose issues developers may encounter when making a peripheral work for Windows. The tools and scripts are described in greater detail on our [blog](https://blogs.msdn.microsoft.com/usbcoreblog/).
+A comprehensive collection of diagnostic tools and scripts for troubleshooting Windows peripheral devices and buses. These tools help developers debug and diagnose issues with USB, Bluetooth, sensors, cameras, and other hardware components.
 
-## Directory of Tools
-* [HMD Validation Kit](hmdvalidationkit/README.md)
-* [USB, HID and Simple Peripheral Buses- I2C, UART, SPI Tools](usb/README.md) 
-* [Sensor Tools](sensors/README.md) 
-* [How to collect Bluetooth logs](bluetooth/tracing/readme.md)
-* [Windows Camera Tracing](camera/Tracing/Readme.md)
+For detailed technical information and best practices, visit our [Microsoft USB Blog](https://techcommunity.microsoft.com/t5/Microsoft-USB-Blog/bg-p/MicrosoftUSBBlog).
+
+## 📦 Quick Start
+
+Download the complete toolkit:
+```powershell
+# Download as ZIP
+https://github.com/Microsoft/busiotools/archive/master.zip
+
+# Or clone with git
+git clone https://github.com/Microsoft/busiotools.git
+```
+
+## 🔧 Tools Overview
+
+### USB & Simple Peripheral Buses
+**[USB, HID, I2C, UART, and SPI Tools](usb/README.md)**
+- Comprehensive tracing for USB and HID devices
+- Support for I2C, UART, and SPI peripheral buses
+- Built-in diagnostics and troubleshooting utilities
+- Install via winget: `winget install windowsbusestracing`
+
+### Bluetooth
+**[Bluetooth Tracing & Diagnostics](bluetooth/tracing/readme.md)**
+- Capture Bluetooth stack logs using Windows Performance Recorder (WPR)
+- Support for both single-session and cross-reboot tracing
+- Radio information and connection diagnostics
+
+### Sensors
+**[Sensor Tools & Testing](sensors/README.md)**
+- **SensorExplorer**: Real-time sensor monitoring application ([Store App](http://aka.ms/sensorexplorer))
+- **MonitorBrightnessApp**: Visualize brightness values in real-time
+- **BrightnessTests**: Automated brightness testing scripts
+- **MALT**: Screen brightness measurement and testing hardware
+- Sensor tracing and logging utilities
+
+### Camera
+**[Camera Tracing](camera/Tracing/Readme.md)**
+- PowerShell-based camera tracing scripts
+- Support for desktop and device scenarios
+- Performance profiling capabilities
+- Boot trace support for initialization issues
+
+### HMD Validation Kit
+**[HMD (Head-Mounted Display) Testing](hmdvalidationkit/README.md)**
+- Managed C# libraries for HMD hardware validation
+- Automated testing for USB, HDMI, display, and audio
+- COM port-based device control
+
+### Simple Peripheral Buses
+**[SPB (I2C & SPI) Tracing](spb/README.md)**
+- SpbCx driver tracing utilities
+- Support for both live and autologger modes
+- Offline hive analysis
+
+## 📚 Additional Resources
+
+- [Official Documentation](https://docs.microsoft.com/en-us/windows-hardware/drivers/)
+- [Microsoft USB Blog](https://techcommunity.microsoft.com/t5/Microsoft-USB-Blog/bg-p/MicrosoftUSBBlog)
+- [Windows Hardware Dev Center](https://developer.microsoft.com/en-us/windows/hardware/)
+
+## 🤝 Contributing
+
+This project is maintained by Microsoft. For issues, questions, or contributions, please refer to [SUPPORT.md](SUPPORT.md) and [SECURITY.md](SECURITY.md).
+
+## 📄 License
+
+This project is licensed under the terms specified in [LICENSE](LICENSE).
diff --git a/usb/README.md b/usb/README.md
@@ -1,30 +1,112 @@
 # USB, HID and SPB Diagnostics
 
-## Review blog posts and documentation
-Before filing a bug report, please review existing [blog posts](https://techcommunity.microsoft.com/t5/Microsoft-USB-Blog/bg-p/MicrosoftUSBBlog) and [documentation](https://docs.microsoft.com/en-us/windows-hardware/drivers/usbcon). They cover a variety of common problems including troubleshooting HLK failures.
-
-If these topics do not cover what you're looking for, please follow these steps to collect files for your bug report.
-
-### 1. Collect Traces
-- Install/deploy tracing files; either (choose (i) OR (ii), not both):-
-  1. Install tracing files from [winget](https://learn.microsoft.com/en-us/windows/package-manager/winget/)
-     - Run `winget install windowsbusestracing` from an elevated command prompt
-     - Run `startwindowsbusestracing` from an elevated command prompt
-  2. OR Use tracing files directly
-     - Download the following three files:
-     [BusesAllProfile.wprp](https://raw.githubusercontent.com/microsoft/busiotools/master/usb/tracing/BusesAllProfile.wprp), [BusesTrace.cmd](https://raw.githubusercontent.com/microsoft/busiotools/master/usb/tracing/BusesTrace.cmd), and [UtilityCollectMiniDumps.ps1](https://raw.githubusercontent.com/microsoft/busiotools/master/usb/tracing/UtilityCollectMiniDumps.ps1)
-     - Run **BusesTrace.cmd** from an elevated command prompt.
-- At the first menu, select "**Start Tracing**".
-- At the second menu select the component in which tracing is desired: for example select "**Input/HID components only**" if you are reporting an input related issue. If unsure, you can also select "**All buses components**".
-- At the next menu, choose to either start tracing now, or start tracing on next boot session.
-- Follow the on-screen instructions to reproduce the issue and conclude the files.
-- If applicable, note the approximate time the problem happened in the bug report. For example "the problem happened around 13:50:25 (hh:mm:ss)", or "the problem started about 5 seconds before tracing was stopped."
-
-### 2. Memory Dump
-If you are reporting a system crash or hang, please include a memory dump along with the output from kernel debug command "!analyze -v" in the bug report.
-USB and other kernel debugger extensions are [documented here](https://docs.microsoft.com/en-us/windows-hardware/drivers/debugger/usb-3-extensions)
-
-Display/sensor minidumps are automatically collected if you select "sensor components only" in the second menu **BusesTrace.cmd**. A full dump might still be required.
-
-[Back to root](http://aka.ms/bustools) 
+## Overview
+
+This guide provides step-by-step instructions for collecting diagnostic information when troubleshooting USB, HID (Human Interface Devices), and SPB (Simple Peripheral Bus: I2C, UART, SPI) issues on Windows.
+
+## Before You Start
+
+**Review existing resources first** - Many common issues are already documented:
+- [Microsoft USB Blog](https://techcommunity.microsoft.com/t5/Microsoft-USB-Blog/bg-p/MicrosoftUSBBlog) - Technical articles and troubleshooting guides
+- [USB Driver Documentation](https://docs.microsoft.com/en-us/windows-hardware/drivers/usbcon) - Official Windows USB driver documentation
+- [HLK Troubleshooting](https://docs.microsoft.com/en-us/windows-hardware/test/hlk/) - Hardware Lab Kit common issues
+
+If these resources don't address your issue, follow the steps below to collect diagnostic data for a bug report.
+
+---
+
+## Step 1: Collect Traces
+
+Traces capture detailed system activity and are essential for diagnosing bus-related issues.
+
+### Installation Method (Recommended)
+
+**Using winget** - Easiest method for most users:
+
+1. Open an **elevated** Command Prompt (Run as Administrator)
+2. Install the tracing package:
+   ```cmd
+   winget install windowsbusestracing
+   ```
+3. Start tracing:
+   ```cmd
+   startwindowsbusestracing
+   ```
+
+### Manual Method
+
+**Direct file download** - Use when winget is unavailable:
+
+1. Download these three files:
+   - [BusesAllProfile.wprp](https://raw.githubusercontent.com/microsoft/busiotools/master/usb/tracing/BusesAllProfile.wprp)
+   - [BusesTrace.cmd](https://raw.githubusercontent.com/microsoft/busiotools/master/usb/tracing/BusesTrace.cmd)
+   - [UtilityCollectMiniDumps.ps1](https://raw.githubusercontent.com/microsoft/busiotools/master/usb/tracing/UtilityCollectMiniDumps.ps1)
+
+2. Open an **elevated** Command Prompt in the download directory
+3. Run the trace script:
+   ```cmd
+   BusesTrace.cmd
+   ```
+
+### Configuring the Trace
+
+Follow the on-screen menus:
+
+1. **First menu**: Select **"Start Tracing"**
+
+2. **Second menu**: Choose the component to trace:
+   - **"Input/HID components only"** - For keyboard, mouse, touch, or HID device issues
+   - **"USB components only"** - For USB storage, connectivity, or enumeration issues
+   - **"Sensor components only"** - For sensor-related problems (auto-collects minidumps)
+   - **"All buses components"** - When unsure or for multi-component issues
+
+3. **Third menu**: Choose when to start tracing:
+   - **"Start tracing now"** - For issues that occur during normal operation
+   - **"Start tracing on next boot"** - For issues during system startup or driver initialization
+
+### Reproducing the Issue
+
+1. Once tracing starts, **reproduce the problem** that you're experiencing
+2. Follow the on-screen instructions to stop tracing and save the files
+3. **Note the timestamp** when the issue occurred (e.g., "Issue occurred at 13:50:25" or "Problem started 5 seconds before I stopped tracing")
+
+### Output Files
+
+The trace files will be saved to a folder that automatically opens when tracing completes. Include all files from this folder in your bug report.
+
+---
+
+## Step 2: Memory Dump (For Crashes/Hangs)
+
+If you're reporting a **system crash (BSOD)** or **system hang**, additional data is required:
+
+### Required Files
+
+1. **Memory dump file** - Typically located at:
+   - `C:\Windows\MEMORY.DMP` (complete dump)
+   - `C:\Windows\Minidump\` (minidump files)
+
+2. **Debugger analysis output**:
+   - Open the dump file in WinDbg or kernel debugger
+   - Run the command: `!analyze -v`
+   - Save the complete output to a text file
+
+### Additional Resources
+
+- [USB Kernel Debugger Extensions](https://docs.microsoft.com/en-us/windows-hardware/drivers/debugger/usb-3-extensions) - USB-specific debugging commands
+- [Windows Debugging Tools](https://docs.microsoft.com/en-us/windows-hardware/drivers/debugger/) - Download and usage guide
+
+### Automatic Minidump Collection
+
+**Note**: Display and sensor minidumps are automatically collected when you select **"sensor components only"** in the BusesTrace.cmd menu. However, a full memory dump may still be needed for complete analysis.
+
+---
+
+## Need Help?
+
+- **Documentation**: Refer to official Windows Hardware documentation
+- **Community**: Post questions on the [Microsoft USB Tech Community](https://techcommunity.microsoft.com/t5/Microsoft-USB-Blog/bg-p/MicrosoftUSBBlog)
+- **Issues**: See [SUPPORT.md](../SUPPORT.md) for information on reporting issues
+
+[← Back to main README](../README.md)