Skip to content
R2Kernel Runtime Kernel for Robotics v1.0.0rc1
R2Kernel Runtime Kernel for Robotics v1.0.0rc1

    CLI / Entry Points

    The stable user-facing command is r2kernel. After sourcing <prefix>/env.sh, <prefix>/bin is added to PATH. Operators should prefer the unified command form unless a guide explicitly calls out a lower-level binary.

    Read Runtime Configuration first when you need to understand what a command changes in config.yaml. This page focuses on the CLI entry points used to inspect, change, and operate an installed host.

    . <prefix>/env.sh
r2kernel --help

    Product deployments normally manage daemons through systemd. Development workflows can start the same daemons directly through r2kernel control or the lower-level binaries described below.

    Operator Commands

    Command Dispatches to Purpose
    r2kernel status r2kernel-doctor show installed runtime status and diagnostics
    r2kernel control [args] r2kernel-control run the host control backend directly
    r2kernel serve [args] r2kernel-control alias for r2kernel control
    r2kernel config ... r2kernel-config inspect or edit runtime configuration
    r2kernel package ... r2kernel-package validate or build managed packages
    r2kernel launch ... r2kernel-launch start, restart, stop, and inspect managed package leases
    r2kernel deploy ... built in validate, plan, start, restart, stop, or inspect robot application deployments
    r2kernel subsystem ... r2kernel-subsystem inspect registered subsystem sessions and clean stale state
    r2kernel frame ... built in inspect the runtime frame graph or compose a transform
    r2kernel resource status r2kernel-launch list list active and recently reaped resource leases
    r2kernel resource inventory r2kernel-launch inventory show CPU, NIC, link-layer, CAN, and device inventory
    r2kernel resource stop <lease> r2kernel-launch stop <lease> stop a managed lease and terminate its process scope
    r2kernel timesync doctor r2kernel-timesync-doctor check time-sync readiness
    r2kernel timesync run ... r2kernel-timesync run a manual time-sync helper path
    r2kernel timesync daemon ... r2kernel-timesyncd run the managed time-sync companion directly
    r2kernel system ... systemctl / journalctl operate R2Kernel systemd units

    Common tutorials.

    . <prefix>/env.sh
r2kernel --help
r2kernel status
r2kernel config --help
r2kernel package --help
r2kernel launch --help
r2kernel deploy validate tutorials/deployments/teleop.deployment.yaml
r2kernel subsystem status
r2kernel frame graph
r2kernel frame lookup component.mobile/world component.manipulation/tool0
r2kernel resource inventory
r2kernel timesync doctor
r2kernel system status

    Configuration values can be inspected and overridden by key path.

    r2kernel config get timed_exchange.inline_payload_threshold
r2kernel config set timed_exchange.inline_payload_threshold 65536

    The same key-path model applies to product shell and security settings.

    r2kernel config set product.name "Acme Robot Controller"
r2kernel config set product.vendor "Acme Robotics"
r2kernel config set control.frontend.mode custom
r2kernel config set control.frontend.root /opt/acme/ui/dist
r2kernel config set federation.security.mode required
r2kernel config set federation.security.key_id robot-cell-a
r2kernel config set federation.security.key_file /opt/r2kernel/var/lib/security/federation.key

    Use r2kernel config tui for the common settings form, or use r2kernel config set for any supported dotted key. Secret material should usually live in root-owned files or environment variables rather than inline YAML.

    Deployment Commands

    Use deployment commands before publishing robot tutorials or product deployment manifests.

    r2kernel deploy validate ./r2kernel.deployment.yaml
r2kernel deploy plan ./r2kernel.deployment.yaml
r2kernel deploy plan ./r2kernel.deployment.yaml --json
r2kernel deploy up ./r2kernel.deployment.yaml
r2kernel deploy restart ./r2kernel.deployment.yaml
r2kernel deploy status ./r2kernel.deployment.yaml
r2kernel deploy down ./r2kernel.deployment.yaml

    validate checks the level declared by the manifest. A manifest with only instances and bindings is a subsystem composition. A manifest with robot adds robot slot and capability validation. A manifest with both robot and application also checks the selected app-role subsystem against required capabilities and optional platform compatibility labels from the profiles manifest field. plan prints the concrete instances and launch modes after validation succeeds.

    up reconciles missing or stale managed instances and keeps active matching instances by default. restart is the explicit replacement path; it stops active managed instances, cleans their runtime session state, and launches the desired state again.

    Lower-Level Runtime Tools

    The installed bundle also ships the individual tools used by r2kernel. These are useful for scripts, debug sessions, and direct daemon launches.

    • r2kernel-control - host control backend. Product installs usually run it as r2kernel-control.service; development installs can run it directly with r2kernel control --config "$R2KERNEL_PREFIX/config.yaml".
    • r2kernel-config - runtime config editor and get / set / unset helper.
    • r2kernel-package - package validate and build.
    • r2kernel-launch - managed package run, restart, inventory, list, status, and stop.
    • r2kernel-subsystem - registered subsystem status, sessions, doctor, lifecycle transition requests, runtime bindings, and stale-state cleanup.
    • r2kernel-doctor - aggregate runtime diagnostics.
    • r2kernel-timesync - explicit Linux PTP/time-sync helper launcher.
    • r2kernel-timesyncd - managed time-sync companion used by time_sync.management_mode=managed.
    • r2kernel-timesync-doctor - focused time-sync readiness doctor.
    • r2kernel-resourced - privileged resource companion for managed package leases, brokered resource FDs, affinity, cgroup placement, and cleanup.

    Linux installs additionally provide shell helpers.

    • r2kernel-timesync-install - install linuxptp / ethtool prerequisites.
    • r2kernel-device-policy-install - install R2Kernel udev serial/USB device-node policy.
    • r2kernel-system-service-install - register r2kernel-control.service, r2kernel-resourced.service, and r2kernel-timesyncd.service.

    Direct Development Launch

    For a development install under a user prefix, keep the control backend in a separate terminal.

    . /opt/r2kernel/env.sh
