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

    Advanced Federation

    This exercise runs the same cleaner robot graph across two runtime hosts. It is not a separate federation demo. The gateway side stays near the simulator or hardware, and the compute side runs components, compound policy, and the app.

    same cleaner graph + two runtime hosts = federated cleaner topology

    1. What You Will Run

    Use two hosts with the same R2Kernel release installed.

    Host Cleaner responsibility
    Gateway host tutorial world, simulator API, and gateway.device_gateway
    Compute host component.*, compound.cleaner, and app.cleaner.radar
    flowchart LR subgraph GH["Gateway host"] World["Tutorial world"] Gateway["gateway.device_gateway"] end subgraph CH["Compute host"] Mobile["component.mobile"] Arm["component.manipulation"] Grip["component.gripper"] Perception["component.perception"] Compound["compound.cleaner"] App["app.cleaner.radar"] end Gateway --> World Mobile -. "federated binding" .-> Gateway Arm -. "federated binding" .-> Gateway Grip -. "federated binding" .-> Gateway Perception -. "federated binding" .-> Gateway Compound --> Mobile Compound --> Arm Compound --> Grip Compound --> Perception App --> Compound

    r2kernel deploy up is host-local. It does not SSH into the peer host. In this exercise, you start each host's local processes directly, then validate the combined graph with the cleaner external deployment manifest.

    2. Configure Both Hosts

    On the gateway host, expose the control backend on a reachable address and list the compute host as a peer.

    . /opt/r2kernel/env.sh
r2kernel config set control.api_host 0.0.0.0
r2kernel config set control.advertise_host <gateway-host>
r2kernel config set federation.peers '[{"host":"<compute-host>","api_port":8001}]'
r2kernel config validate
sudo systemctl restart r2kernel-control.service

    On the compute host, do the inverse.

    . /opt/r2kernel/env.sh
r2kernel config set control.api_host 0.0.0.0
r2kernel config set control.advertise_host <compute-host>
r2kernel config set federation.peers '[{"host":"<gateway-host>","api_port":8001}]'
r2kernel config validate
sudo systemctl restart r2kernel-control.service

    The two hosts must reach each other on control API port 8001. On an untrusted network, enable Web/API security and federation transport security before exposing the hosts.

    r2kernel config set federation.security.mode required
r2kernel config set federation.security.key_id cleaner-lab
r2kernel config set federation.security.key_file /opt/r2kernel/var/lib/security/federation.key

    Use compatible key material on both hosts before restarting r2kernel-control.service.

    3. Start The Gateway Host

    Run the tutorial world on the gateway host.

    . /opt/r2kernel/env.sh
cd /opt/r2kernel
python3 tutorials/run_sim_world.py --host 0.0.0.0

    In another gateway-host terminal, start only the gateway subsystem.

    . /opt/r2kernel/env.sh
cd /opt/r2kernel
r2kernel launch run tutorials/subsystems/gateway.device_gateway \
  --instance gateway.device_gateway \
  --set simulator.url=http://127.0.0.1:8092 \
  --detach

    Check that the gateway is registered locally.

    r2kernel launch list
r2kernel subsystem bindings gateway.device_gateway

    The gateway host owns the simulator or hardware resource boundary. Nothing on the compute host should open the simulator or hardware directly.

    4. Start The Compute Host

    On the compute host, start each component and bind it to the federated gateway interfaces.

    . /opt/r2kernel/env.sh
cd /opt/r2kernel
r2kernel launch run tutorials/subsystems/component.mobile \
  --instance component.mobile \
  --bind actuator_servo=gateway.device_gateway.actuator_servo \
  --detach

r2kernel launch run tutorials/subsystems/component.manipulation \
  --instance component.manipulation \
  --bind actuator_servo=gateway.device_gateway.actuator_servo \
  --detach

r2kernel launch run tutorials/subsystems/component.gripper \
  --instance component.gripper \
  --bind digital_io=gateway.device_gateway.digital_io \
  --detach

r2kernel launch run tutorials/subsystems/component.perception \
  --instance component.perception \
  --bind perception_sensor=gateway.device_gateway.perception_query \
  --detach

    Start the compound subsystem.

    r2kernel launch run tutorials/subsystems/compound.cleaner \
  --instance compound.cleaner \
  --bind mobility=component.mobile.mobile_base \
  --bind manipulation=component.manipulation.manipulator \
  --bind gripper=component.gripper.gripper \
  --bind perception=component.perception.perception \
  --bind actuator_servo=gateway.device_gateway.actuator_servo \
  --bind digital_io=gateway.device_gateway.digital_io \
  --detach

    Start the radar app on the compute host.

    r2kernel launch run tutorials/subsystems/app.cleaner.radar \
  --instance app.cleaner.radar \
  --bind mobility=compound.cleaner.mobility \
  --bind trash_disposal=compound.cleaner.trash_disposal \
  --bind perception=compound.cleaner.perception_query \
  --detach

    5. Validate The Split Cleaner Graph

    The installed tutorial includes an external deployment manifest for this development-style bring-up.

    r2kernel deploy validate tutorials/deployments/dev/radar.deployment.yaml
r2kernel deploy status tutorials/deployments/dev/radar.deployment.yaml
r2kernel subsystem bindings

    Expected result.

    • compute-host instances are local managed processes
    • gateway.device_gateway is visible through federation
    • component requirements bind to the gateway provider interfaces
    • compound.cleaner provides the capabilities required by app.cleaner.radar
    • the development deployment is external, so it validates and observes but does not start or stop these manually launched processes

    If the gateway appears as missing, check federation peer configuration, firewall rules for port 8001, and the gateway host's advertised address.

    6. Observe The Federated Cleaner

    Open the world viewer from the gateway host.

    http://<gateway-host>:8091/

    Open the compute host Web Console separately if you want to inspect the runtime graph where the app and components are local.

    http://<compute-host>:8001/

    The world viewer should show the same cleaner behavior as the single-host radar deployment. The difference is ownership. Gateway resource policy stays on the gateway host, while application and component workloads stay on the compute host.

    7. Cleanup

    On the compute host, terminate the manually launched processes.

    r2kernel subsystem terminate app.cleaner.radar
r2kernel subsystem terminate compound.cleaner
r2kernel subsystem terminate component.perception
r2kernel subsystem terminate component.gripper
r2kernel subsystem terminate component.manipulation
r2kernel subsystem terminate component.mobile

    On the gateway host, terminate the gateway and stop the tutorial world terminal.

    r2kernel subsystem terminate gateway.device_gateway

    Stop the world terminal with Ctrl-C.

    What This Proves

    • federation is a host-level runtime relation, not a new subsystem role
    • subsystem manifests and bindings remain the same across host boundaries
    • deployment validation can describe a split graph without starting remote processes
    • gateway-host resource policy can stay near the hardware
    • compute-host app and component policy can stay near CPU or GPU resources
    • the cleaner graph can move from single host to multi-host without changing application intent

    For timing-sensitive multi-host work, combine this with Time Sync Operations before enabling real actuators.