Skip to content
Domotz Custom Driver v3.1.0

Device info

Read the target device’s IP, credentials, hostname, and metadata, or ping it.

D.device.ip

Section titled “D.device.ip”

Returns the IP address of the device object.

Signature

D.device.ip()

Returns

  • string

Example

// returns '192.168.1.1' for a device with this local IP address
D.device.ip()

D.device.macAddress

Section titled “D.device.macAddress”

Returns the MAC address of the device object.

Signature

D.device.macAddress()

Returns

  • string

Example

// returns '00:11:22:33:44:AA' for a device
D.device.macAddress()

D.device.mtr

Section titled “D.device.mtr”

Runs an MTR measurement of the network path to the device’s IP address.

MTR combines traceroute and ping: it discovers each hop on the path to the device and, for every hop, reports packet loss, round-trip time and jitter.

Signature

D.device.mtr([options], callback)

Parameters

options · `object` · optional
The options for the MTR measurement.
options.cycles · `number` · optional, default `10`
The number of measurement cycles (probes sent to each hop). Integer 1–100.
options.max_hops · `number` · optional
The maximum number of hops to probe (TTL ceiling). Integer 1–255.
options.first_hop · `number` · optional
The first hop (TTL) to start probing from. Integer 1–255.
options.interval · `number` · optional
The minimum duration of each probe round, in seconds. 0.1–60.
options.packet_size · `number` · optional, default `84`
The size of each probe packet, in bytes. Integer 28–1500.
options.protocol · `string` · optional, default `ICMP`
The probe protocol: `ICMP`, `UDP` or `TCP`.
options.port · `number` · optional
The target port for `UDP`/`TCP` probes. Integer 1–65535.
options.tos · `number` · optional
The IP Type-of-Service / DSCP byte. Integer 0–255.
callback · `function`
The callback function to handle the MTR result.
callback.result · `object` | `null` · optional
The result of the measurement, or `null` if an error occurred. Contains the following fields:
callback.result.target · `string`
The IP address that was traced (the device's IP).
callback.result.protocol · `string`
The probe protocol used.
callback.result.cycles · `number`
The number of cycles run.
callback.result.packet_size · `number`
The probe packet size, in bytes.
callback.result.hop_count · `number`
The number of hops on the path.
callback.result.elapsed_ms · `number` | `null`
The total measurement time, in milliseconds.
callback.result.hops · `Array.`
One entry per hop, ordered from the first hop to the device. Each hop contains:
callback.result.hops[].ttl · `number`
The hop's TTL (its distance from the collector).
callback.result.hops[].host · `string` | `null`
The hop's IP address, or `null` for an unresponsive ("blind") hop.
callback.result.hops[].hostname · `string` | `null`
The hop's resolved hostname, or `null`.
callback.result.hops[].hosts · `Array.`
All addresses that answered at this hop (`{ ip, hostname }`); more than one indicates load balancing (ECMP).
callback.result.hops[].loss_percent · `number`
The packet loss at this hop, as a percentage.
callback.result.hops[].sent · `number`
The number of probes sent to this hop.
callback.result.hops[].received · `number`
The number of probes answered by this hop.
callback.result.hops[].dropped · `number`
The number of probes with no reply (`sent - received`).
callback.result.hops[].rtt · `object` | `null`
Round-trip-time statistics in milliseconds, or `null` for a blind hop. Fields: `last`, `avg`, `best`, `worst`, `stddev`.
callback.result.hops[].jitter · `object` | `null`
Jitter statistics in milliseconds, or `null` for a blind hop. Fields: `last`, `avg`, `max`, `interval`.
callback.result.hops[].tos · `number` | `null`
The Type-of-Service byte observed at this hop, or `null`.
callback.result.hops[].extensions · `Array` | `null`
ICMP extensions (e.g. MPLS), or `null` if none.
callback.error · `Error` | `null` · optional
The error object if the measurement failed, or `null` if successful.

Returns

  • void

Example

D.device.mtr({ cycles: 10 }, function (result, error) {
    if (error) {
        console.error('MTR failed:', error);
        return;
    }
    var destination = result.hops[result.hops.length - 1];
    console.log('Hops:', result.hop_count, '- destination loss:', destination.loss_percent);
});

D.device.password

Section titled “D.device.password”

Returns the stored password of a device.

Signature

D.device.password()

Returns

  • string

Example

// returns 'the device password'
D.device.password()

D.device.ping

Section titled “D.device.ping”

Executes a ping operation to the device’s IP address.

Signature

D.device.ping(pingOptions, callback)

Parameters

pingOptions · `object`
The options for the ping operation.
pingOptions.count · `number` · optional, default `10`
The number of ICMP requests to send.
pingOptions.interval · `number` · optional, default `100`
The interval (in ms) between ICMP requests.
pingOptions.timeout · `number` · optional, default `1000`
The timeout (in ms) for each ICMP request.
pingOptions.packet_size · `number` · optional, default `16`
The size of the ICMP packet in bytes.
pingOptions.ttl · `number` · optional, default `64`
The Time-To-Live (TTL) value for the ICMP packets.
callback · `function`
The callback function to handle the ping result.
callback.result · `object` | `null` · optional
The result of the ping operation, or `null` if an error occurred. Contains the following fields:
callback.result.jitter · `number`
The jitter in milliseconds.
callback.result.avg · `number`
The average latency in milliseconds.
callback.result.packet_loss · `number`
The packet loss percentage.
callback.result.min · `number`
The minimum latency in milliseconds.
callback.result.max · `number`
The maximum latency in milliseconds.
callback.result.std · `number`
The standard deviation of latency in milliseconds.
callback.result.samples · `array`
The raw samples, in milliseconds.
callback.error · `Error` | `null` · optional
The error object if the ping operation failed, or `null` if successful.

Returns

  • void

Example

D.device.ping({ count: 5, interval: 100 }, function (result, error) {
    if (error) {
        console.error('Ping failed:', error);
    } else {
        console.log('Ping result:', result.avg);
    }
});

D.device.serial

Section titled “D.device.serial”

Returns the serial number of the device object.

Signature

D.device.serial()

Returns

  • string

Example

// returns 'serial_number' for a device
D.device.serial()

D.device.username

Section titled “D.device.username”

Returns stored username of a device.

Signature

D.device.username()

Returns

  • string

Example

// returns 'the device username'
D.device.username()