Hidviz decodes USB HID reports so you can work out what a device sends

A traffic viewer for the HID class, not a HID driver

Hidviz is a GUI application for in-depth analysis of USB HID class devices, and the documentation names two use cases: reverse engineering existing devices and developing new ones. The scope of the HID class is broader than most people assume. It covers the obvious cases, mice, keyboards, joysticks and gamepads, but the documentation also points at weather stations, medical equipment such as thermometers and blood pressure monitors, and simulation devices like flight sticks. That breadth is the reason a tool like this exists, because each of those device classes has a different report descriptor and a different idea of what its report bytes mean. Hidviz does not replace the operating system's input handling and it is not a driver. It sits beside the device, decodes what the device reports, and shows you the structure, which is exactly what you need when the manual is wrong or missing.

Qt, libusb, protobuf and a C++14 toolchain

The dependency list tells you what kind of tool this is. A C++ compiler with C++14 support, libusb 1.0, protobuf, with version 2 enough, Qt6 base, and CMake 3.2 or newer. The Qt dependency is what makes it a GUI application rather than a command line filter, and libusb is what lets it sit on the wire at a level where individual reports are visible. The repository layout backs this up, with a `hidviz` directory for the application itself and a separate `libhidx` directory for the HID parsing library, plus a `scripts` directory and a `Doxyfile` for documentation generation. The `libhidx` split is worth noting, because it means the protocol handling and the user interface are separate pieces, and a protocol layer that lives in its own directory is usually one that others have reused. Protobuf handles the serialisation of the captured data, which is what makes an analysis session something you can save and compare later rather than something that only exists on screen.

Building on Fedora or Ubuntu

The supported platforms are Fedora, Ubuntu and MSYS2 on Windows, with experimental support on macOS that has been tested on an M1 based Mac. The Linux path is the one the project develops on. On Fedora the prerequisites come from the distribution.

sudo dnf install cmake gcc-c++ qt6-qtbase-devel protobuf-devel libusbx-devel asio-devel

On Ubuntu the package set differs slightly, notably pulling in the protobuf compiler and the Mesa GL development files.

sudo apt-get install build-essential qt6-base-dev libprotobuf-dev protobuf-compiler libusb-1.0-0-dev libgl1-mesa-dev cmake libasio-dev

The `libusbx-devel` and `libusb-1.0-0-dev` names are the same library under two distribution names, and the documentation notes that libusb can be called libusbx in your distro. Once the packages are in place, the source is fetched and an out of source build directory prepared.

git clone --recursive https://github.com/ondrejbudai/hidviz.git
mkdir hidviz/build
cd hidviz/build

The recursive flag is not optional. The repository carries a `.gitmodules` file, and the documentation states plainly that you have to do a recursive clone, so a plain clone leaves you without the protocol definitions the build expects.

Configuring and compiling with CMake

Configuration on Linux is a single CMake invocation from the build directory, and the Windows variant only adds a generator name. The macOS invocation passes the Qt6 directory explicitly and points the prefix path at the Homebrew prefix.

cmake ..

cmake -G "Unix Makefiles" ..

cmake .. -DQt6_DIR=$(brew --prefix qt6)/lib/cmake/Qt6 -DCMAKE_PREFIX_PATH=/opt/homebrew

The macOS line carries a warning worth passing on. The documentation notes that if you are on an M1 based Mac you should ensure the build environment matches the host architecture, and describes a failing build caused by using an x86 version of the editor, which broke the `arch` query the build performs, with a native terminal fixing the problem. The compilation step itself is a parallel make.

make -j$(nproc)

There is one environment trap on Windows. The documentation says to check before building that you are using the MinGW32 or MinGW64 shell, otherwise the build will not work, which is the kind of detail that only appears when a maintainer has lost an afternoon to it.

The working directory requirement and installing the binary

Running the tool has a requirement that is stated in bold: you need `build/hidviz` as your current directory for hidviz to work properly. The documented sequence is to change into the directory and launch the binary.

cd hidviz
./hidviz

The reason is not explained, which is a reasonable thing to notice if you move the binary or run it from elsewhere and it misbehaves. On Linux you can install it system wide with a make target.

sudo make install

There is also a packaged route, since Hidviz is available from the Arch Linux AUR.

pacaur -S hidviz

The AUR package is worth mentioning because it is the difference between a tool you try once and a tool you keep. A tool that only runs from a build directory is a tool you will not reach for a second time, whereas a package you can install and launch from anywhere becomes part of your workflow. On Windows there is a further step, since you cannot use hidviz out of the box there. You have to install custom drivers for the devices you want to analyse, and the recommended approach is to download Zadig and install libusbK to the target device, with the libusb wiki linked for the background on why Windows needs this.

Platform support is uneven and stated as such

The project is direct about where it is solid and where it is not. The Windows note says hidviz is primarily developed on Linux and that there is currently no Windows CI, therefore the Windows build can be broken at any time, and it asks you to open an issue if you find that to be the case. The macOS note says hidviz on macOS is not an officially supported platform, that it has been known to work but your mileage may vary. Neither of those notes is unusual for a hobby-scale tool, but they change how you should plan around it. If your work depends on this running on a particular machine, treat the Linux path as the reference and the others as best effort. There is also an inconsistency in the prerequisite lists that a careful reader will spot: the macOS section says to install qt6 and protobuf via brew, while the command shown installs `qt@5` rather than Qt6, even though the configuration command for that platform passes a Qt6 directory. Whether that is a documentation slip or a deliberate downgrade for the macOS build, the README does not resolve it.

Release history and the cost of picking it up now

The release list is short: v0.2.1 in April 2025, v0.2 in March 2023, and v0.1.5 in December 2019. The last push to the repository was on 2026-08-07, so there is work after the most recent tag even though the version number has not moved. A version below 1.0 with a two year gap between the last two tags tells you this is a tool maintained in bursts rather than on a schedule, and the 2019 to 2023 gap is a long time for a project whose main risk is the USB stack and the Qt version moving underneath it. The licence is GPLv3 or later, which is fine for a tool you run on your own machines and means that a modified build you distribute carries the copyleft obligations. The Doxyfile and the `libhidx` directory suggest the intent was for the parsing library to be reusable, and the Arch package and the `scripts` directory suggest an intent to package and automate. Neither of those intentions is documented as a roadmap, so if you need a supported tool with a stated maintenance commitment, this is not it.

Editorial conclusion

Adopt Hidviz if you need to see what reports an unfamiliar HID device actually sends, or to develop a device and check that your descriptor and report layout are what you intended. Skip it if you only need to read a keyboard or mouse, since the platform already does that, or if you are not prepared to build from source and install libusb drivers on Windows. Before you start, clone recursively, because the project carries submodules, and read the running note: the binary expects build/hidviz to be its working directory.

Frequently asked questions

Official sources

1. hidviz/hidviz on GitHub
2. Issues
3. License: GPL-3.0
4. README
5. Releases