Module eco.ubus

UBus support.

This module provides bindings to OpenWrt's ubus IPC system via libubus.

Note: connecting to ubus requires root privileges in this implementation.

Functions

call (object, method[, params[, timeout]]) Call a ubus method (one-shot connection).
send (event[, params]) Send an ubus event (one-shot connection).
objects () List ubus objects (one-shot connection).
signatures (object) Get the signatures of an ubus object (one-shot connection).
connect ([path[, auto_reconnect=false]]) Connect to ubus.

Fields

STATUS_OK Return status: success.
STATUS_INVALID_COMMAND Return status: invalid command.
STATUS_INVALID_ARGUMENT Return status: invalid argument.
STATUS_METHOD_NOT_FOUND Return status: method not found.
STATUS_NOT_FOUND Return status: object not found.
STATUS_NO_DATA Return status: no data.
STATUS_PERMISSION_DENIED Return status: permission denied.
STATUS_TIMEOUT Return status: timeout.
STATUS_NOT_SUPPORTED Return status: not supported.
STATUS_UNKNOWN_ERROR Return status: unknown error.
STATUS_CONNECTION_FAILED Return status: connection failed.
ARRAY Blob message policy type: array.
TABLE Blob message policy type: table.
STRING Blob message policy type: string.
INT64 Blob message policy type: int64.
INT32 Blob message policy type: int32.
INT16 Blob message policy type: int16.
INT8 Blob message policy type: int8.
DOUBLE Blob message policy type: double.
BOOLEAN Blob message policy type: boolean.

Class connection

connection:close () Close the connection.
connection:call (object, method[, params[, timeout]]) Call an ubus method using an existing connection.
connection:send (event[, params]) Send an ubus event.
connection:reply (req[, msg]) Reply to a request.
connection:listen (event, cb) Listen to ubus events.
connection:add (object, defs) Add a ubus object with method handlers.
connection:subscribe (path, cb[, auto=false]) Subscribe to notifications of an ubus object.
connection:unsubscribe (subscriber) Unsubscribe from an ubus object notifications.
connection:notify (object, method[, params]) Send a notification from an object.
connection:objects () List ubus objects.
connection:signatures (object) Get the signatures of an ubus object.


Functions

call (object, method[, params[, timeout]])
Call a ubus method (one-shot connection).

This helper creates a temporary connection (via eco.ubus.connect), performs a call and closes the connection automatically.

Parameters:

  • object string UBus object path (e.g. 'network.interface.lan').
  • method string Method name.
  • params table Parameters table. (optional)
  • timeout number Timeout in seconds. (optional)

Returns:

    table Result table.

Or

  1. nil On failure.
  2. string Error message.

Usage:

    local ubus = require 'eco.ubus'
local res, err = ubus.call('eco', 'echo', { text = 'hello' }, 3)
if not res then
    print('call failed:', err)
else
    print(res.text)
end
send (event[, params])
Send an ubus event (one-shot connection).

This helper creates a temporary connection (via eco.ubus.connect), sends the event and closes the connection automatically.

Parameters:

  • event string Event name.
  • params table Event payload. (optional)

Returns:

    boolean true On success.

Or

  1. nil On failure.
  2. string Error message.
objects ()
List ubus objects (one-shot connection).

Returns:

    table objects A map of id -> path.

Or

  1. nil On failure.
  2. string Error message.
signatures (object)
Get the signatures of an ubus object (one-shot connection).

Parameters:

  • object string UBus object path.

Returns:

    table signatures

Or

  1. nil On failure.
  2. string Error message.
connect ([path[, auto_reconnect=false]])
Connect to ubus.

This creates a connection object and starts a background coroutine to dispatch events and call replies.

Note: this implementation requires root privileges.

Parameters:

  • path string UBus socket path. (optional)
  • auto_reconnect boolean Automatically reconnect when connection is lost. (default false)

Returns:

    connection

Or

  1. nil On failure.
  2. string Error message.

Fields

