babble-bridge

BabbleSim + Zephyr nRF RPC simulation bridge. Provides:

• Test harness — spawn a full BabbleSim simulation from Rust integration tests
• xtask CLI — setup, sim lifecycle, and Docker management commands
• Programmatic API — call setup and spawn functions directly from build.rs or code

Quickstart for downstream crate authors

1. Add the dependency

Root Cargo.toml:

[workspace]
members = ["your-app", "xtask"]

[workspace.dependencies]
babble-bridge = "0.1.0"

Your crate's Cargo.toml:

[dev-dependencies]
babble-bridge.workspace = true

2. Create an xtask crate

cargo init xtask

xtask/Cargo.toml:

[package]
name = "xtask"
version = "0.1.0"
edition = "2021"

[dependencies]
babble-bridge.workspace = true

xtask/src/main.rs:

fn main() {
    babble_bridge::xtask::cli_main();
}

.cargo/config.toml:

[alias]
xtask = "run -p xtask --"

Platform setup

Linux (native or inside a container)

cargo xtask zephyr-setup --prebuilt   # download Linux BabbleSim + Zephyr binaries (~30 s)

Also creates tests/sockets/ with restricted permissions (0700).

macOS

BabbleSim only runs on Linux. Use the --container flag — it manages a persistent Docker container for you:

cargo xtask start-sim --container     # builds image if needed, starts sim in container

On first run per workspace this also runs zephyr-setup --prebuilt inside the container to fetch Linux binaries.

Simulation lifecycle

Options for start-sim:

--sim-id <id>     Socket name and BabbleSim identifier (default: sim)
--sim-dir <path>  Directory for the socket file (default: <workspace>/tests/sockets)
--container       Build image if needed and run inside a container (macOS)

The socket is created at tests/sockets/<sim-id>.sock.

Connecting to the simulation

From Linux (or inside the container)

use std::os::unix::net::UnixStream;
let socket = UnixStream::connect("tests/sockets/sim.sock")?;

From macOS

Unix sockets don't cross the OS boundary. start-sim --container automatically starts a TCP bridge inside the container and publishes it to 127.0.0.1 on your Mac:

TCP bridge ready: connect from macOS at 127.0.0.1:<port>

The port is stable and derived from your workspace path:

use std::net::TcpStream;
let stream = TcpStream::connect("127.0.0.1:<port>")?;

To run code that needs to reach the socket from macOS, use exec to run it inside the container instead:

cargo xtask exec -- cargo test --test my_integration_test
cargo xtask exec -- cargo run --example my_example

Integration tests

use std::collections::HashSet;
use std::path::Path;

let tests_dir = Path::new(concat!(env!("CARGO_MANIFEST_DIR"), "/tests/sockets"));
let (mut processes, socket_path) =
    babble_bridge::spawn_zephyr_rpc_server_with_socat(tests_dir, "my_test");

// Connect to socket_path with a UnixStream, run test logic, then:
processes.search_stdout_for_strings(HashSet::from([
    "<inf> nrf_ps_server: Initializing RPC server",
]));

Enable verbose output to see labelled per-process logs during a test run:

cargo test --features babble-bridge/sim-log

Tests require Linux — run them inside the container on macOS:

cargo xtask exec -- cargo test --test my_integration_test

Docker commands

docker-run creates a fresh container each time (no running sim). exec targets the persistent container started by start-sim --container, where the simulation socket is reachable.