This project is a simulated UMDF driver for Ultra-Wideband (UWB) devices on Windows. It is intended to be used to test components of the nearobject framework.
This project is organized to make use of the common development libraries provided by the nearobject-framework. However, being a UMDF Windows driver, it is not (yet) supported to be configured or built directly with CMake (see here and here). Consequently, it is a traditional MSBuild UMDF driver project using the WindowsUserModeDriver10.0 platform toolset. See the build architecture section for additional details.
Pre-requisites:
Follow the instructions on the Windows WDK download page to install the above pre-requisites. In Step 1 when installing Visual Studio and selecting workloads, in addition to the Desktop development with C++ workload, you must also install the Linux and embedded development with C++ workload to obtain built-in support for vcpkg. The vcpkg support applies to Windows as well, but the feature started out on Linux and hasn't yet been moved to an appropriate VS installer feature set option.
Last, install vcpkg system-wide using the instructions here. Once installed, execute the following command: vcpkg integrate install which integrates vcpkg with Visual Studio.
The project also contains a build task for Visual Studio Code. However, it is simple and only meant for convenience. Most build tasks and deployment scenarios will be much easier to accomplish from Visual Studio.
The simulator driver depends on a few libraries from the main nearobject-framework project. These dependencies are resolved using the newly added vcpkg support in Visual Studio (Visual Studio 2022 17.4+). This is controlled by two files in the driver project:
- vcpkg.json: The vcpkg "manifest" which defines the dependencies this project depends on.
- vcpkg-configuration.json: The vcpkg configuration which defines where to resolve the dependencies defined in the vcpkg.json manifest.
The main project defines a vcpkg called nearobject-framework which makes its libraries available via vcpkg tooling. The package exposes a feature called msvc-link-static-runtime which forces its libraries to statically link against the VC++ runtime, which is required when using the WindowsUserModeDriver10.0 platform toolset as per here. Consequently, this feature is selected in the driver's vcpkg manifest. The package also exposes a feature called enable-development which controls the version of the code the nearobject-framework vcpkg will make available. Typically, the package will expose a stable version of the code for public consumption. However, during early development of the feature, it is more common for the inner development loop to use the HEAD revision of the code. Consequently, the this feature is currently selected in the driver's vcpkg manifest. Eventually, this will be removed once a baseline working simulator driver has been established.
- Ensure all pre-requisites have been installed.
- Check out the main project if not already done.
- Configure the project with CMake (see here).
- Open the simulator driver solution file UwbSimulator.sln in Visual Studio 2022.
- Build the
UwbSimulatordriver project.
Any time new changes are made to dependent libraries in the main project (eg. uwb, windows-devices-uwb-cx-adapter, uwbcx-driver, etc.), Visual Studio must be instructed to rebuild the nearobject-framework vcpkg. The easiest way to do this is to delete the timestamp file associated with the package. This can be found under ${MSBuildProjectDirectory}/vcpkg_installed/x64-windows/.msbuildstamp-x64-windows.stamp, for example D:\src\nearobject-framework\windows\drivers\uwb\simulator\vcpkg_installed\x64-windows\.msbuildstamp-x64-windows.stamp. So, the process to ingest the changes is:
- Make the changes to the main project library or libraries and ensure the
install(orALL_BUILD) target builds successfully. - Commit the changes. The changes do not have to be pushed to a remote; committing to the local repository is fine.
- Reconfigure the project using cmake. This will also automatically delete the timestamp file.
- Rebuild the UwbSimulator driver project in Visual Studio.
The project output window should display a line indicating the the nerarobject-framework vcpkg needs to be rebuilt, similar to below:
1>The following packages will be rebuilt:
1> nearobject-framework[core,enable-development,msvc-link-static-runtime]:x64-windows -> 1.0.0 -- D:\src\nearobject-framework\windows\drivers\uwb\simulator\../../../../packaging/vcpkg/ports\nearobject-frameworkThe main project will eventually be updated to detect when a commit is made and automatically regenerate the vcpkg port file. Until then, this brief manual process must be followed.