nros/guide/configuration.rs
1//! # Configuration
2//!
3//! ## Runtime environment variables
4//!
5//! [`ExecutorConfig::from_env()`](crate::env::ExecutorConfigEnvExt::from_env) reads these at startup:
6//!
7//! | Variable | Description | Default |
8//! |----------|-------------|---------|
9//! | `ROS_DOMAIN_ID` | ROS 2 domain ID | `0` |
10//! | `NROS_LOCATOR` | Router address (`tcp/…`, `udp/…`, or `tls/…`) | `tcp/127.0.0.1:7447` |
11//! | `NROS_SESSION_MODE` | Session mode: `client` or `peer` | `client` |
12//! | `ZENOH_TLS_ROOT_CA_CERTIFICATE` | Path to CA certificate (PEM) | — |
13//! | `ZENOH_TLS_ROOT_CA_CERTIFICATE_BASE64` | Base64-encoded CA cert (bare-metal) | — |
14//!
15//! ## Buffer tuning (build-time)
16//!
17//! Set these environment variables **before** `cargo build`. After
18//! changing a value, run `cargo clean -p zpico-sys` (or `xrce-sys`) to
19//! force a rebuild.
20//!
21//! **Zenoh backend (`ZPICO_*`):**
22//!
23//! | Variable | Description | Posix | Embedded |
24//! |----------|-------------|-------|----------|
25//! | `NROS_ZENOH_FRAG_MAX_SIZE` | Max reassembled message size | 65536 | 2048 |
26//! | `NROS_ZENOH_BATCH_UNICAST_SIZE` | Max unicast batch before fragmentation | 65536 | 1024 |
27//! | `NROS_ZENOH_BATCH_MULTICAST_SIZE` | Max multicast batch size | 8192 | 1024 |
28//! | `NROS_SUBSCRIBER_BUFFER_SIZE` | Per-subscriber buffer in zenoh shim | 1024 | 1024 |
29//! | `NROS_SERVICE_INBOX_BYTES` | Request slot of a user service server's inbox ring (zenoh); `ZPICO_SERVICE_BUFFER_SIZE` is its one-release alias | 1024 | 1024 |
30//! | `NROS_SERVICE_INBOX_DEPTH` | Requests a user service server holds before dropping the newest | 4 | 4 |
31//! | `NROS_ACTION_INBOX_BYTES` | Request slot of an action server queryable's inbox ring | `NROS_SERVICE_INBOX_BYTES` | ditto |
32//! | `NROS_ACTION_INBOX_DEPTH` | Requests an action server queryable holds (the twin of `ZPICO_MAX_PENDING_REPLIES`) | 4 | 4 |
33//!
34//! **XRCE-DDS backend (`XRCE_*`):**
35//!
36//! | Variable | Description | Posix | Embedded |
37//! |----------|-------------|-------|----------|
38//! | `XRCE_TRANSPORT_MTU` | Transport MTU (also sizes stream buffers) | 4096 | 512 |
39//! | `XRCE_BUFFER_SIZE` | Default of the three receive families below | 1024 | 1024 |
40//! | `XRCE_SUBSCRIBER_BUFFER_SIZE` | Subscriber ring entry | `XRCE_BUFFER_SIZE` | ditto |
41//! | `XRCE_SERVICE_REQUEST_BUFFER_SIZE` | Service-server request entry | `XRCE_BUFFER_SIZE` | ditto |
42//! | `XRCE_SERVICE_REPLY_BUFFER_SIZE` | Service-client reply slot | `XRCE_BUFFER_SIZE` | ditto |
43//! | `XRCE_STREAM_HISTORY` | Reliable stream history depth (>= 2) | 4 | 4 |
44//!
45//! The zenoh service inbox is per FAMILY since phase-461 W1 (issue 1352): a
46//! user service and an action server queryable each take a slot size and a
47//! ring depth of their own, and the parameter and lifecycle services bring
48//! their own ring, sized by `nros-node` from the contract's declared
49//! parameters. An image that states nothing gets the one table it had.
50//!
51//! The three families were one number until phase-454 W6.b, so a subscriber
52//! ring entry paid for the largest type a SERVICE carried, 32 x 8 times over.
53//! Two of them are also DERIVED from what the image declares when it declares
54//! it (RFC-0100): the subscriber entry takes the largest wire bound over the
55//! declared subscriptions and `XRCE_STREAM_HISTORY` drops to the protocol
56//! floor of 4 when no endpoint declares `reliability = reliable`. Stating
57//! either here still wins.
58//!
59//! **Core (`NROS_*`, C API only):**
60//!
61//! | Variable | Description | Default |
62//! |----------|-------------|---------|
63//! | `NROS_MAX_PARAMETERS` | Max parameters in parameter server | 32 |
64//!
65//! Example — increase zenoh defrag to 128 KB for large point clouds:
66//!
67//! ```bash
68//! NROS_ZENOH_FRAG_MAX_SIZE=131072 cargo build --features rmw-zenoh,platform-posix
69//! ```