Repository files navigation

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 orWindows Server
• WSL with Ubuntu installed
• .NET Framework 4.8 (for CTT-Remote)

In addition, the test orchestrator requires:

• Node.js 24 or later
• Thegh CLI 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-tests

npm install

Run these commands in WSL (open WSL terminal withwsl):

sudo dpkg --add-architecture i386sudo apt-get updatesudo apt-get install -y libc6:i386 libstdc++6:i386

These 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 theCTT_PATH environment variable.

powershell .\setup\download-zwave-stack.ps1

Note: This setup assumes the DUT is acontroller, 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 thezwave_stack/run.sh script accordingly.

npm run devices

Starts 6 Z-Wave binaries in WSL:

These can now be used to set up the CTT project.

1. Create a new project in CTT GUI
2. Set up 5 IP-based devices:
   • 2x Controller:127.0.0.1:5001 and:5002
   • 2x End Device:127.0.0.1:5003 and:5004
   • 1x Zniffer:127.0.0.1:4905

Configure DUT to connect totcp://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 toctt/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 (orRUNNER_IPC_PORT env var)
• Required methods:
  • ready notification (on connect)
  • start (initialize DUT with controllerUrl and security keys)
  • stop (shutdown DUT)
  • handleCttPrompt (respond to CTT prompts)

Seedut/zwave-js/run.ts for a reference implementation anddocs/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.ps1powershell .\setup\pack-network-state-archive.ps1

Both 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 thenetwork-state.zip archive instead.

To test locally, run:

npm run start -- [options]

# List all available testsnpm run start -- --discover# Run a single testnpm run start -- --test=CC_Binary_Switch_Set# Run multiple specific testsnpm 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 categorynpm 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 outputnpm run start -- --test=CC_Binary_Switch_Set --verbose

The 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 namedZW_STACK_TOKEN with a GitHub PAT that hasContents: read permission for theZ-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.json
  • ctt/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.