Heads up! New Developer Preview programs are rolling out soon. Apply here and be one of the first to try new tools and provide feedback.

Virtual Device Controller

Device SDK

The Virtual Device Controller is a desktop app that provides a graphical user interface to control and display the states of your virtual Matter devices. The app provides a visual representation of your virtual device, as well as the controls for the Matter clusters supported by the device.

The app uses an RPC client to communicate with the virtual device's RPC server, sending requests reflecting your actions (toggle power, dim, brighten) and polling once every second to retrieve state.

Supported devices

Currently, the Virtual Device Controller supports the following Matter device types:

Matter Device Type Application Cluster(s) Home Ecosystem Type
Contact Sensor Boolean State Sensor
Dimmable Light On/Off
Level Control
Extended Color Light On/Off
Level Control
Color Control
Flow Sensor Flow Measurement Sensor
Humidity Sensor Relative Humidity Measurement Sensor
Illuminance Sensor Illuminance Measurement Sensor
Occupancy Sensor Occupancy Sensing Sensor
On/Off Light On/Off Light
Outlet On/Off
Level Control
Pressure Sensor Pressure Measurement Sensor
Speaker On/Off
Level Control
Switch On/Off Switch
Temperature Sensor Temperature Measurement Sensor

Set up the Virtual Device Controller

The Virtual Device Controller is provided as part of a preconfigured Docker image available on the Docker Hub. To install it, run:

user@host> docker pull us-docker.pkg.dev/nest-matter/docker-repo/virtual-device-image:latest

This operation might take a few minutes to complete.

Run the Virtual Device Controller

  1. Start the Docker container:

    user@host> xhost local:1000
    user@host> docker run -it --ipc=host --net=host -e DISPLAY --name matter-container us-docker.pkg.dev/nest-matter/docker-repo/virtual-device-image:latest

    After starting the container, you should see some diagnostic output followed by a message affirming that your container configuration is correct, and finally, the container shell prompt:

    Environment looks good, you are ready to go!
  2. Create a second terminal session instance:

    user@host> docker exec -it matter-container /bin/bash
  3. For a virtual Matter device, once the device is running, start the Virtual Device Controller, passing it the --s argument and the IP port used by the device:

    $ electron main.js --s=localhost:33000

    For a physical device, start the Virtual Device Controller, passing it the --d argument followed by the device serial port:

    $ electron main.js --d=/dev/ttyUSB0

If you start the Controller without providing any arguments, it will default to the network socket option using localhost port 33000.

Once the Controller is able to connect to your device, it will display a screen showing your device state:

Virtual Device graphic user interface

Display the device's QR code

The Virtual Device Controller app can also be used to retrieve the QR code as part of your device commissioning flow. Click on the QR code icon next to the device image to display the QR code for this device:

Virtual Device Controller displaying the device's QR Code

You can use this QR code to commission your device.

Stop the Virtual Device Controller

To stop the Virtual Device Controller, press Control-Q with the Controller's screen in focus, or press Control-C in the terminal session where you started the app.


To submit your thoughts or feedback on how we can improve your experience with the Virtual Device Controller, complete our Feedback Form.

Send us your feedback