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

    Developer Guide

    Use this section when you are writing, running, or testing Librux subsystems. It assumes that Librux is already installed and that you have completed Quickstart.

    In Librux, native development usually means building one subsystem role and using existing packages for the rest of the robot composition. The role you choose defines the boundary you own.

    Installed Runtime Or Source Checkout

    Start from the installed runtime for normal tutorial, package, and subsystem development. The installer already places SDK payloads, tutorial packages, deployment manifests, and runtime tools under the selected prefix.

    For the standard product install, that prefix is /opt/librux.

    Path Purpose
    /opt/librux/sdk/python installed Python SDK wheel payload
    /opt/librux/sdk/cpp installed C++ SDK headers, libraries, and CMake files
    /opt/librux/tutorials guided cleaner robot tutorial source
    /opt/librux/tutorials/subsystems subsystem package roots used by the tutorial
    /opt/librux/tutorials/deployments staged and full robot deployment manifests
    /opt/librux/tutorials/advanced advanced tutorial fixtures
    /opt/librux/benchmarks installed benchmark runners, when included in the release

    Use a writable copy when you want to edit tutorial packages.

    mkdir -p ~/librux-work
cp -R /opt/librux/tutorials ~/librux-work/tutorials
cd ~/librux-work

    Use a source checkout only when you need editable project source.

    • SDK implementation changes
    • runtime or launcher changes
    • documentation changes
    • tutorial source contributions
    • source-level tests or release verification

    When using an editable Python SDK checkout, create a dedicated virtual environment. Run this from the source repository root.

    python3 -m venv ~/librux-sdk-dev
. ~/librux-sdk-dev/bin/activate
python -m pip install -e sdk/python

    Complete robotics demos live outside the guided installed tutorial path. Use the demo repository separately when you want larger example applications rather than the step-by-step cleaner tutorial.

    Check The Installed SDKs

    Source the installed environment before running tutorial packages or SDK code.

    . /opt/librux/env.sh

    Check the Python SDK.

    python3 -c 'import librux; print("Librux Python SDK ready")'

    Check the C++ SDK payload.

    test -r /opt/librux/sdk/cpp/include/librux/wrapper/subsystem.hpp
find /opt/librux/sdk/cpp -maxdepth 4 \( -name 'liblibrux_cpp.*' -o -name 'librux_cppConfig.cmake' \) -print

    Then check that the installed runtime services are reachable.

    librux system status
librux resource status
curl -sf http://127.0.0.1:8001/api/v1/ready

    If services were skipped during installation, register them first.

    sudo /opt/librux/bin/librux system install --prefix /opt/librux

    Choose The Subsystem Role You Are Building

    Every native runtime unit is a subsystem. Each subsystem declares one role in subsystem.yaml. Choose the role by the boundary you are contributing.

    Role Developer boundary Typical provide surface Typical dependency
    gateway hardware or simulator-backed device boundary device-facing api.* contracts host resources such as NIC, CAN, serial, USB, or device files
    component reusable robotics control function, such as motion, perception, IO, safety, or planning component contracts and their underlying api.* contracts gateway or other component APIs
    compound robot platform composition and app-facing capability surface capability.* contracts component, gateway, or lower-level APIs
    app robot task, scenario, SI logic, or product application application status and optional app-owned UI platform capabilities

    The common development pattern is to build one role and reuse existing packages for the others. For example, a gripper vendor may build only a component subsystem, while a platform company builds a compound subsystem from existing gateway and component packages. An application developer usually builds an app subsystem against a platform capability surface.

    The cleaner tutorial is the baseline path for all of these roles because it shows the same package, manifest, binding, and deployment mechanics each role uses.

    Native Subsystem Development Flow

    Use this order when building a native Librux subsystem.

    1. Run the Cleaner Robot Tutorial once without edits.
    2. Pick the role you are building: gateway, component, compound, or app.
    3. Copy /opt/librux/tutorials to a writable workspace if you need local edits.
    4. Use the matching tutorial chapter as the nearest working example.
    5. Use Subsystem Packages when you need a managed package root.
    6. Use Subsystem SDK API for Python and C++ authoring details.
    7. Use Resource Policy when the subsystem needs CPU, NIC, CAN, serial, or device access.

    The base tutorial chapters map to the role boundaries.

    Role focus Tutorial page
    simulation and visible test target Start Simulation World
    gateway subsystem Build Gateway Subsystem
    component subsystems Add Component Subsystems
    compound subsystem and platform manifest Define Platform
    app subsystem and deployment Run Applications

    Using Existing Stacks Such As ROS 2

    ROS 2 integration is not a separate Librux role. A ROS 2 graph can be wrapped as one Librux subsystem when that graph owns one clear runtime boundary.

    Choose the wrapper role by what the ROS 2 side represents.

    ROS 2 boundary Librux wrapper role
    hardware bridge, driver, or simulator device boundary gateway
    reusable controller, perception pipeline, planner, or safety function component
    robot platform composition or app-facing capability implementation compound
    task-level scenario or product application app

    This keeps ROS 2 as an implementation choice inside a role-bounded subsystem. The Librux side still declares package metadata, lifecycle behavior, contracts, bindings, and resource policy at the subsystem boundary.

    Continue with ROS 2 Integration when the subsystem you are building is backed by ROS 2.

    External Integration

    External integrations stay outside the native subsystem runtime. Use this path for browser frontends, product GUIs, cloud services, automation scripts, diagnostics tools, and other clients that talk to a Librux host through Host Control APIs.

    1. API Overview
    2. Host Control REST API
    3. Host Control WebSocket API
    4. Teleop App Frontend
    5. Web Console Manual

    External clients can observe events, invoke Procedure or Operation calls, inspect runtime state, manage packages, or open app-owned frontend surfaces. They do not become native subsystems and do not join native subsystem transport directly.

    Topic Page
    First installed run Quickstart
    End-to-end native tutorial Cleaner Robot Tutorial
    Package roots and launch metadata Subsystem Packages
    Subsystem author API Subsystem SDK API
    Host automation API Host Control REST API
    Host event and app UI API Host Control WebSocket API
    Runtime concepts Robot, Application, And Deployment
    Binding model Subsystem Binding Model
    ROS 2 wrapper guidance ROS 2 Integration