Skip to content
wheelosPublic

About

Autonomous driving middleware publish subscribe system

Topics

Resources

Contributing

Stars

55 stars

Watchers

5 watching

Forks

Repository files navigation

Project Name

wheelos_core

Overview

wheelos_core is the WheelOS runtime foundation for message passing and middleware coordination. The repository implements the Cyber RT stack used for publish/subscribe channels, service/client RPC, component lifecycle management, coroutine-style scheduling, topology discovery, shared-memory and RTPS transport, record/playback, native tools, and Python bindings.

The code is organized under cyber/, with the public C++ entry point exposed through cyber/cyber.h. The project is built with Bazel and ships native runtime tools such as cyber_launch, cyber_monitor, and cyber_recorder.

The reusable unified runtime rules assemble source-built modules into one relocatable development, installed, or archived product.

Role in WheelOS

wheelos_core sits in the WheelOS Runtime layer and provides the message-oriented middleware runtime used by higher-level components and applications.

WheelOS
 |
 +--- Runtime
      |
      +--- wheelos_core
           |
           +--- cyber runtime
           |    +--- Node / Channel / Service APIs
           |    +--- Scheduler and task execution
           |    +--- Transport: INTRA / SHM / RTPS
           |    +--- Topology and service discovery
           |    +--- Record, tools, and Python integration
           |
           +--- examples
           +--- docs and release tooling

Architecture

Application / Component
          |
          v
+-----------------------------------------------+
| Node API (CreateNode / Channel / Service)     |
+-----------------------------------------------+
          |
          +----------------------+------------------+
          |                      |
          v                      v
+-------------------+   +----------------------------+
| Scheduler / Task  |   | Component loader / lifecycle |
+-------------------+   +----------------------------+
          |
          v
+-----------------------------------------------+
| Topology manager / service discovery          |
+-----------------------------------------------+
          |
          v
+-----------------------------------------------+
| Transport layer                                |
| INTRA / SHM / RTPS / QoS / message routing    |
+-----------------------------------------------+
          |
          v
Subscriber / Receiver / Proc() execution

Applications depend on //cyber or the explicit targets in the public API contract. //cyber:cyber_core, discovery managers, scheduler policies, and transport backends are internal implementation targets, not external APIs.

The main ownership boundaries are:

Directories Responsibility
node/, service/, parameter/, gpu/ Application APIs and their adapters; RPC uses transport directly rather than Node internals
component/, mainboard/, class_loader/ Component contracts, process assembly, and dynamic loading
scheduler/, croutine/, task/, timer/ Dispatch policies, execution contexts, task submission, and timers
data/, blocker/ Scheduling data buffers/fusion and publish/observe caches; simulation Node adapters live in node/internal/
transport/, service_discovery/ Data backends and topology control; GPU Node control-plane adapters live in gpu/, not the backend
record/, tools/, python/ Record-file library, runtime commands, and language bindings

Paths in this table are relative to cyber/. The public SDK distinguishes supported header roots from the internal support headers needed to compile C++ templates; it does not export the entire runtime dependency graph.

Installation

Build the toolchain and dependencies

sudo bash scripts/deploy/build.sh

This installs the Bazel build dependencies used by the repository.

Build the project

Use Bazel 8.8.1, matching Apollo-Lite. Bazelisk reads the version from .bazelversion; a separately installed bazel binary must match it. Protobuf 36.2 generates Python code requiring protobuf>=7.36.2,<8. Abseil and GoogleTest remain at the latest versions compatible with Protobuf's Abseil compatibility level 1.

bash scripts/build.sh

The repository default build entry point is scripts/build.sh, which runs Bazel with the CI configuration and //cyber/... by default. For narrower checks, the repository also documents:

bazel build //cyber
bazel test //cyber/message/...

For containerized unit, integration, installed-package E2E and release gates, see the test ownership and release workflow.

Offline / vendor build mode

Vendor mode is an opt-in Bazel workflow for offline or air-gapped builds. Generate the lockfile and vendor tree while online, then publish a self-contained archive:

bazel mod deps --config=ci --lockfile_mode=update
bash scripts/release/build_vendor_bundle.sh --outdir artifacts/vendor

The script refreshes the Bazel 8.8.1-compatible MODULE.bazel.lock, runs bazel vendor --lockfile_mode=update, validates //:wheelos_core, and writes an archive such as artifacts/vendor/wheelos_core_vendor_<timestamp>.tar.gz. The archive contains the source snapshot, vendor/bazel repositories and registry files, and the lockfile. It does not contain bazel-external, which Bazel recreates at runtime.

To compile from the archive, extract it into a writable directory. Keep the lockfile and vendor tree together, use a fresh output root and empty repository cache, and disable downloads:

mkdir -p /work/wheelos-vendor
tar -xzf artifacts/vendor/wheelos_core_vendor_<timestamp>.tar.gz \
  -C /work/wheelos-vendor
cd /work/wheelos-vendor/repo
mkdir -p /tmp/empty-repository-cache
bazel \
  --output_user_root=/tmp/wheelos-vendor-output \
  build \
  --config=ci \
  --lockfile_mode=error \
  --vendor_dir=vendor/bazel \
  --repository_cache=/tmp/empty-repository-cache \
  --repository_disable_download \
  //:wheelos_core

For strict validation, run the extracted tree in an Ubuntu 22.04 container with Docker --network none. Do not mount vendor/bazel read-only: Bazel must create the runtime bazel-external symlink. Do not delete the lockfile or use --lockfile_mode=off, because Bazel then falls back to remote registries.

Install the runtime bundle

bazel build //:wheelos_core
sudo apt install ./bazel-bin/wheelos_core_1.0.0_all.deb
source /opt/wheelos_core/setup.bash
cyber_launch --help

The Debian package is the supported native runtime bundle. It installs commands such as mainboard, cyber_launch, cyber_monitor, and cyber_recorder under /opt/wheelos_core.

Examples

The repository contains minimal example components under examples/. The clearest end-to-end example is examples/common_component_example.

cd /path/to/core
bazel build //examples/common_component_example/...

Start the component in one terminal:

cyber_launch start examples/common_component_example/common.launch

Or start it directly from the DAG file:

mainboard -d examples/common_component_example/common.dag

Then start the two writer nodes in separate terminals:

bazel run //examples/common_component_example:channel_test_writer
bazel run //examples/common_component_example:channel_prediction_writer

This example demonstrates loading a component from a shared library and feeding it messages from multiple writer processes.

There are additional related examples under examples/timer_component_example, but the common component example is the smallest repository-provided example with explicit build and run commands.

Documentation

Start with the documentation index for the complete, categorized guide list.

The guides are the recommended entry point for installation and runtime usage; generated API documentation remains the code-level reference.

About

Autonomous driving middleware publish subscribe system

Topics

Resources

Contributing

Stars

55 stars

Watchers

5 watching

Forks

Packages

Used by

Contributors

Languages