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

Custom Driver screenshot 2

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 associated to “buttons” when the driver is associated to the device:

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

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

Custom Driver screenshot  5

Step 3 Select a function to execute. You have two choices

  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:

Custom Driver screenshot 6

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?

Step 1 Go to a device of your choice and select “Apply driver to this device”:

Step 2 Select the driver that you want to apply to this device

Note:
Only one driver can be applied 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 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.

Updated on August 24, 2022

Was this article helpful?