# 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.\
 

<figure><img src="https://884329393-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MhzNRg0B4ECiNXc093G%2Fuploads%2FvlLhZc7VpiWDtePJYVbd%2FGroup%201%20(1).png?alt=media&#x26;token=97306d5d-2b8d-4357-83bb-c67789978eff" alt=""><figcaption></figcaption></figure>

## 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.&#x20;

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.&#x20;

If the *category* key is not specified in the `manifest.toml`,  the device will automatically be added to a *category* called `plugin`. &#x20;

{% hint style="warning" %}
If the *category* is specified but no value is given, the device will not be displayed.&#x20;
{% endhint %}

## Filters

*Filters* are defined within the `manifest.toml` file.  In the screenshot above, *Filters* are highlighted in magenta.&#x20;

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.

{% hint style="warning" %}
Neither *categories* nor *Filters* work as a means of filtering devices when requesting the API, it works only to categorize devices in the drawer.&#x20;
{% endhint %}

## 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 <a href="#naming-convention" id="naming-convention"></a>

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

<table><thead><tr><th width="121">Section/subsection</th><th width="115">Key</th><th width="161">Value</th><th width="157">Description</th><th>Example</th></tr></thead><tbody><tr><td>[settings]</td><td>categories</td><td>A list of strings</td><td>Each element in the list is the name of a category</td><td><p></p><pre class="language-toml"><code class="lang-toml">categories = ["End Device"]
</code></pre></td></tr><tr><td>[settings]</td><td>filters</td><td><p>A dictionary with the following schema:</p><p><br> <code>str: list</code></p></td><td>Each root key is the name of the filer and its respective values are the values corresponding to the device</td><td><p></p><pre class="language-toml"><code class="lang-toml">filters = {brand = ["Advantech"], connectivity = ["Ethernet"]}

</code></pre></td></tr></tbody></table>

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 <a href="#view.xml" id="view.xml"></a>

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

### LICENSE and README.md files

Refer to Private Plugins page to get detailed information:

{% content-ref url="" %}
[](https://dev.ubidots.com/plugins/private-plugins)
{% endcontent-ref %}

### Naming convention <a href="#naming-convention" id="naming-convention"></a>

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.