STATUS_OK
Return status: success.
STATUS_INVALID_COMMAND
Return status: invalid command.
STATUS_INVALID_ARGUMENT
Return status: invalid argument.
STATUS_METHOD_NOT_FOUND
Return status: method not found.
STATUS_NOT_FOUND
Return status: object not found.
STATUS_NO_DATA
Return status: no data.
STATUS_PERMISSION_DENIED
Return status: permission denied.
STATUS_TIMEOUT
Return status: timeout.
STATUS_NOT_SUPPORTED
Return status: not supported.
STATUS_UNKNOWN_ERROR
Return status: unknown error.
STATUS_CONNECTION_FAILED
Return status: connection failed.
ARRAY
Blob message policy type: array.
TABLE
Blob message policy type: table.
STRING
Blob message policy type: string.
INT64
Blob message policy type: int64.
INT32
Blob message policy type: int32.
INT16
Blob message policy type: int16.
INT8
Blob message policy type: int8.
DOUBLE
Blob message policy type: double.
BOOLEAN
Blob message policy type: boolean.

Class connection

UBus connection returned by ubus.connect.

This object manages an ubus connection and dispatches events/call replies in a background coroutine.

connection:close ()
Close the connection.
connection:call (object, method[, params[, timeout]])
Call an ubus method using an existing connection.

Parameters:

  • object string UBus object path.
  • method string Method name.
  • params table Parameters table. (optional)
  • timeout number Timeout in seconds. (optional)

Returns:

    table Result table.

Or

  1. nil On failure.
  2. string Error message ('timeout' or a libubus message).
connection:send (event[, params])
Send an ubus event.

Parameters:

  • event string Event name.
  • params table Event payload. (optional)

Returns:

    boolean true On success.

Or

  1. nil On failure.
  2. string Error message.
connection:reply (req[, msg])
Reply to a request.

This is called from handlers registered via connection:add.

Parameters:

  • req lightuserdata Request handle.
  • msg table Reply message. (optional)

Returns:

    boolean true On success.

Or

  1. nil On failure.
  2. string Error message.
connection:listen (event, cb)
Listen to ubus events.

When the connection is created with auto_reconnect = true, event listeners added by this method are automatically re-registered after reconnect.

The callback is executed in a new coroutine as:

cb(event, msg, con)

Parameters:

  • event string Event name, or '*' for all.
  • cb function Callback cb(event, msg, con).

Returns:

    boolean true On success.

Or

  1. nil On failure.
  2. string Error message.
connection:add (object, defs)
Add a ubus object with method handlers.

defs is a table mapping method name to { cb, policy }.

When the connection is created with auto_reconnect = true, objects added by this method are automatically added again after reconnect.

The method callback is executed in a new coroutine as:

cb(req, msg, con)

You usually send the reply using connection:reply. The callback may return a numeric ubus status code; non-number return values are treated as 0.

policy is a table mapping field name to policy type (e.g. ubus.STRING, ubus.INT32).

Parameters:

  • object string Object name.
  • defs table Method definition table.

Returns:

    lightuserdata obj Object handle (opaque).

Or

  1. nil On failure.
  2. string Error message.

Usage:

    local ubus = require 'eco.ubus'
local con = assert(ubus.connect())

local defs = {
    echo = {
        function(req, msg, con)
            con:reply(req, msg)
        end,
        { text = ubus.STRING }
    }
}

con:add('eco', defs)
connection:subscribe (path, cb[, auto=false])
Subscribe to notifications of an ubus object.

The callback is executed in a new coroutine as:

cb(method, msg, con)

Parameters:

  • path string Object path.
  • cb function Callback cb(method, msg, con).
  • auto boolean Auto-subscribe when the object appears later. (default false)

Returns:

    lightuserdata subscriber Subscriber handle.

Or

  1. nil On failure.
  2. string Error message.
connection:unsubscribe (subscriber)
Unsubscribe from an ubus object notifications.

Parameters:

Returns:

    boolean true On success.

Or

  1. nil On failure.
  2. string Error message.
connection:notify (object, method[, params])
Send a notification from an object.

Parameters:

  • object lightuserdata Object handle returned by connection:add.
  • method string Notification method name.
  • params table Payload. (optional)

Returns:

    boolean true On success.

Or

  1. nil On failure.
  2. string Error message.
connection:objects ()
List ubus objects.

Returns:

    table objects A map of id -> path.

Or

  1. nil On failure.
  2. string Error message.
connection:signatures (object)
Get the signatures of an ubus object.

Parameters:

  • object string UBus object path.

Returns:

    table signatures

Or

  1. nil On failure.
  2. string Error message.
generated by LDoc 1.5.0 Last updated 2026-04-09 14:48:22