Getting Started with the Ambiorix (amx) Bus

Components never talk to a bus API directly. They talk to libamxb, and whichever backend plugin is loaded translates that onto the real bus underneath — ubus or otherwise, without the component code changing.

Compare that to the rpcd approach: there, you wrote the code that speaks the list/call JSON protocol for a single, specific bus. Here, the backend plugin and amxrt write that code for you — you only describe what the object looks like (in ODL) and implement the custom logic (in C), and it works unchanged on any bus that has a backend.

ODL files have (up to) three sections:

A minimal object definition looks like this:

For every method in the ODL, Ambiorix looks for a matching C function, by default named _<method> (or _<Object>_<method> if there are name clashes) inside the .so you import. The expected C prototype is fixed:

That’s the entire contract. No JSON parsing, no list/call dispatch loop to write.

amxc_var_set(cstring_t, ret, buf) stores a C string into the generic variant that gets sent back over the bus — the amx equivalent of writing a JSON string into the rpcd reply.

Note : <amxd/amxd_object.h> uses types (like amxp_signal_mngr_t) that come from <amxp/amxp.h>, but doesn’t include it for you — and <amxp/amxp.h> in turn expects <amxc/amxc.h> to already be visible. Leave any of the three out, or reorder them, and you’ll get "unknown type name" errors deep in a header you didn’t write. Include amxc before amxp before amxd, every time.

Build it natively if the Ambiorix dev libraries and headers are installed on your machine:

If you’re developing on your workstation but the device is, say, an aarch64 board like the Banana Pi BPI-R4, you don’t build natively — you point the Makefile at your prplOS/OpenWrt SDK’s cross toolchain and the target’s staging sysroot (which already has libamxc, libamxd, and their headers built for that architecture):

CROSS_COMPILE is the compiler prefix (the Makefile appends gcc), and SYSROOT is the target’s staging directory — the same one the buildroot uses when it compiles every other package for this board. Confirm the result before shipping it over:

Then copy the two files the component needs straight onto the board and start it exactly as before:

From here, ubus list / ubus call and ba-cli work against the real board exactly as described below — the ODL and the RPC contract don’t change based on which CPU is executing them, only the compiler flags used to build the .so did.

Make sure ubusd is running, and a ubus backend is available to amxrt (this is the amxb_ubus plugin — on prplOS/OpenWrt it’s already part of the base image). Then:

-D runs it as a daemon. Under the hood, amxrt parsed the ODL, built the SysTime object in memory, dlopen'd systime.so, connected to ubusd through amxb_ubus, and registered SysTime as a ubus object — all without you writing a single line of ubus registration code.

Where rpcd sits between ubusd and a shell plugin speaking list/call JSON, amxb_ubus sits between ubusd and amxrt, speaking the bus-agnostic protocol that libamxd understands.

Because the backend is ubus, all your familiar tools still work:

Each call prints three separate JSON objects rather than one flat reply: the return value under the generic key retval, an empty table for named output arguments (currentTime()/currentDate() only declare a return type, not out args), and a status object carrying amxd-error-code — the same status _currentTime() / _currentDate() returned from C, where 0 means amxd_status_ok. It’s not an error; it’s amxb_ubus always appending the call’s result code after the return value.

Notice _list, _describe, _get, _get_instances, _get_supported, _set, _add, _del, _exec showed up automatically — you didn’t implement any of those. Every object published by Ambiorix gets generic parameter get/set and instance add/delete semantics for free, on top of the two custom methods you wrote.

ubus is a fine way to check your component, but it only speaks ubus. prplOS also ships ba-cli — the "Bus Agnostic Command Line Interface" — which talks to whatever backend libamxb has loaded (ubus among them) through the same bus-agnostic API your component is built on, instead of a bus-specific one.

List the object and call its methods exactly as you would in an interactive shell — methods, not just parameters, need () to be invoked:

Forgetting the () calls out the mistake instead of silently doing nothing, and the trailing (0)/(-1) in the prompt tracks the last command’s status:

Same component, same data model, same result you got from ubus call — just reached through the bus-agnostic front door instead of a bus-specific one. That’s the practical payoff of building on libamxb: one component, testable and usable from any backend that’s loaded, with no code changes.