Represents a connection to the ubus bus.
A connection is established via connect() and serves as the primary interface for all ubus operations. Through a connection, you can:
- Discover and invoke methods on remote objects (list(), call())
- Publish your own objects to the bus (publish())
- Subscribe to notifications from other objects (subscriber())
- Register event listeners for pattern-based events (listener())
- Send broadcast events to other listeners (event())
The connection uses the broker pattern, routing all communication through ubusd. It supports both synchronous (call) and asynchronous (defer) method invocations.
const conn = connect();
conn.list();
conn.call(…);
conn.defer(…);
conn.publish(…);
conn.remove(…);
conn.listener(…);
conn.subscriber(…);
conn.event(…);
conn.disconnect();
conn.error();- Source
Methods
call(object, method, dataopt, returnopt, fdopt, fd_cbopt) → {*}nullable
Invoke a ubus method synchronously.
Calls the specified method on a ubus object and waits for the response.
Returns the method response data, or an array of responses if multiple replies were received.
Returns null if the call failed.
| Name | Type | Description |
|---|---|---|
object | string | | The object name (string) or object ID (number) to call the method on. |
method | string | The name of the method to invoke. |
data | Object | (optional) Optional method arguments as an object with field names and values. |
return | string | | (optional, default: "single")Controls how multiple responses are handled: |
fd | number | (optional) Optional file descriptor to send along with the call. |
fd_cb | function | (optional) Optional callback function invoked when a file descriptor is received. |
- Source
defer(object, method, dataopt, cbopt, data_cbopt, fdopt, fd_cbopt) → {deferred}nullable
Invoke a ubus method asynchronously.
Initiates a non-blocking call to the specified method on a ubus object. The provided callback will be invoked when the response is received or on timeout.
Returns a deferred request resource representing the pending operation.
Returns null if the deferred call could not be initiated.
| Name | Type | Description |
|---|---|---|
object | string | The object name to call the method on. |
method | string | The name of the method to invoke. |
data | Object | (optional) Optional method arguments as an object with field names and values. |
cb | function | (optional) Callback function invoked when the operation completes. Receives status code and response data as arguments. |
data_cb | function | (optional) Optional callback invoked for intermediate data notifications. |
fd | number | (optional) Optional file descriptor to send along with the call. |
fd_cb | function | (optional) Optional callback function invoked when a file descriptor is received. |
// Asynchronous call with callback - typical pattern for RPC handlers
const conn = connect();
const req = conn.defer("some.object", "some_method", {}, (rc, data) => {
if (rc == 0)
printf("Result: %.J\n", data);
});// Persistent connection pattern - avoid GC by keeping reference
const ubus = connect();
function get_status(req) {
// Use persistent ubus connection for async calls
return ubus.defer("some.object", "some_method", {}, (rc, data) => {
req.reply({ result: data });
});
}- Source
disconnect() → {boolean}
Disconnect from the ubus bus.
Closes the connection to the ubus bus and releases associated resources. All pending requests are aborted.
Returns true on success.
const conn = connect();
// … do work …
conn.disconnect();- Source
error(numericopt) → {string|number}
Query ubus error information.
Returns a string containing a description of the last ubus error when the numeric argument is absent or false.
Returns a ubus status code number when the numeric argument is true.
Returns null if there is no error information.
| Name | Type | Description |
|---|---|---|
numeric | boolean | (optional) Whether to return a numeric status code ( |
- Source
event(event_type, event_dataopt) → {boolean}nullable
Send a ubus event.
Broadcasts an event of the specified type with optional data to all registered event listeners.
Returns true on success.
Returns null if the event could not be sent.
| Name | Type | Description |
|---|---|---|
event_type | string | The type string identifying the event. |
event_data | Object | (optional) Optional event data as an object with field names and values. |
const conn = connect();
conn.event("system.boot", { host: "router1", uptime: 3600 });- Source
list(object_nameopt) → {string[]}nullable
List available ubus objects.
Queries the ubus bus for registered objects. If an object name pattern is provided, returns signatures for matching objects. Otherwise, returns a list of all registered object paths.
Returns an array of object paths or object signatures.
Returns null if the list operation failed.
| Name | Type | Description |
|---|---|---|
object_name | string | (optional) Optional object name pattern to filter results. When provided, returns signatures for matching objects; otherwise returns all object paths. |
- Source
listener(pattern, cb) → {listener}nullable
Register an event listener.
Registers a callback to be invoked when events matching the specified pattern are received. The listener receives the event type and data.
Returns a listener resource that can be removed via remove().
Returns null if the listener could not be registered.
| Name | Type | Description |
|---|---|---|
pattern | string | The event type pattern to match, supporting wildcards (e.g., |
cb | function | Callback invoked when a matching event is received. Receives the event type string and event data object as arguments. |
const conn = connect();
const listener = conn.listener("system.*", (type, data) => {
printf("Event %s: %.J\n", type, data);
});- Source
publish(object_name, methodsopt, subscribe_callbackopt) → {object}nullable
Publish a ubus object on the bus.
Registers a new object with the specified name and methods on the ubus bus. The object can define method handlers and an optional subscribe callback.
Returns an object resource representing the published object.
Returns null if the object could not be registered.
| Name | Type | Description |
|---|---|---|
object_name | string | The name to register the object under. |
methods | Object | (optional) Optional object defining methods with |
subscribe_callback | function | (optional) Optional callback invoked when a subscriber connects to the object. |
const conn = connect();
const obj = conn.publish("my.service", {
"hello": {
call: (req, msg) => {
req.reply({ message: "Hello, " + msg.name });
},
args: { name: "string" }
}
});- Source
subscriber(notify_callback, remove_callback, subscription_patternsopt) → {subscriber}nullable
Register a ubus subscriber.
Creates a subscriber that can receive notifications from ubus objects. The subscriber can define notify and remove callbacks, and optional subscription patterns for automatic object discovery.
Returns a subscriber resource representing the registered subscriber.
Returns null if the subscriber could not be registered.
| Name | Type | Description |
|---|---|---|
notify_callback | function | Callback invoked when a notification is received from a subscribed object. |
remove_callback | function | Callback invoked when a subscribed object is removed from the bus. |
subscription_patterns | string[] | (optional) Optional array of glob patterns for automatic object subscription. |
const conn = connect();
const sub = conn.subscriber(
(event) => {
printf("Received: type=%s, data=%.J\n",
event.type, event.data);
},
(objid) => {
printf("Object removed: %d\n", objid);
},
["network.interface.*"] // Auto-subscribe to matching objects
);
// Subscribe to a specific object
sub.subscribe("some.object");- Source