Custom device interface¶

The custom device interface enables access to arbitrary host devices inside the workshop, identified by the device subsystem they belong to (for example, input, tty, or usb).

By using the interface, the SDK publisher allows the workshop to access devices that no dedicated interface covers, such as serial adapters, input devices, or other peripherals used for testing hardware or embedded devices.

Custom device interface plug¶

An essential element here is the custom device interface plug, which is declared in the SDK definition.

Its structure includes the name of the plug, the interface (custom-device), and the optional subsystem, vendorid, and productid device filters. At least one of these filters must be set.

Defining the plug in an SDK allows the workshops using this SDK to connect to matching devices, which can unlock additional SDK functionality.

Device subsystems¶

The subsystem attribute for a given device is defined by the Linux kernel. One way to query device properties is udevadm info:

$ udevadm info --query=property --property=SUBSYSTEM /dev/input/event0

  SUBSYSTEM=input

Product and vendor filters¶

When a subsystem matches more devices than wanted, the optional vendorid and productid attributes narrow the selection down to devices reporting the given vendor and product ID. Both are matched against the respective identifiers reported by the kernel, which can be queried with udevadm info:

$ udevadm info --query=property --property=ID_VENDOR_ID --property=ID_MODEL_ID /dev/ttyUSB0

  ID_VENDOR_ID=0403
  ID_MODEL_ID=6001

Because a product ID is only meaningful within a vendor’s namespace, setting productid also requires vendorid.

Custom device interface slot¶

To let SDKs in a workshop access the host’s devices, Workshop provides a custom device interface slot that multiple custom device interface plugs can access.

When the SDK is installed at runtime during launch and refresh operations, Workshop checks that the plug targeting the slot passes validation; if it does, it can be connected.

Connection¶

The interface isn’t connected automatically at launch and refresh for security reasons. The workshop connect and workshop disconnect commands can be invoked manually after the workshop has started:

$ workshop connect ws/input-sdk:input-device :custom-device
$ workshop disconnect ws/input-sdk:input-device

Establishing a connection means that all existing host devices belonging to the plug’s subsystem will be made available inside the workshop. While the connection is active, adding new devices on the host will also make them available inside the workshop, whereas unplugged devices will also be removed from the workshop.

To check if the interface is connected:

$ workshop connections --all

  INTERFACE      PLUG                       SLOT                     NOTES
  ...
  custom-device  ws/input-sdk:input-device  ws/system:custom-device  manual

This means the host’s devices from the given subsystem are available inside the workshop:

$ workshop shell ws
workshop@ws-8584e571$ ls /dev/input/

  event0  event1  mice