Custom Integration Drivers

Introduction

The Custom Integration feature allows you to create drivers that can be used on IP-connected devices to retrieve additional data and execute actions on them.

Supported network protocols:

• HTTP
• SSH
• Telnet
• SNMP
• TCP

Note: We are continuously developing support for additional protocols, which will be enabled soon including winRM, TCP, etc.

Current limitations:

Missing protocols

• Winrm

How to create a Driver?

Step 1 Go to Integrations >  Custom Integrations

Step 2 Click on Create a New Driver

Note: Be aware that the chosen driver name must be unique.

Step 3 Enter driver properties and code

Note: Please visit the official Driver API Documentation to learn how to write domotz drivers’ code.

Step 4 Add additional Custom Actions

By using the “Add Actions” button, it is possible to create user defined “actions/functions”:

And these can be executed by assigning the driver to the device and selecting the proper Custom function:

In the above example, the custom_1 action is associated to the device and sets the SNMP variable sysName to “Change Me Once”.

After assigning the custom_1 action to the device, you can see it in the “Drivers” tab of your device and execute the function by clicking on the “Execute Action” botton:

Expandable descriptions are also available for your Custom action under “Drivers” tab of your device.

Example Drivers

A few examples of Drivers can be used for the following devices:

edge_os_get_dhcp_leases.js

• This Driver extracts the DHCP Lease information for Ubiquiti EdgeOS Routers.
• Communication protocol is HTTPS.
• Creates a dynamic number of driver variables based on the number of DHCP IP addresses.

esxi_get_users.js

• This Driver extracts the users in the VMWare ESXi system and store them as driver variables.
• Communication protocol is SSH.

esxi_last_login.js

• This Driver extracts the Last Login line for an VMWare ESXi system.
• Communication protocol is SSH.

esxi_ntp_configuration.js

• This Driver extracts the NTP configuration for an VMWare ESXI system.
• Communication protocol is SSH.

niveo_get_switch_port_temperature

• This Driver extracts temperature readings for the ports of a Niveo Switch.
• Communication protocol is Telnet with negotiation.
• Creates multiple driver variables for each of the switch’s ports.

iq4e_sensors.js

• This Driver extracts Sensor Values out of a Honeywell Trend Controllers (IQ4E).
• Communication protocol is HTTP without authentication.
• The extraction of values is based on a HTML parsing mechanism.
• Creates a dynamic number of driver variables based on the number of sensor items.

cisco_reboot.js

• This Driver Collects System uptime for a Cisco device and stores it in a driver variable.
• Communication protocol is SNMP
• This driver shows the usage of Custom Actions. In particular, a custom action function is exposed by this driver that allows the reboot of a Cisco device with “snmp-server system-shutdown” configuration set.

For more information, please visit the list of all examples available on GitHub. Domotz will continue to add more and more examples in this section. Feel free to reach out to support@domotz.com if you have any suggestions.

How to test a Driver?

You can validate the code of a driver by executing it against a device of your choice.

Step 1 Open the Driver Details section

Step 2 Select a Device for the Driver

Step 3 Select a function to execute.

1. Validate is designed to verify if the device that you apply a driver to can support the driver’s functionality. To clarify, the function will be executed and depending on the result it will allow or prevent the driver to device association:

• The D.success() callback indicates the device is a valid candidate for the driver.

• The D.failure(D.errorType.DEVICE_NOT_SUPPORTED) callback indicates that this driver’s functionality is not supported on the selected device.

2. Get_status and Run Code:

Then select the device you want to run the driver on:

Step 4 Run function code:

Step 4.1 If Credentials Required

Note: If you have selected any driver to use credentials, a pop-up will appear before executing the code in order to insert the device’s credentials. If you type wrong credentials no code execution will be performed. Please, make sure you present the correct set of credentials for the selected device. Using the save credentials option is recommended.

Step 5 Checking the result

A pop-up will appear with the code run execution result for the specified function. You have two choices:

1. get_status is the function name that was executed
2. Variables is the section that contains a list of variable name-value pairs
   – “this is an example label” is the name we’ve given the variable
   – “this is an example value” is its value

You can also add logging to your driver:

And after running the code you will be able to access it under the Log tab:

Custom driver table variables

Now, you can also create table variables where each record is a demonstration of various key/value pairs. You can basically insert records and insert the unique identifier of the row, which in this case is the Docker container ID, then you just insert for each column your defined value.

How to define Driver Table, you can follow the link: https://portal.domotz.com/custom-driver/driverTable.html

To see an example of custom driver table variables: https://github.com/domotz/custom-driver/blob/master/examples/ssh/docker_stats.js

How to use a Driver?

If no drivers were assigned to the device:

Step 1

Go to a device of your choice and select “Apply Drivers to Device”:

If you did assign any drivers to the device:

Step 1

Go to a device of your choice and select “Manage Device Drivers”:

Step 2

Select the driver that you want to apply to this device. To filter your Drivers list, check the boxes ” Already associated to a device” or ” Valid Code”, or both.

Note:
You can apply more than one driver to a single device.
Be aware that the chosen driver must have a valid code.

Note: When associating a driver to a device that requires credentials, please provide the correct credentials for this device.

The Drivers Label appears after assigning a driver to a single device:

When multiple Drivers are associated with a single device, the Drivers Label would seem:

Agent Variable Consumption

The Agent’s variable consumption box shown on the Devices list screen indicates the number of driver variables consumed by the particular Agent:

By clicking on the highlighted above section, you will be able to access the Manage Drivers section where you can see which devices are consuming variables:

Step 3 Driver configuration

Go to the Driver tab and find your driver configuration (sample period) and results:

A historical view of the variable value changes is available by clicking under its value cell:

Step 3.1 Driver Table variables

If you set up a driver table variable, you will be able to see the perspective columns you specified in the driver.

How to Download CSV for Drivers Tables:

Select your device from the Device List, and then, on the Driver tab of your device with custom integrations, click the “Download CSV” link to download a CSV of a driver table.

Failed Drivers

If one or more drivers are in the “Failed” status, you will see an informative banner in the “Total Custom Integrations Variables” section stating “One or more Custom Integrations have stopped working”.

By clicking on the banner, you will be able to access the Manage Drivers section, where you can see a list of devices for which the Custom Integratione has been stopped.

Note: The failed drivers are easily visible under the “Drivers” tab of your selected device.