How to Create a Custom Switchboard Device Plugin

Depending on your project's needs and the devices you are using, you may need to add or extend the device functionality in Switchboard. This page covers creating your own device plugin in Python. With some C++ knowledge, it is possible to extend the listener to accept more types of messages but this is not covered here.

The following instructions step through how to create a new device plugin, SampleDevice, for Switchboard that you can use as a starting point.

1. For the device plugin to be discoverable on load in Switchboard, you must create a folder and Python file with the naming convention <plugin_name>\plugin_<plugin_name>.py in \Engine\Plugins\VirtualProduction\Switchboard\Source\Switchboard\switchboard\devices\.
   • For the SampleDevice plugin create the following file: \Engine\Plugins\VirtualProduction\Switchboard\Source\Switchboard\switchboard\devices\sampledevice\plugin_sampledevice.py.
2. Extend the Deviceclass defined in \Engine\Plugins\VirtualProduction\Switchboard\Source\Switchboard\switchboard\devices\device_base.py in the plugin_sampledevice.py file:
   • Import Device from device_base.py.
   • Create a new class DeviceSampleDevice which inherits from Device.

   • Import LOGGER from switchboard/switchboard_logging.py to report errors.

     		
           from switchboard.devices.device_base import Device
           from switchboard.switchboard_logging import LOGGER
     
           class DeviceSampleDevice(Device):`
               def __init__(self, name, ip_address, **kwargs):
               super().__init__(name, ip_address, **kwargs)
     			
     Copy full snippet

     from switchboard.devices.device_base import Device from switchboard.switchboard_logging import LOGGER class DeviceSampleDevice(Device):` def __init__(self, name, ip_address, **kwargs): super().__init__(name, ip_address, **kwargs)

   Verify the file is discoverable by Switchboard. Launch Switchboard and expand the Add Device dropdown menu. SampleDevice appears in the list.

   
3. Adding a SampleDevice to your Switchboard won't create a widget in the view. To create a SampleDevice widget, extend DeviceWidget in plugin_sampledevice.py:
   • Import DeviceWidget from device_widget_base.py.

   • Create the new class DeviceWidgetSampleDevice which inherits from DeviceWidget.

     					
               from switchboard.devices.device_base import Device
               from switchboard.devices.device_widget_base import DeviceWidget
               from switchboard.switchboard_logging import LOGGER
     			
               class DeviceSampleDevice(Device):
                   def __init__(self, name, ip_address, **kwargs):
                       super().__init__(name, ip_address, **kwargs)
     			
               class DeviceWidgetSampleDevice(DeviceWidget):
                   def __init__(self, name, device_hash, ip_address, icons, parent=None):
                       super().__init__(name, device_hash, ip_address, icons, parent=parent)
     								
     Copy full snippet

     from switchboard.devices.device_base import Device from switchboard.devices.device_widget_base import DeviceWidget from switchboard.switchboard_logging import LOGGER class DeviceSampleDevice(Device): def __init__(self, name, ip_address, **kwargs): super().__init__(name, ip_address, **kwargs) class DeviceWidgetSampleDevice(DeviceWidget): def __init__(self, name, device_hash, ip_address, icons, parent=None): super().__init__(name, device_hash, ip_address, icons, parent=parent)

   Verify the widget appears in Switchboard. Launch Switchboard and add a SampleDevice. A minimal SampleDevice widget appears in the view.

   
4. Create a custom dialog when a new SampleDevice is added by creating a new class which inherits from AddDeviceDialog and assigning it to the static variable add_device_dialog in the DeviceSampleDevice class:
   • Import AddDeviceDialog from device_widget_base.py.
   • Import Qt modules from PySide2
   • Create a new class AddSampleDeviceDialog which inherits from AddDeviceDialog and set the device_type parameter to "SampleDevice" when calling the base class's constructor.
   • In the new class's constructor add a QLineEdit text field to the dialog.

   • Override the add_device_dialog static variable in DeviceSampleDevice with the new class.

     					
               from switchboard.devices.device_base import Device
               from switchboard.devices.device_widget_base import AddDeviceDialog, DeviceWidget
               from switchboard.switchboard_logging import LOGGER
     			
               from PySide2 import QtWidgets, QtGui, QtCore
     			
               class AddSampleDeviceDialog(AddDeviceDialog):
                   def __init__(self, existing_devices, parent=None):
                       super().__init__(device_type="SampleDevice", existing_devices=existing_devices, parent=parent)
     			
                       # Create QTWidgets to add to the form
                       self.additional_text_field = QtWidgets.QLineEdit(self)
     			
                       # Append the new options to the QTWidgets.QFormLayout object defined in the parent class
                       self.form_layout.addRow("Additional Text", self.additional_text_field)
     			
               class DeviceSampleDevice(Device):
                   # Override the add device dialog object associated with the device plugin
                   add_device_dialog = AddSampleDeviceDialog
     			
                   def __init__(self, name, ip_address, **kwargs):
                       super().__init__(name, ip_address, **kwargs)
     			
               class DeviceWidgetSampleDevice(DeviceWidget):
                   def __init__(self, name, device_hash, ip_address, icons, parent=None):
                       super().__init__(name, device_hash, ip_address, icons, parent=parent)
     			
     Copy full snippet

     from switchboard.devices.device_base import Device from switchboard.devices.device_widget_base import AddDeviceDialog, DeviceWidget from switchboard.switchboard_logging import LOGGER from PySide2 import QtWidgets, QtGui, QtCore class AddSampleDeviceDialog(AddDeviceDialog): def __init__(self, existing_devices, parent=None): super().__init__(device_type="SampleDevice", existing_devices=existing_devices, parent=parent) # Create QTWidgets to add to the form self.additional_text_field = QtWidgets.QLineEdit(self) # Append the new options to the QTWidgets.QFormLayout object defined in the parent class self.form_layout.addRow("Additional Text", self.additional_text_field) class DeviceSampleDevice(Device): # Override the add device dialog object associated with the device plugin add_device_dialog = AddSampleDeviceDialog def __init__(self, name, ip_address, **kwargs): super().__init__(name, ip_address, **kwargs) class DeviceWidgetSampleDevice(DeviceWidget): def __init__(self, name, device_hash, ip_address, icons, parent=None): super().__init__(name, device_hash, ip_address, icons, parent=parent)

   Verify the new device dialog appears in Switchboard. Launch Switchboard and add a SampleDevice. The additional text field appears in the dialog.

   
