dbus

The dbus module provides Linux-only D-Bus APIs for JSH applications. It supports method calls, property access, introspection, signal subscription, and name-owner watching.

Module load

const dbus = require("dbus");
const conn = new dbus.Connection({ busType: dbus.BusType.Session });

If the runtime OS is not Linux, creating a connection fails.

BusType

• dbus.BusType.Session
• dbus.BusType.System

Connection

D-Bus connection object.

Creation

new dbus.Connection(options)

Options

Return value

• Connection

Error behavior:

• Throws when busType is invalid.
• Throws when the platform is not Linux.

close()

Closes the current D-Bus connection.

Syntax

conn.close()

Return value

• undefined

This method is idempotent and can be called more than once.

object()

Creates an ObjectProxy bound to destination/path.

Syntax

conn.object(destination, path)

Parameters

• destination (string): Service name (for example, org.freedesktop.DBus)
• path (string): Object path (for example, /org/freedesktop/DBus)

Return value

• ObjectProxy

call()

Calls a D-Bus method.

Syntax

conn.call(request)

Parameters

• request (object): CallRequest

Return value

• object: CallResult

Error behavior:

• Throws when required fields are missing.
• Throws when the object path is invalid.

getProperty()

Reads a D-Bus property.

Syntax

conn.getProperty(request)

Parameters

• request (object): PropertyRequest

Return value

• object: PropertyResult

setProperty()

Writes a D-Bus property.

Syntax

conn.setProperty(request)

Parameters

• request (object): SetPropertyRequest

Return value

• undefined

introspect()

Gets introspection metadata for an object.

Syntax

conn.introspect(request)

Parameters

• request (object): IntrospectRequest

Return value

• object: IntrospectionNode

subscribeSignal()

Subscribes to D-Bus signals matching criteria.

Syntax

conn.subscribeSignal(request)

Parameters

• request (object): SignalWatchRequest

Return value

• Connection (for chaining)

Error behavior:

• Throws missing signal match criteria when all match fields are empty.

unsubscribeSignal()

Unsubscribes a previously registered signal match.

Syntax

conn.unsubscribeSignal(request)

Parameters

• request (object): SignalWatchRequest

Return value

• Connection (for chaining)

Error behavior:

• Throws when no matching subscription exists.

watchName()

Starts watching owner changes for a bus name.

Syntax

conn.watchName(name)

Parameters

• name (string): D-Bus well-known name

Return value

• Connection (for chaining)

unwatchName()

Stops watching owner changes for a bus name.

Syntax

conn.unwatchName(name)

Parameters

• name (string): D-Bus well-known name

Return value

• Connection (for chaining)

Error behavior:

• Throws name watch not found when there is no active watch for the name.

getNameOwner()

Gets the current owner for a bus name.

Syntax

conn.getNameOwner(name)

Parameters

• name (string): D-Bus well-known name

Return value

• object: NameOwnerResult

If the name has no owner, this method does not throw and returns hasOwner: false.

Events

Connection extends EventEmitter.

signal

Emitted on every subscribed D-Bus signal.

conn.on("signal", (sig) => {
    console.println(sig.interface, sig.member, sig.body);
});

name-owner-changed

Emitted when a watched name changes owner.

conn.on("name-owner-changed", (evt) => {
    console.println(evt.name, evt.oldOwner, evt.newOwner);
});

ObjectProxy

Created with conn.object(destination, path).

call()

obj.call(method, ...args)

• Returns: same shape as CallResult

getProperty() / get()

obj.getProperty(name, interfaceName)
obj.get(name, interfaceName)

• getProperty() returns PropertyResult
• get() returns the property value only (result.value)

setProperty() / set()

obj.setProperty(name, value, interfaceName)
obj.set(name, value, interfaceName)

introspect()

obj.introspect()

• Returns: IntrospectionNode

subscribeSignal() / unsubscribeSignal()

obj.subscribeSignal(member, interfaceName)
obj.unsubscribeSignal(member, interfaceName)

These are convenience wrappers that pass destination/path automatically.

Request/response structures

CallRequest

CallResult

PropertyRequest

PropertyResult

SetPropertyRequest

IntrospectRequest

IntrospectionNode

Each interface includes methods/signals/properties/annotations.

SignalWatchRequest

At least one of sender, path, interface, member must be provided.

NameOwnerResult

Usage examples

1) Basic method call

1
2
3
4
5
6
7
8
9

const dbus = require("dbus");

const conn = new dbus.Connection();
const obj = conn.object("com.plc.manufacture.Service", "/com/plc/device0");

const temp = obj.call("com.plc.manufacture.Interval.GetTemperature");
console.println("temperature:", temp.body[0]);

conn.close();

2) Property read and write

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

const dbus = require("dbus");

const conn = new dbus.Connection();
const dev = conn.object("com.plc.manufacture.Service", "/com/plc/device0");

console.println("mode:", dev.get("Mode", "com.plc.manufacture.Status"));
dev.set("Mode", "MANUAL", "com.plc.manufacture.Status");
console.println("mode:", dev.get("Mode", "com.plc.manufacture.Status"));

conn.close();

3) Introspection

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

const dbus = require("dbus");

const conn = new dbus.Connection();
const obj = conn.object("com.plc.manufacture.Service", "/com/plc/device0");
const node = obj.introspect();

for (const iface of node.interfaces) {
    console.println("iface:", iface.name);
}

conn.close();

4) Signal subscription

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

const dbus = require("dbus");

const conn = new dbus.Connection();
const obj = conn.object("com.plc.manufacture.Service", "/com/plc/device0");

obj.subscribeSignal("TemperatureChanged", "com.plc.manufacture.Interval");
conn.on("signal", (sig) => {
    if (sig.member !== "TemperatureChanged") {
        return;
    }
    console.println("temperature changed:", sig.body[0]);
});

5) Name watch

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

const dbus = require("dbus");

const conn = new dbus.Connection();
const name = "com.example.Worker";

const owner = conn.getNameOwner(name);
console.println("has owner:", owner.hasOwner);

conn.watchName(name);
conn.on("name-owner-changed", (evt) => {
    if (evt.name === name) {
        console.println("owner changed:", evt.oldOwner, "->", evt.newOwner);
    }
});

Error behavior notes

• Calling methods after conn.close() throws connection not initialized.
• Missing required fields in request objects throws an error.
• Invalid object paths throw an error.
• getNameOwner() returns { hasOwner: false } when the name exists but has no owner.
• D-Bus tests and runtime behavior are Linux-only.