phoxal 0.20.0

Phoxal - production-oriented autonomous robot framework: the runtime engine and model (the api contract tree lives in phoxal-api, the typed bus in phoxal-bus).
Documentation

phoxal

A production-oriented framework for autonomous robots, shipped as one crate.

Phoxal gives a robot a small, strongly-typed core: a contract bus over Zenoh, a single dated API-version contract set, and a derive-based participant authoring model. The framework owns the awkward parts - argument parsing, bus connection, scheduling, query serving, shutdown, and health - so the code you write is the robot's behavior, not its plumbing.

Greenfield rewrite in progress (tmp/framework-rewrite). The bus + participant machinery and the macros are new; the official service/simulator/tool crates are being re-ported onto this surface and some are temporarily out of the workspace.

[dependencies]
phoxal = "0.17"      # the engine: runner, derives, SetupContext, prelude
phoxal-api = "0.17"  # the contract tree: `use phoxal_api::y2026_1 as api;`

The authoring model

A service is one struct of typed handles + one annotated inherent impl. The struct declares the contracts it uses (as handle fields) and the one API version it runs against; the impl declares the lifecycle.

use phoxal_api::y2026_1 as api;
use phoxal::prelude::*;

#[derive(phoxal::Service)]
#[phoxal(id = "avoid-obstacles", api = y2026_1, config = Config)]
struct AvoidObstacles {
    state:  Latest<api::drive::State>,
    target: Publisher<api::drive::Target>,
    cruise_linear_x_mps: f32,
}

#[derive(serde::Deserialize, phoxal::schemars::JsonSchema)]
struct Config {
    cruise_linear_x_mps: f32,
}

#[phoxal::behavior]
impl AvoidObstacles {
    #[setup]
    async fn setup(ctx: &mut SetupContext<Self>, config: Self::Config) -> Result<Self> {
        Ok(Self {
            state:  ctx.subscribe(api::topic::new().drive().state()).latest().await?,
            target: ctx.publisher(api::topic::new().drive().target()).await?,
            cruise_linear_x_mps: config.cruise_linear_x_mps,
        })
    }

    #[step(hz = 50)]
    async fn step(&mut self, step: StepContext) -> Result<()> {
        let now = step.time();
        // read inputs, publish version-local bodies
        self.target.publish_at(now, api::drive::Target {
            linear_x_mps: self.cruise_linear_x_mps,
            angular_z_radps: 0.0,
            curvature_limit_radpm: None,
        }).await?;
        Ok(())
    }
}

fn main() -> phoxal::Result<()> { phoxal::run::<AvoidObstacles>() }

