nros/guide/troubleshooting.rs
1//! # Troubleshooting
2//!
3//! ## Message too large / truncated
4//!
5//! Messages pass through multiple buffer layers. A message must fit every
6//! layer to be delivered intact:
7//!
8//! | Layer | Env var | Posix default |
9//! |-------|---------|---------------|
10//! | Defragmentation | `NROS_ZENOH_FRAG_MAX_SIZE` | 65536 |
11//! | Batch size | `NROS_ZENOH_BATCH_UNICAST_SIZE` | 65536 |
12//! | Shim buffer | `NROS_SUBSCRIBER_BUFFER_SIZE` | 1024 |
13//! | User receive buffer | — (const generic) | 1024 |
14//!
15//! For large messages, increase the transport limits (set before `cargo
16//! build`) and size the per-entity buffer via the builder's `.rx_buffer::<N>()`:
17//!
18//! ```ignore
19//! // 4 KB receive buffer
20//! executor.node_mut(node).subscription("/topic").typed::<MyMsg>()
21//! .rx_buffer::<4096>().build(|msg| { ... })?;
22//! ```
23//!
24//! ## zenoh version mismatch
25//!
26//! zenoh-pico and zenohd must be the same version (1.6.2). Symptoms:
27//! `z_publisher_put failed: -100` (`_Z_ERR_TRANSPORT_TX_FAILED`) followed
28//! by `-73` (`_Z_ERR_SESSION_CLOSED`).
29//!
30//! The router is the one ROS ships: `ros2 run rmw_zenoh_cpp rmw_zenohd`.
31//! nano-ros vendors none (RFC-0075), and the old `just build-zenohd` recipe
32//! was retired with the vendored copy.
33//!
34//! ## Build issues
35//!
36//! - **Submodule not found** — init that ONE submodule, scoped:
37//! `git submodule update --init packages/rmw/zenoh/zpico-sys/zenoh-pico`.
38//! Never `--recursive` on nano-ros — the transitive closure is large and
39//! mostly irrelevant to any one task. `nros setup <board> --rmw zenoh`
40//! provisions it for you, shallow, and is the preferred route.
41//! - **CMake cache stale** (changed env vars not taking effect) — run
42//! `cargo clean -p zpico-sys` then rebuild
43//!
44//! ## zenoh-pico error codes
45//!
46//! | Code | Name | Meaning |
47//! |------|------|---------|
48//! | -3 | `_Z_ERR_TRANSPORT_OPEN_FAILED` | Cannot connect to router |
49//! | -73 | `_Z_ERR_SESSION_CLOSED` | Session closed after failure |
50//! | -78 | `_Z_ERR_SYSTEM_OUT_OF_MEMORY` | Allocation failed |
51//! | -100 | `_Z_ERR_TRANSPORT_TX_FAILED` | Transport transmission failed |
52//! | -128 | `_Z_ERR_GENERIC` | Generic error |