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	Light
Extended Color Light	On/Off Level Control Color Control	Light
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	Outlet
Pressure Sensor	Pressure Measurement	Sensor
Speaker	On/Off Level Control	Speaker
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:

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:

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.

Feedback

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