Device

Definition

A private device plugin allows Ubidots developers to create custom devices with a native Ubidots experience. However, unlike Ubidots' native devices, these plugins offer the flexibility to define custom categories and filters, providing greater control over how the device appears in the devices drawer.

Categories

Categories are set in the manifest.toml file and are the primary method for cataloging a Device plugin. In the screenshot, categories are highlighted in red.

Each Device plugin can define its own categories, so the Devices drawer will show as many categories as defined for each device. If multiple devices share the same category, said category will only be displayed once in the drawer, grouping together all devices that define that category.

For example in the screenshot above, both devices define the End Device category. At the same time, the ALTA Device also defines the Industrial Gateway category, thus in total, there are two different categories defined that will be displayed in the drawer:

• End Device

• Industrial Gateway

Note from the screenshot above, that the ALTA device is shown within two categories, namely End Device and Industrial Gateway, this is because a device can be owned by multiple categories at the same time.

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

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

Filters

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

This is the second means of categorization for devices and allows user-customizable filter definitions. These filters are built via a set of key-value pairs of settings, where the value consists of a list of strings.

Neither categories nor Filters work as a means of filtering devices when requesting the API, it works only to categorize devices in the drawer.

Required files

As stated before any Private plugin regardless of its type, and, particularly, a private device plugin, is composed by the file structure shown below:

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

manifest.toml

Aside from previously mentioned manifest components common to all plugin types, the following ones are specific to Device type plugin:

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 filer and its respective values are the values corresponding to the device	filters = {brand = ["Advantech"], connectivity = ["Ethernet"]}

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

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

Though this file is only relevant when using Cron and Webhook type plugins, it still must contain valid placeholder data to deploy the plugin.

LICENSE and README.md files

Refer to Private Plugins page to get detailed information:

pagePrivate Plugins

Naming convention

You ought to retain the names of all files and directories mentioned in the previous section, as the plugins engine specifically searches for these files and their extensions.