This project provides a complete framework for running Z-Wave CTT certification tests against a Controller DUT with device emulation based on the "Open Source" Z-Wave stack.
As long as CTT-Remote does not run on Linux, we use WSL (Windows Subsystem for Linux) to run the Z-Wave stack binaries in a Linux environment while controlling them from Windows.
- Windows 10/11 or Windows Server
- WSL with Ubuntu installed
- .NET Framework 4.8 (for CTT-Remote)
In addition, the test orchestrator requires:
- Node.js 24 or later
- The
ghCLI tool for downloading the Z-Wave stack binaries from GitHub and authentication
┌──────────────────────────────────────────────────────────┐
│ Windows (Local or CI) │
│ │
│ ┌────────────────────────────────────────────────────┐ │
│ │ WSL (Ubuntu) - CTT Devices │ │
│ │ │ │
│ │ • Controller 2 → TCP :5001 (CTT Controller1) │ │
│ │ • Controller 3 → TCP :5002 (CTT Controller3) │ │
│ │ • End Device 1 → TCP :5003 (CTT EndDevice1) │ │
│ │ • End Device 2 → TCP :5004 (CTT EndDevice2) │ │
│ │ • Zniffer → TCP :4905 (CTT Zniffer) │ │
│ └────────────────────────────────────────────────────┘ │
│ ↑ │
│ ┌────────────────────────────────────────────────────┐ │
│ │ CTT-Remote.exe │ │
│ │ Connects to controllers/devices on ports 5001-5004 │ │
│ └────────────────────────────────────────────────────┘ │
│ ↑ │
│ WebSocket :4712 │
│ ↓ │
│ ┌────────────────────────────────────────────────────┐ │
│ │ Orchestrator │ │
│ │ Controls test execution and coordinates components │ │
│ └────────────────────────────────────────────────────┘ │
│ ↑ │
│ WebSocket :4713 │
│ ↓ │
│ ┌────────────────────────────────────────────────────┐ │
│ │ DUT Runner │ │
│ │ Manages DUT lifecycle and handles CTT prompts │ │
│ │ Controls DUT device │ │
│ └────────────────────────────────────────────────────┘ │
│ ↓ │
│ ┌────────────────────────────────────────────────────┐ │
│ │ WSL (Ubuntu) - DUT Device │ │
│ │ │ │
│ │ • Controller 1 → TCP :5000 (DUT) │ │
│ └────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────┘
git clone <repository-url>
cd remote-ctt-testsnpm installRun these commands in WSL (open WSL terminal with wsl):
sudo dpkg --add-architecture i386
sudo apt-get update
sudo apt-get install -y libc6:i386 libstdc++6:i386These commands:
- Enable 32-bit architecture support
- Install 32-bit C/C++ libraries required by the Z-Wave binaries
- Make the Z-Wave binaries executable
CTT is not included in this repository. You need to install it separately. It will later be bundled so it can be used in CI.
If the location differs from the default install location, set the CTT_PATH environment variable.
powershell .\setup\download-zwave-stack.ps1Note: This setup assumes the DUT is a controller, which connects to the emulated controller on port 5000. Testing sample applications (end devices) should also be possible but requires copying additional files from the stack binaries, and updating the
zwave_stack/run.shscript accordingly.
npm run devicesStarts 6 Z-Wave binaries in WSL:
| Device | Port | Purpose |
|---|---|---|
| Controller 1 | 5000 | Your DUT connects here |
| Controller 2 | 5001 | CTT |
| Controller 3 | 5002 | CTT |
| End Device 1 | 5003 | CTT |
| End Device 2 | 5004 | CTT |
| Zniffer | 4905 | CTT packet capture |
These can now be used to set up the CTT project.
- Create a new project in CTT GUI
- Set up 5 IP-based devices:
- 2x Controller:
127.0.0.1:5001and:5002 - 2x End Device:
127.0.0.1:5003and:5004 - 1x Zniffer:
127.0.0.1:4905
- 2x Controller:
Configure DUT to connect to tcp://127.0.0.1:5000, then establish the test network:
- Option A: DUT includes CTT devices into its network
- Option B: CTT includes DUT into its network
To test both scenarios, you'll need separate CTT projects.
Make sure to finish creation of the network, including the query for DUT capabilities.
Copy from CTT's project folder to ctt/project/:
ctt/project/
├── Config/ # All config files
├── json/ # JSON configurations
├── <your-project>.cttsln # Project file
└── ZWave_CTT_CommandClasses.cttxml # Command classes definition
Implement the IPC protocol (JSON-RPC 2.0 over WebSocket):
- Connect to port 4713 (or
RUNNER_IPC_PORTenv var) - Required methods:
readynotification (on connect)start(initialize DUT with controllerUrl and security keys)stop(shutdown DUT)handleCttPrompt(respond to CTT prompts)
See dut/zwave-js/run.ts for a reference implementation and docs/ipc-protocol.md for the full protocol specification.
{
"dut": {
"name": "Your DUT Name",
"runnerPath": "your-dut/run.ts",
"homeId": "d34db33f",
"storageDir": "your-dut/storage",
"storageFileFilter": ["%HOME_ID_LOWER%.jsonl"]
}
}Field explanations:
runnerPath: Path to your DUT runner script. Supports Node.js (TypeScript/JavaScript), Python, or any executable that your system can handle running directly, e.g. with a shebang.homeId: Must match the Home ID of your test network (from CTT setup)storageDir/storageFileFilter: Used to transfer DUT network state to GitHub for automated CI testing. The filter patterns support placeholders:%HOME_ID_LOWER%- homeId in lowercase%HOME_ID_UPPER%- homeId in uppercase
powershell .\setup\pack-ctt-archive.ps1
powershell .\setup\pack-network-state-archive.ps1Both archives are required for CI/automated testing. They will need to be regenerated if the CTT setup or project changes.
- ctt-setup.zip: Contains CTT (closed-source, vendored) keys, appdata, and configuration
- network-state.zip: Contains network state for emulated Z-Wave devices and DUT storage
Check in:
config.json- DUT runner script (
your-dut/run.ts) - CTT project files (
ctt/project/) - Setup archives (
setup/ctt-setup.zip,setup/network-state.zip)
Update .gitignore:
The default .gitignore excludes common paths, but may need modifications depending on how your DUT stores state.
Add exclusions for your DUT's storage directory (e.g., your-dut/storage/). This should be included in the network-state.zip archive instead.
To test locally, run:
npm run start -- [options]| Option | Description |
|---|---|
--discover |
List all available test cases grouped by category |
--test=<name> |
Run a specific test by name |
--test=<n1>,<n2> |
Run multiple tests (comma-separated) |
--category=<cat> |
Run all tests in a category (partial match, case-insensitive) |
--category=<c1>,<c2> |
Run tests from multiple categories |
--group=<grp> |
Run tests in a group (Automatic or Interactive) |
--group=<g1>,<g2> |
Run tests from multiple groups |
--dut=<path> |
Path to DUT runner (defaults to config.json runner path) |
--devices-only |
Only start emulated Z-Wave devices, without CTT or the DUT runner |
--verbose |
Show CTT-Remote log output |
| Variable | Default | Description |
|---|---|---|
CTT_PATH |
C:\Program Files (x86)\Z-Wave Alliance\Z-Wave CTT 3 |
Path to CTT installation |
# List all available tests
npm run start -- --discover
# Run a single test
npm run start -- --test=CC_Binary_Switch_Set
# Run multiple specific tests
npm run start -- --test=CC_Binary_Switch_Set,CC_Binary_Switch_Get
# Run all automatic tests (for CI)
npm run start -- --group=Automatic
# Run all tests in a category
npm run start -- --category=Binary
# Combine filters (category AND group)
npm run start -- --category=Binary --group=Automatic
# Start only the emulated devices (for manual testing)
npm run start -- --devices-only
# Run with verbose CTT output
npm run start -- --test=CC_Binary_Switch_Set --verboseThe project comes with a ready-to-use GitHub Actions workflow for running CTT tests in CI using WSL. For now, only tests from the "Automatic" group are supported, because they don't require manual interaction.
To use the workflow, configure a repository secret named ZW_STACK_TOKEN with a GitHub PAT that has Contents: read permission for the Z-Wave-Alliance/z-wave-stack-binaries repository.
Make sure that the DUT has all command classes set (factory reset may be required) before joining the CTT network
Make sure that:
- The DUT storage contains the correct files
- The home ID is configured correctly everywhere:
config.jsonctt/project/Config/TestCaseStaticController.xml(HomeId attribute)ctt/project/Config/Saved Items/002_<HOMEID>.xml(filename)
Something in the storage is likely corrupted. Delete all stack storage files and re-create the CTT network from scratch. Make sure to update the home ID accordingly, see above.
- docs/ipc-protocol.md - DUT Runner IPC protocol specification
- CTT-Remote/CTT-Remote.md - CTT-Remote API documentation
- .github/workflows/run-zwave-wsl.yml - CI workflow configuration
MIT
For issues or questions, please open an issue in the GitHub repository.