Device

Definition

A private device plugin lets Ubidots developers create custom devices with a native Ubidots experience. Unlike Ubidots native devices, these plugins let you define custom categories and filters. This gives you more control over how the device appears in the Devices drawer.

Categories

Categories are set in the manifest.toml file and are the primary way to classify a Device plugin. In the screenshot above, categories are highlighted in red.

Each Device plugin can define its own categories, so the Devices drawer shows every category defined across your devices. If multiple devices share the same category, that category is displayed only once in the drawer and groups together all devices that define it.

For example, in the screenshot above, both devices define the End Device category. The ALTA device also defines the Industrial Gateway category. As a result, the drawer displays two categories:

• End Device

• Industrial Gateway

In the screenshot above, the ALTA device appears under two categories — End Device and Industrial Gateway — because a device can belong to multiple categories at the same time.

If the categories key is not specified in the manifest.toml file, the device is automatically added to a category called plugin.

If categories is specified but no value is given, the device will not be displayed.

Filters

Filters are defined in the manifest.toml file. In the screenshot above, filters are highlighted in magenta.

This is the second way to classify devices and lets users define custom filters. These filters are built as key-value settings, where each value is a list of strings.

Neither categories nor filters can be used to filter devices in API requests. They only categorize devices in the drawer.

Required files

As explained earlier, any private plugin, including a private device plugin, uses the file structure shown below:

├── src           
│   ├── view.xml           
├── LICENSE
├── README.md
├── manifest.toml

manifest.toml

Aside from the manifest components shared by all plugin types, the following keys are specific to Device plugins:

Section/subsection	Key	Value	Description	Example
[settings]	categories	A list of strings	Each element in the list is the name of a category.	categories = ["End Device"]
[settings]	filters	A dictionary with the following schema: str: list	Each root key is the name of the filter, and its respective values are assigned to the device.	filters = {brand = ["Advantech"], connectivity = ["Ethernet"]}

With this in mind, a typical device plugin manifest file looks like this:

manifest_version = 2.0

[settings]
version = "0.0.1"
plugin_type = "device"
license_name = "MIT license"
categories = ["End Device"]
filters = {brand = ["Advantech"], connectivity = ["Ethernet"]}

view.xml

This file is not currently used by Device plugins, but it must still contain valid placeholder data so the plugin can be deployed.

LICENSE and README.md files

For more details, see Private Plugins.

Naming convention

Keep the names of all files and directories mentioned in the previous section. The plugins engine looks specifically for those files and their extensions.