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:
- How to create a Driver?
- Example Drivers
- How to test a Driver?
- Custom driver table variables
- How to use a Driver?
- How to Download CSV for Drivers Tables:
- Failed Drivers
How to create a Driver?
Step 1 Go to Integrations > Custom Integrations
Step 2 Click on Create a New Driver
Step 3 Enter driver properties and 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.
If you want to see a few examples of Drivers built by the Domotz team which you can use to build your own 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 firstname.lastname@example.org 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.
- 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
Step 5 Checking the result
A pop-up will appear with the code run execution result for the specified function. You have two choices:
- get_status is the function name that was executed
- 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?
Go on the page of the device you would like to apply the driver to and click on “Apply Drivers to Device”:
Go on the page of the device you would like to apply the driver to and click on select “Manage Device Drivers” or click on the “Drivers” tab button:
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.
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.
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.