Skip to content
Librux Runtime Kernel for Robotics development
Librux Runtime Kernel for Robotics development

    Advanced Resource Policy

    This exercise keeps the cleaner tutorial context and adds the resource-control layer. It does not introduce a new robot. It shows where host resources are claimed when the same cleaner graph moves from the simulator toward hardware.

    cleaner package boundary + resource claim = resource authority

    The runnable part uses the installed cleaner packages and a no-hardware CPU probe. Hardware-specific checks are optional and should be run only on hosts with the matching NIC, CAN interface, or device node.

    1. Start The Cleaner Under Managed Launch

    Start the tutorial world in one terminal.

    . /opt/librux/env.sh
cd /opt/librux
python3 tutorials/run_sim_world.py --host 127.0.0.1

    For a remote runtime host, use the same rule as the core tutorial.

    python3 tutorials/run_sim_world.py --host 0.0.0.0

    In another terminal, start the complete radar deployment.

    . /opt/librux/env.sh
cd /opt/librux
librux deploy up tutorials/deployments/radar.deployment.yaml --replace

    Inspect the managed leases created by the deployment.

    librux resource status
librux launch list

    Expected result.

    • cleaner subsystem instances are visible as managed runtime sessions
    • the package runtime directories are under /opt/librux/var/run/packages
    • the simulated gateway has no hardware resource claim yet
    • packages with browser backends use brokered network sandboxing for package frontends

    This proves the first resource-control rule. A package launched outside Librux can run code, but it does not receive a managed resource lease.

    2. Inspect The Cleaner Resource Boundary

    Open the simulated gateway package.

    nano tutorials/subsystems/gateway.device_gateway/package.yaml

    Then open one component package.

    nano tutorials/subsystems/component.mobile/package.yaml

    In the simulator, both packages have empty hardware claims because the gateway talks to the provided simulator HTTP API. On a physical cleaner, the same roles would claim different resources.

    Cleaner role Resource policy
    gateway.device_gateway owns NIC, raw Ethernet fieldbus, CAN, serial, camera, GPIO, or device-node claims
    component.* may request CPU affinity or scheduler policy, but should not own hardware interfaces
    compound.cleaner normally no device claim; it composes component and gateway APIs into capabilities
    app.cleaner.* no device claim; it calls capabilities and uses brokered package frontend networking

    The rule is intentional. Hardware access belongs behind gateways. Components can need compute resources, but they should not bypass a gateway to touch host interfaces directly.

    3. Run A CPU Resource Probe

    The installed tutorial includes a no-hardware resource fixture. It represents a timing-sensitive component workload that asks the resource authority for CPU placement.

    librux package validate tutorials/advanced/resource_control/cpu_package
librux package build tutorials/advanced/resource_control/cpu_package \
  --out /tmp/librux-cleaner-cpu-probe \
  --force
librux launch run /tmp/librux-cleaner-cpu-probe \
  --config /opt/librux/runtime/config.yaml \
  --instance component.cpu_probe

    Expected result.

    • package validation succeeds
    • the process starts through librux-resourced
    • launch output reports the resource attachment result
    • the worker prints its PID and, on Linux hosts with taskset, the CPU affinity

    The fixture exits after a short sleep. Run librux resource status while it is active if you want to see the transient lease.

    If the host has only one CPU core, change the fixture's CPU claim to core 0 before running the probe. The installed test sandboxes normally have more than one core.

    4. Run A Gateway Outlet Smoke

    The following checks are optional because they need host-specific hardware. Choose the one that matches the resource a real cleaner gateway would own.

    First inspect available host resources.

    librux resource inventory

    For an IP network gateway, choose a real NIC and run the brokered network probe.

    ip -brief link
python3 tutorials/advanced/resource_control/brokered_network/bin/make_package.py \
  --out /tmp/librux-brokered-network \
  --interface eth0 \
  --repo-root "$PWD"
librux launch run /tmp/librux-brokered-network \
  --config /opt/librux/runtime/config.yaml \
  --detach

    For an EtherCAT or other raw Ethernet fieldbus gateway, declare a link-layer claim in the gateway package.

    resources:
  link_layer:
    interfaces:
      - name: eth1
        mode: exclusive
        access: raw_packet
        protocols: [ethercat]
        grant:
          capabilities: [CAP_NET_RAW]

    Validate and launch that gateway package on the target host.

    librux package validate ./my_ethercat_gateway
librux launch run ./my_ethercat_gateway \
  --config /opt/librux/runtime/config.yaml \
  --detach
librux resource status

    For a SocketCAN gateway, choose a CAN interface and run the CAN probe.

    ip -details link show type can
python3 tutorials/advanced/resource_control/brokered_can/bin/make_package.py \
  --out /tmp/librux-brokered-can \
  --interface can0 \
  --repo-root "$PWD"
librux launch run /tmp/librux-brokered-can \
  --config /opt/librux/runtime/config.yaml \
  --detach

    For a serial device gateway, choose an unused TTY node and run the managed device smoke.

    ls -l /dev/ttyAMA* /dev/ttyS* /dev/ttyUSB* /dev/ttyACM* 2>/dev/null
tutorials/advanced/resource_control/brokered_device/bin/run_tty_smoke.sh \
  --device /dev/ttyAMA10 \
  --prefix /opt/librux

    Expected result for these gateway outlet checks.

    • direct unmanaged access is blocked where a brokered sandbox is requested
    • accepted handles are delivered through the resource broker
    • conflicting claims on the same exclusive resource are rejected
    • raw Ethernet fieldbus traffic stays inside the gateway process after launch

    5. Read The Cleaner Shape Backward

    The resource boundary is the same whether the gateway talks to a simulator or a physical bus.

    flowchart LR App["app.cleaner.*<br/>capability client"] Compound["compound.cleaner<br/>capability implementation"] Components["component.*<br/>control APIs and CPU claims"] Gateway["gateway.*<br/>device and bus claims"] Hardware["NIC, CAN, serial,<br/>fieldbus, camera, GPIO"] App --> Compound Compound --> Components Compound --> Gateway Components --> Gateway Gateway --> Hardware

    For the simulator, gateway.device_gateway calls the simulator API. For a real cleaner, a product gateway package would replace that simulator call with CAN, serial, camera, EtherCAT, GPIO, or another interface claim.

    6. Cleanup

    Stop the radar deployment.

    librux deploy down tutorials/deployments/radar.deployment.yaml

    If a probe is still running, stop it by lease id from librux resource status.

    librux resource stop <lease-id>

    Stop the tutorial world terminal with Ctrl-C.

    Continue to Advanced Federation.