Key rules the example shows:

  • Import exactly one dated API module (use phoxal_api::y2026_1 as api;) and declare it on the derive (#[phoxal(api = y2026_1)], mandatory).
  • Handle fields use version-local bodies: Publisher<api::drive::Target>, Latest<api::drive::State>. The derive emits a ContractBody<Api = R::Api> assertion, so a body from another API version is a compile error.
  • Topics are api-local: api::topic::new().drive().state().
  • The wire body is the plain payload; api_version, family, and codec ride bus metadata. Normal participants never open Zenoh - the runner opens the bundle-selected bus profile before #[setup].
  • config is for user participants only. Official participants take no config param and read the robot model through ctx.robot().
  • cargo run --example runtime_control_loop emit-apis prints the participant's static metadata as one JSON document (the emit-apis subcommand) and exits.

The runner also owns the rest of the lifecycle: #[step(hz = ...)] is the scheduled control loop, #[server] / #[server_snapshot] serve queries, and #[shutdown] runs graceful park/stop/flush before the bus closes.

Modules

A participant depends on two crates: the phoxal engine (the modules below) and the phoxal-api contract tree.

Module What it is
phoxal_api (separate crate) The dated API-version modules (phoxal_api::y2026_1, …) generated by phoxal_api_tree! from a tree of nested nodes: the marker enum Api (ApiVersion), version-local wire bodies + their ContractBody impls, and the api-local topic builders. Imported directly with use phoxal_api::y2026_1 as api;.
[phoxal::prelude] Everything a participant author imports with use phoxal::prelude::*;: the handle types, SetupContext/StepContext, and Result.
[phoxal::bus] Re-export of the phoxal-bus crate (the ABI floor): the Zenoh-native bus_abi boundary: the key scheme <namespace>/robots/<robot-id>/<topic>, the MessagePack codec, the BusMetadata attachment, and the body-typed handles Publisher/Subscriber/Latest/Querier.
[phoxal::participant] The static metadata traits the macros target, SetupContext/StepContext/ShutdownContext, the clock (RealClock/TestClock) + scheduler, ParticipantLaunch, emit-apis, and the runner (run / tokio::run).
[phoxal::model] Authored manifest schemas (robot.yaml, structure.urdf, component.yaml, …).

Authoring the API tree

The phoxal_api modules (in the phoxal-api crate) are generated by phoxal_api_tree! from a tree of nested nodes. A node is name { … } (static) or name(var) { … } (dynamic, where var is a key segment filled at build time), nestable to any depth. A node body holds any mix of struct/enum type declarations, topic declarations, and child nodes. Each topic declares a role: topic <leaf>: command <Body>; (a control input the owning service subscribes), topic <leaf>: state <Body>; (telemetry the owning service publishes), or topic <leaf>: query <Req> => <Resp>; (request/response). command and state are both pub/sub on the wire; the role selects the side brand of the generated builders (L1), so the public client builder (api::topic::new()) and the internal owner builder (api::topic::internal::new(cap)) return different branded topics (Publish/Subscribe) and taking the wrong side does not compile. The owner builder additionally requires the runner-minted OwnerCap (L2): pass ctx.owner_capability(), so owning a topic is a deliberate, capability-gated opt-in rather than something that can happen by accident. There are no key-template strings and no topic parameter lists; dynamism comes entirely from the (var) nodes on the path.

phoxal_api_tree! {
    version y2026_1 {
        drive {                                  // static node
            struct Target { linear_x_mps: f32, angular_z_radps: f32 }
            topic target: command Target;        // key drive/target, FAMILY drive::Target
            struct State { /* … */ }
            topic state: state State;            // owner-published telemetry
        }
        component(instance) {                    // literal "component" + var {instance}
            motor(capability) {                  // literal "motor"     + var {capability}
                enum Command { Velocity(f32), Torque(f32), Stop }
                topic command: command Command;
            }
        }
    }
}

Everything a topic exposes is derived from the node path n1 … nk to its leaf (each ni has a name and an optional var):

  • Topic key (ContractBody::TOPIC, versionless): each node emits name, or name/{var} for a dynamic node, joined by /, then /<leaf>. So drive → target is drive/target, and component(instance) → motor(capability) → command is component/{instance}/motor/{capability}/command.
  • Module path / type location: each node becomes a nested pub mod name, and a node's types + their ContractBody impls live in that module. Variables never appear in the module path, so the body above is phoxal_api::y2026_1::component::motor::Command.
  • FAMILY (ContractBody::FAMILY): the node names joined by ::, then ::TypeName - e.g. drive::Target, component::motor::Command.
  • Builder: api::topic::new().n1(var?)…nk(var?).leaf(). A dynamic node's method takes its var as impl Display (* / ** stay valid for subscribe); the leaf method yields the typed Topic. So api::topic::new().component("front_left").motor("drive").command() builds the key component/front_left/motor/drive/command.

Each node is self-contained: it declares its own copy of every type it uses, with no super:: and no shared/common module. Because the node path disambiguates, names are path-local - component::imu::Sample and component::range::Sample are distinct types that may safely repeat field names. Duplicating an identical type across sibling nodes is intentional, not a smell.

A later version yNNNN_M extends yNNNN_K { … } re-emits the parent tree as fresh types under the child version (same FAMILY/TOPIC, a different Api), overriding a type by ident or a topic by leaf and appending wholly new nodes - so an inherited node never needs to be retyped.

Entrypoints

  • Default (blocking): fn main() -> phoxal::Result<()> { phoxal::run::<R>() }.
  • Advanced (async): phoxal::tokio::run::<R>().await for custom Tokio mains.

Official service set

The complete platform participant set ships alongside this crate in the workspace service/ tree (drive, localize, map, safety, …). They are full official participants authored on exactly this surface, and they double as worked reference reading. Neutral teaching examples live in phoxal/examples/ (runtime_control_loop, runtime_query_server, runtime_snapshot_server, runtime_async_entrypoint).

Status

Pre-1.0, building in public. One API version per robot graph (#[phoxal(api = y2026_1)]); the wire body is the plain payload and the version identity rides bus metadata, never the key. Compatibility is checked at build/check time (emit-apis + phoxal-cli check), never by introspecting a running binary.

License

AGPL-3.0-only. A commercial license is available - see the repository.