r2kernel control --config "$R2KERNEL_PREFIX/config.yaml"

    For product prefixes, prefer the system service.

    sudo systemctl status r2kernel-control.service --no-pager

    r2kernel dev control, r2kernel dev resourced, and r2kernel dev timesyncd are developer conveniences for starting one daemon directly. r2kernel dev all is intentionally not implicit; start daemons in separate terminals when debugging their logs.

    Use r2kernel launch run <package> --bind requirement=provider.interface when you want to start one managed subsystem package and wire its required interfaces without creating a full deployment. r2kernel deploy up is the command for reconciling a complete robot and application composition. Launch bindings validate the local requirement name and target shape; deployment manifests validate the complete provider contract graph.

    Use r2kernel launch restart <package> ... during iterative development when the same package instance is already running or stale. It uses the same --instance, --bind, --set, and --runtime-dir arguments as run, but the process is always relaunched through the managed detached path.

    If you start a subsystem without a required binding during development, it can remain registered in WaitingBinding instead of failing at process start. Use Runtime Graph in the Web Console, or the subsystem binding commands, to bind it after both sides are visible.

    r2kernel subsystem bindings
r2kernel subsystem bind app.cleaner.teleop.mobility compound.cleaner.mobility
r2kernel subsystem bind app.cleaner.teleop.trash_disposal compound.cleaner.trash_disposal
r2kernel subsystem unbind app.cleaner.teleop.mobility

    Runtime bindings override launch bindings for the running control backend. They are intended for interactive development and operator repair; keep deployment manifests as the reviewable source for product compositions.

    r2kernel launch run prints a concise launch summary by default. Add --json when a script needs the full resource-service response, lease details, or machine-readable logs.

    Spatial Frame Commands

    Use the frame commands after the relevant subsystems and bindings are visible.

    r2kernel frame graph
r2kernel frame lookup <source> <target>

    The graph command reports spatial ports, static compound mounts, dynamic subsystem transforms, stale edges, cycles, and unresolved ports. Lookup composes only current non-stale edges. Prefer qualified names such as component.mobile/world; an unqualified local name is accepted only when it is unique.

    Subsystem Sessions

    Subsystem processes do not need to be launched by a special development launcher. A Python or C++ subsystem can be started from its normal main, script, IDE, debugger, or test harness. The SDK registers a per-process session with the local control backend when the subsystem comes up.

    For a repeated development cycle, the backend treats the subsystem name and session identity together.

    • the same live session can refresh its own status
    • a stale or dead previous session with the same subsystem name can be replaced
    • a different session with the same subsystem name is rejected while the previous session is still active
    • late shutdown messages from an old session cannot remove the current session

    Use the subsystem commands to inspect or repair runtime state.

    r2kernel subsystem status
r2kernel subsystem status arm_controller
r2kernel subsystem sessions --json
r2kernel subsystem doctor arm_controller
r2kernel subsystem bindings arm_controller
r2kernel subsystem bind arm_controller.motion mobile_base.motion
r2kernel subsystem unbind arm_controller.motion
r2kernel subsystem pause arm_controller
r2kernel subsystem resume arm_controller
r2kernel subsystem reset arm_controller
r2kernel subsystem fault arm_controller --reason "encoder timeout"
r2kernel subsystem terminate arm_controller
r2kernel subsystem kill arm_controller
r2kernel subsystem cleanup arm_controller --stale
r2kernel subsystem cleanup arm_controller --force

    Lifecycle commands are requests. The runtime validates the current state and delivers the request to the subsystem SDK hook through the registered notify endpoint. Watch r2kernel subsystem status <name> or Runtime Graph for completion.

    terminate and kill are managed process actions, not lifecycle transitions. They require a resource lease from r2kernel-resourced. terminate gives the process scope a SIGTERM grace window before escalation; kill sends SIGKILL immediately.

    cleanup --stale is the default-safe path and only removes inactive state. cleanup --force is for operator intervention when the current runtime view is known to be wrong.

    Version Provenance

    Installed runtime CLIs read the package version from the bundled release-manifest.json when available. Use --version on r2kernel, r2kernel-control, r2kernel-config, r2kernel-package, r2kernel-launch, r2kernel-subsystem, r2kernel-doctor, r2kernel-timesync, r2kernel-timesyncd, r2kernel-timesync-doctor, and r2kernel-resourced when collecting runtime provenance. Source-tree builds without a release manifest may report the underlying package version instead.

    Source-Tree Helpers

    Source checkouts may include helper scripts for building or inspecting the tree. Those helpers are separate from the installed runtime CLIs listed above.