5. Devices can also have a widget on the right side of Switchboard, tabbed with other extension dialogs, to share more information. To create this tab, override the classmethod plug_into_ui from the Device base class.
   • Create a new class SampleDeviceTabView which inherits from QtWidgets.QWidget.
   • Create the class member tab_view in DeviceSampleDevice to hold the instance of the widget.

   • Override the classmethod plug_into_ui in DeviceSampleDevice and initialize tab_view with the new class SampleDeviceTabView.

     					
               from switchboard.devices.device_base import Device
               from switchboard.devices.device_widget_base import AddDeviceDialog, DeviceWidget
               from switchboard.switchboard_logging import LOGGER
     			
               from PySide2 import QtWidgets, QtGui, QtCore
     			
               class AddSampleDeviceDialog(AddDeviceDialog):
                   def __init__(self, existing_devices, parent=None):
                       super().__init__(device_type="SampleDevice", existing_devices=existing_devices, parent=parent)
     			
                       # Create QTWidgets to add to the form
                       self.additional_text_field = QtWidgets.QLineEdit(self)
     			
                       # Append the new options to the QTWidgets.QFormLayout self.form_layout object defined in the parent class
                       self.form_layout.addRow("Additional Text", self.additional_text_field)
     			
               class DeviceSampleDevice(Device):
                   add_device_dialog = AddSampleDeviceDialog # Override the default dialog for the plugin
                   tab_view = None
     			
                   def __init__(self, name, ip_address, **kwargs):
                       super().__init__(name, ip_address, **kwargs)
     			
                   @classmethod
                   def plug_into_ui(cls, menubar, tabs):
                       ''' Implementation of base class function that allows plugin to inject UI elements.
                       '''
     			
                       if not cls.tab_view:
                           cls.tab_view = SampleDeviceTabView(parent=tabs)
     			
                       tabs.addTab(cls.tab_view, 'SampleDevice Tab')
     			
               class DeviceWidgetSampleDevice(DeviceWidget):
                   def __init__(self, name, device_hash, ip_address, icons, parent=None):
                       super().__init__(name, device_hash, ip_address, icons, parent=parent)
     			
               class SampleDeviceTabView(QtWidgets.QWidget):
                   def __init__(self, parent):
                       QtWidgets.QWidget.__init__(self, parent)
     								
     Copy full snippet

     from switchboard.devices.device_base import Device from switchboard.devices.device_widget_base import AddDeviceDialog, DeviceWidget from switchboard.switchboard_logging import LOGGER from PySide2 import QtWidgets, QtGui, QtCore class AddSampleDeviceDialog(AddDeviceDialog): def __init__(self, existing_devices, parent=None): super().__init__(device_type="SampleDevice", existing_devices=existing_devices, parent=parent) # Create QTWidgets to add to the form self.additional_text_field = QtWidgets.QLineEdit(self) # Append the new options to the QTWidgets.QFormLayout self.form_layout object defined in the parent class self.form_layout.addRow("Additional Text", self.additional_text_field) class DeviceSampleDevice(Device): add_device_dialog = AddSampleDeviceDialog # Override the default dialog for the plugin tab_view = None def __init__(self, name, ip_address, **kwargs): super().__init__(name, ip_address, **kwargs) @classmethod def plug_into_ui(cls, menubar, tabs): ''' Implementation of base class function that allows plugin to inject UI elements. ''' if not cls.tab_view: cls.tab_view = SampleDeviceTabView(parent=tabs) tabs.addTab(cls.tab_view, 'SampleDevice Tab') class DeviceWidgetSampleDevice(DeviceWidget): def __init__(self, name, device_hash, ip_address, icons, parent=None): super().__init__(name, device_hash, ip_address, icons, parent=parent) class SampleDeviceTabView(QtWidgets.QWidget): def __init__(self, parent): QtWidgets.QWidget.__init__(self, parent)
   

These steps showed how to create a new device plugin for Switchboard. For an advanced example, see the nDisplay device plugin for Switchboard.