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

    Resource Control

    R2Kernel resource control applies to subsystem processes launched as managed packages. It validates declared host-resource claims, records ownership, and releases accepted resources when the managed process scope ends.

    It is not a global Linux sandbox. A process started directly from a shell does not receive managed resource guarantees.

    Operating Model

    A managed launch follows this observable sequence.

    1. the package declares its resource requirements
    2. the host resource service accepts or rejects the claim
    3. the process starts only after admission succeeds
    4. launch status reports the guarantees that were applied
    5. owned resources are released after the managed process scope ends

    Web Console Runtime launches and detached CLI launches use the same authority path.

    Runtime Configuration

    resource_service:
  mode: "auto"        # auto, required, or disabled
    Mode Operator meaning
    auto Use the resource service when available and permit supported development fallbacks.
    required Fail managed launch when resource authority is unavailable. Recommended after product-host validation.
    disabled Disable managed resource admission and managed package lifecycle.

    Service Checks

    . <prefix>/env.sh
r2kernel system status
r2kernel resource status
r2kernel resource inventory

    Install or repair system services from the selected prefix.

    sudo <prefix>/bin/r2kernel system install --prefix <prefix>

    When serial, USB, or device-node packages are used, install the device policy.

    sudo <prefix>/bin/r2kernel-device-policy-install \
  --device-group r2kernel-device \
  --device-mode 0660

    Do not grant normal users broad production device access. Product hardware should be reached through admitted managed packages.

    Managed Launch

    Validate, build, and launch a package.

    r2kernel package validate ./my_controller
r2kernel package build ./my_controller \
  --out ./dist/my_controller.r2kernelpkg \
  --force
r2kernel launch run ./dist/my_controller.r2kernelpkg --detach

    Inspect or stop its lease.

    r2kernel resource status
r2kernel launch status <lease-id>
r2kernel resource stop <lease-id>

    Package parameters must be declared in package.yaml. The launcher rejects undeclared --set keys.

    Package Resource Declaration

    schema_version: 1
name: gateway.arm_fieldbus
entrypoint:
  command: bin/gateway
resources:
  cpu:
    cores: [2, 3]
    exclusive: true
  network:
    interfaces:
      - name: enp4s0
        mode: shared
        policy: control-plane
  link_layer:
    interfaces:
      - name: enp5s0
        mode: exclusive
        access: raw_packet
        protocols: [ethercat]
        grant:
          capabilities: [CAP_NET_RAW]
  devices:
    paths:
      - /dev/ttyUSB0
    can:
      - can0
  sandbox:
    network: brokered
    can: brokered
    devices: managed

    Relative entrypoints resolve inside the package directory and cannot escape it.

    Resource Semantics

    Resource Public semantics
    CPU requests affinity and host-supported isolation; launch status reports applied or degraded guarantees
    NIC requests shared or exclusive use of selected IP-network adapters
    Link layer requests exclusive raw-link access for declared industrial Ethernet protocols
    CAN requests access to selected SocketCAN interfaces
    Serial and device nodes requests access to selected device outlets
    Frontend listener requests an instance-scoped listener for a package UI backend

    network and link_layer name network adapters but express different resource classes. Use network for IP networking. Use link_layer for fieldbus gateways that require raw-link access, such as EtherCAT. Conflicting exclusive claims are rejected.

    Supported link-layer protocol labels are ethercat, cclink_ie_tsn, profinet_rt, and custom_l2. Grant only the capabilities required by the gateway package.

    Role Policy

    • gateway packages may claim hardware-facing resources
    • component packages may claim compute resources and normally use gateway APIs for hardware access
    • compound packages may use component APIs and, when necessary, gateway APIs
    • app packages consume capabilities and must not claim device-facing resources

    App packages with a browser backend use resources.sandbox.network: brokered and declare the listener through frontend.context. Their browser assets remain static package frontend files served by R2Kernel.

    Stop And Cleanup

    Lifecycle stop and process termination are separate. Lifecycle stop asks the subsystem to enter its safe stopped state. Process terminate ends the managed process scope with a grace period. Process kill skips that grace period.

    The process-action result reports whether graceful termination succeeded or a forced kill was required. Resource ownership is not released until the managed process scope is gone.

    Application signal handlers remain best effort. Product safety must not depend on application-level signal acknowledgement alone.

    Direct Execution

    A directly executed SDK process can register identity, bindings, and lifecycle status, but it does not receive:

    • a resource lease
    • managed resource admission
    • managed process ownership
    • host isolation guarantees
    • managed frontend listener grants

    Use direct execution for development. Use managed launch for product deployment. Host policy must restrict unmanaged shell or root access when a product requires R2Kernel to be the only hardware execution path.

    Validation

    Use Resource Policy to exercise CPU, network, link-layer, CAN, serial, and device claims on a suitable Linux host.