Skip to content
Domotz Custom Driver v3.0.1

Quickstart

Build a driver that pings a device and publishes the average latency as a variable.

What you need

Section titled “What you need”
  • A Domotz account with a collector already deployed.
  • A device on the same network as the collector, reachable by ICMP.
  • A text editor.

Step 1 — Driver skeleton

Section titled “Step 1 — Driver skeleton”

Create a file called ping-driver.js with two required entry points:

// validate runs once when the driver is attached to a device.
function validate() {
    D.device.ping({ count: 1 }, function (result, error) {
        if (error || !result || result.packet_loss === 100) {
            return D.failure(D.errorType.RESOURCE_UNAVAILABLE);
        }
        D.success();
    });
}


// get_status runs on every schedule tick.
function get_status() {
    // filled in below
}

Step 2 — Ping the device

Section titled “Step 2 — Ping the device”

Replace the body of get_status:

function get_status() {
    D.device.ping({ count: 5, interval: 100 }, function (result, error) {
        if (error) {
            console.error('Ping failed', error);
            return D.failure(D.errorType.RESOURCE_UNAVAILABLE);
        }
        var latency = D.createVariable(
            'latency',
            'Average latency',
            result.avg,
            'ms',
            D.valueType.NUMBER
        );
        D.success([latency]);
    });
}

D.device.ping takes a ping options object and a callback. The result contains avg, min, max, jitter, packet_loss, std, and the raw samples.

Step 3 — Upload in Domotz

Section titled “Step 3 — Upload in Domotz”
  1. Sign in to the Domotz web app.
  2. Go to Integrations → Automation & Scripts and click New Script.
  3. Give the script a name (e.g. “Ping latency”) and an optional description.
  4. Pick the type — Generic for variables/metrics, Configuration Management for backup/restore drivers. Use Generic here.
  5. Paste the contents of ping-driver.js into the editor.
  6. Select a test device and run the script against it. The collector runs validate and (on success) get_status, and the result panel shows what would be published.
  7. If the test succeeds, associate the script with the target device(s).

Step 4 — Verify the reading

Section titled “Step 4 — Verify the reading”

Open the device’s Device Details page and switch to the Scripts tab. The Ping latency → Average latency variable appears with a number in milliseconds and a historical chart.

Next steps

Section titled “Next steps”