.. .. Copyright (c) 2025 ZettaScale Technology .. .. This program and the accompanying materials are made available under the .. terms of the Eclipse Public License 2.0 which is available at .. http://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0 .. which is available at https://www.apache.org/licenses/LICENSE-2.0. .. .. SPDX-License-Identifier: EPL-2.0 OR Apache-2.0 .. .. Contributors: .. ZettaScale Zenoh Team, .. ************* Configuration ************* Zenoh-Pico has many run-time and compile-time configuration options. Some are passed as flags by the build system (make, cmake) while others can be modified manually. All of those options are visible in the generated `include/zenoh-pico/config.h` from a configured build or install tree. Run-time options ================ All the run-time options presented in `config.h` should be changed using the `zp_config_insert` function with the corresponding key in your application. Mode ---- Defines if a Zenoh node is a client or peer. * `Z_CONFIG_MODE_KEY`: The index of the option in the config table. * `Z_CONFIG_MODE_CLIENT`: The string value representing client mode. * `Z_CONFIG_MODE_PEER`: The string value representing peer mode. * `Z_CONFIG_MODE_DEFAULT`: The default value for client or peer mode. Connect ------- Defines one or multiple endpoints a node will connect to. * `Z_CONFIG_CONNECT_KEY`: The index of the option in the config table. * `Z_CONFIG_CONNECT_TIMEOUT_KEY`: Timeout, in milliseconds, dedicated to establishing configured connect locators. * `Z_CONFIG_CONNECT_TIMEOUT_DEFAULT`: The default timeout value for configured connect locators. * `Z_CONFIG_CONNECT_EXIT_ON_FAILURE_KEY`: Whether `z_open` should fail when configured connect locators cannot all be established. * `Z_CONFIG_CONNECT_EXIT_ON_FAILURE_CLIENT_DEFAULT`: The default exit-on-failure value for client mode. * `Z_CONFIG_CONNECT_EXIT_ON_FAILURE_PEER_DEFAULT`: The default exit-on-failure value for peer mode. .. warning:: `Z_CONFIG_CONNECT_TIMEOUT_KEY` and `Z_CONFIG_CONNECT_EXIT_ON_FAILURE_KEY` are currently unstable, are only available when `Z_FEATURE_UNSTABLE_API` is enabled, and may be changed in a future release. `Z_CONFIG_CONNECT_TIMEOUT_KEY` accepts the following values: * `0`: no retry, try each locator once. * `>0`: retry retryable connect failures until the timeout expires. * `-1`: retry indefinitely. The default connect timeout is `0`. `Z_CONFIG_CONNECT_EXIT_ON_FAILURE_KEY` accepts `true` or `false`. Its default value is `true` in client mode and `false` in peer mode. In client mode, configured connect locators are alternatives. Zenoh-Pico tries them until one succeeds or the configured timeout expires. Client mode always requires at least one connect locator to succeed before `z_open` returns successfully. Setting `Z_CONFIG_CONNECT_EXIT_ON_FAILURE_KEY` to `false` does not allow a client session to open without a transport. In peer mode, `z_open` also requires a primary transport before returning successfully. The primary transport is established either by opening the configured listen locator or by connecting to one configured connect locator. Once the primary transport is open, remaining connect locators are added as peers. `Z_CONFIG_CONNECT_EXIT_ON_FAILURE_KEY` controls whether failures while connecting configured peer locators are tolerated. If it is `true`, non-retryable connect errors fail immediately. Retryable connect errors are retried according to `Z_CONFIG_CONNECT_TIMEOUT_KEY`; if the timeout expires before the required connectivity is established, `z_open` fails. If it is `false`, peer connections that are still failing may continue retrying from the transport task until the configured connect timeout expires. With `Z_FEATURE_MULTI_THREAD` enabled this task runs in the background; otherwise it progresses when the application spins the session tasks. Listen ------ Defines a single endpoint a node will listen on. * `Z_CONFIG_LISTEN_KEY`: The index of the option in the config table. * `Z_CONFIG_LISTEN_TIMEOUT_KEY`: Timeout, in milliseconds, dedicated to opening the configured listen locator. * `Z_CONFIG_LISTEN_TIMEOUT_DEFAULT`: The default timeout value for the configured listen locator. * `Z_CONFIG_LISTEN_EXIT_ON_FAILURE_KEY`: Whether `z_open` should fail when the configured listen locator cannot be opened. * `Z_CONFIG_LISTEN_EXIT_ON_FAILURE_DEFAULT`: The default exit-on-failure value for the configured listen locator. .. warning:: `Z_CONFIG_LISTEN_TIMEOUT_KEY` and `Z_CONFIG_LISTEN_EXIT_ON_FAILURE_KEY` are currently unstable, are only available when `Z_FEATURE_UNSTABLE_API` is enabled, and may be changed in a future release. Zenoh-Pico supports a single configured listen locator. Configuring more than one listen locator causes `z_open` to fail. `Z_CONFIG_LISTEN_TIMEOUT_KEY` accepts the following values: * `0`: no retry, try opening the listen locator once. * `>0`: retry retryable listen failures until the timeout expires. * `-1`: retry indefinitely. The default listen timeout is `0`. `Z_CONFIG_LISTEN_EXIT_ON_FAILURE_KEY` accepts `true` or `false`. Its default value is `true`. If `Z_CONFIG_LISTEN_EXIT_ON_FAILURE_KEY` is `true`, non-retryable listen errors fail immediately. Retryable listen errors are retried according to `Z_CONFIG_LISTEN_TIMEOUT_KEY`; if the timeout expires before the listen locator is opened, `z_open` fails. In peer mode, if listening fails and `Z_CONFIG_LISTEN_EXIT_ON_FAILURE_KEY` is `false`, Zenoh-Pico may still open the session by connecting to a configured connect locator. If no listen or connect locator establishes a primary transport, `z_open` fails. TLS --- With `Z_FEATURE_LINK_TLS` enabled, configure TLS using the following keys: * `Z_CONFIG_TLS_ROOT_CA_CERTIFICATE_KEY`: Path to the CA bundle used to verify remote certificates (required). * `Z_CONFIG_TLS_ROOT_CA_CERTIFICATE_BASE64_KEY`: Base64-encoded CA bundle (inline alternative to the file path). * `Z_CONFIG_TLS_LISTEN_PRIVATE_KEY_KEY`: Path to the listener private key used while listening for TLS peers (required for peers). * `Z_CONFIG_TLS_LISTEN_PRIVATE_KEY_BASE64_KEY`: Base64-encoded listener private key. * `Z_CONFIG_TLS_LISTEN_CERTIFICATE_KEY`: Path to the listener certificate presented to clients (required for peers). * `Z_CONFIG_TLS_LISTEN_CERTIFICATE_BASE64_KEY`: Base64-encoded listener certificate. * `Z_CONFIG_TLS_ENABLE_MTLS_KEY`: Set to `true`/`1`/`yes`/`on` to require client certificates (mutual TLS); defaults to disabled. * `Z_CONFIG_TLS_CONNECT_PRIVATE_KEY_KEY`: Path to the client private key (required when mTLS is enabled). * `Z_CONFIG_TLS_CONNECT_PRIVATE_KEY_BASE64_KEY`: Base64-encoded client private key. * `Z_CONFIG_TLS_CONNECT_CERTIFICATE_KEY`: Path to the client certificate (required when mTLS is enabled). * `Z_CONFIG_TLS_CONNECT_CERTIFICATE_BASE64_KEY`: Base64-encoded client certificate. * `Z_CONFIG_TLS_VERIFY_NAME_ON_CONNECT_KEY`: Set to `false`/`0`/`no`/`off` to skip CN/SAN hostname verification; defaults to enabled. Scouting -------- Scouting is used when a node isn't provided with a connect or listen endpoint. Defines if and how the node will do the scouting. * `Z_CONFIG_MULTICAST_SCOUTING_KEY`: The index of the option in the config table. * `Z_CONFIG_MULTICAST_SCOUTING_DEFAULT`: Default value of run-time scouting activation. * `Z_CONFIG_MULTICAST_LOCATOR_KEY`: The index of the option in the config table. * `Z_CONFIG_MULTICAST_LOCATOR_DEFAULT`: Default value of endpoint use for scouting. * `Z_CONFIG_SCOUTING_TIMEOUT_KEY`: The index of the option in the config table. * `Z_CONFIG_SCOUTING_TIMEOUT_DEFAULT`: Default value for scouting timeout in milliseconds. * `Z_CONFIG_SCOUTING_WHAT_KEY`: The index of the option in the config table. * `Z_CONFIG_SCOUTING_WHAT_DEFAULT`: Default value for scouting node types as a bitmask, see :c:type:`z_whatami_t` Session id ---------- Define a custom value for the session id. Otherwise it will be random. * `Z_CONFIG_SESSION_ZID_KEY`: The index of the option in the config table. Unused ------ The following options are not currently in use, but might be in the future. * `Z_CONFIG_ADD_TIMESTAMP_KEY`: The index of the option in the config table. * `Z_CONFIG_ADD_TIMESTAMP_DEFAULT`: Default value for automatic timestamps. * `Z_CONFIG_USER_KEY`: The index of the option in the config table. * `Z_CONFIG_PASSWORD_KEY`: The index of the option in the config table. Manual compile-time options =========================== These options can be changed manually in `config.h.in` if your build system invokes zenoh-pico's own CMake. * `Z_ZID_LENGTH`: Length of session ids generated by zenoh-pico, in bytes. * `Z_PROTO_VERSION`: Id used to identify the Zenoh wire protocol version, DO NOT MODIFY. * `Z_TRANSPORT_LEASE_EXPIRE_FACTOR`: Ratio used to calculate the interval for sending keep alive messages. * `Z_JOIN_INTERVAL`: Time to wait before sending a new join message, in milliseconds, multicast transport only. * `Z_SN_RESOLUTION`: Length of the packet serial number as enum value (0: 8bits, 1: 16 bits, 2: 32 bits, 3: 64 bits) * `Z_REQ_RESOLUTION`: Length of the request id as enum value (0: 8bits, 1: 16 bits, 2: 32 bits, 3: 64 bits) * `Z_RX_CACHE_SIZE`: Width of the rx cache, when activated. * `Z_GET_TIMEOUT_DEFAULT`: Default value for a request timeout, in milliseconds. * `Z_LISTEN_MAX_CONNECTION_NB`: Maximum number of connections on a listening socket. * `ZP_ASM_NOP`: Change this options if your platform doesn't have a standard `nop` instruction. Generated compile-time options ============================== All the generated options must be changed in zenoh-pico's CMake (beware of CMake's cache) or by passing them as flags when calling zenoh-pico's CMake. * `Z_FRAG_MAX_SIZE`: Size of the defragmentation buffer, in bytes. Any packet bigger than this cannot be received by the node. * `Z_BATCH_UNICAST_SIZE`: Size of the unicast packet buffers, in bytes. Any packet bigger than this will be fragmented if possible. * `Z_BATCH_MULTICAST_SIZE`: Size of the multicast packet buffers, in bytes. Any packet bigger than this will be fragmented if possible. * `Z_CONFIG_SOCKET_TIMEOUT`: Timeout for socket options, if applicable, in milliseconds. * `Z_TRANSPORT_LEASE`: Maximum time without receiving messages from a connection before closing it, in milliseconds. * `Z_TRANSPORT_ACCEPT_TIMEOUT`: Link accept timeout in P2P mode in milliseconds (maximum amount of time the listening peer would wait to receive a response). * `Z_TRANSPORT_CONNECT_TIMEOUT`: Link connect timeout in milliseconds (maximum amount of time the connecting peer would wait to receive a response). * `Z_FEATURE_TCP_NODELAY`: (DEFAULT: ON) Toggle the `TCP_NODELAY` socket option that disables Nagle's algorithm as it can cause latency spikes. * `Z_FEATURE_AUTO_RECONNECT`: (DEFAULT: ON) Toggle the auto reconnection feature. * `Z_FEATURE_MULTICAST_DECLARATIONS`: (DEFAULT: OFF) Toggle multicast declarations. It lets nodes declare key expressions and activate write filtering but requires each node to send all the declarations every time a new node join the network. * `Z_FEATURE_RX_CACHE`: (DEFAULT: OFF) Toggle LRU cache on the Rx side, improves throughput at the cost of heap memory. * `Z_FEATURE_BATCH_TX_MUTEX`: (DEFAULT: OFF) Toggle tx mutex lock at a batch level instead of at a message level. Improves throughput at the risk of losing connection as it prevents session to send keep alive messages. * `Z_FEATURE_BATCH_PEER_MUTEX`: (DEFAULT: OFF) Toggle peer mutex lock at a batch level instead of at a message level. Prevents reception of messages from peers while batching is active, may also trigger loss of connection. The following options are here to reduce binary sizes for users that don't need those features but need the extra memory. * `Z_FEATURE_UNSTABLE_API`: (DEFAULT: OFF) Toggle compilation of unstable API functions. * `Z_FEATURE_CONNECTIVITY`: (DEFAULT: OFF) Toggle compilation of connectivity status/events API functions. This feature requires `Z_FEATURE_UNSTABLE_API`. * `Z_FEATURE_MULTI_THREAD`: (DEFAULT: ON) Toggle compilation of multi thread capabilities. Will limit the library to single thread only without this. * `Z_FEATURE_PUBLICATION`: (DEFAULT: ON) Toggle compilation of publication API functions, the library can't publish without this. * `Z_FEATURE_ADVANCED_PUBLICATION`: (DEFAULT: OFF) Toggle compilation of advanced publication API functions. * `Z_FEATURE_SUBSCRIPTION`: (DEFAULT: ON) Toggle compilation of subscription API functions, the library can't subscribe without this. * `Z_FEATURE_ADVANCED_SUBSCRIPTION`: (DEFAULT: OFF) Toggle compilation of advanced subscription API functions. * `Z_FEATURE_QUERY`: (DEFAULT: ON) Toggle compilation of query API functions, the library can't get/query without this. * `Z_FEATURE_QUERYABLE`: (DEFAULT: ON) Toggle compilation of queryable API functions, the library can't reply to queries without this. * `Z_FEATURE_SCOUTING`: (DEFAULT: ON) Toggle compilation of scouting API functions, the library can't scout without this. * `Z_FEATURE_LIVELINESS`: (DEFAULT: ON) Toggle compilation of liveliness API functions, the library can't declare liveliness tokens without this. * `Z_FEATURE_BATCHING`: (DEFAULT: ON) Toggle compilation of batching API functions, the library can't batch messages without this. * `Z_FEATURE_MATCHING`: (DEFAULT: ON) Toggle compilation of matching API functions,the library can't do matching without this. * `Z_FEATURE_INTEREST`: (DEFAULT: ON) Toggle compilation of interest protocol, the library can't do write filtering without this. * `Z_FEATURE_ENCODING_VALUES`: (DEFAULT: ON) Toggle compilation of encoding values constants, the library will not provide encoding constants without this. * `Z_FEATURE_SESSION_CHECK`: (DEFAULT: ON) Toggle session reference check. Dangerous if entities like publishers or queriers are used after a session is closed. * `Z_FEATURE_LOCAL_SUBSCRIBER`: (DEFAULT: OFF) Toggle local subscriber feature, subscribers will not be triggered by local publications without this. * `Z_FEATURE_LOCAL_QUERYABLE`: (DEFAULT: OFF) Toggle local queryable feature, queryables will not be triggered by local queries without this. * `Z_FEATURE_FRAGMENTATION`: (DEFAULT: ON) Toggle fragmentation feature, the library can't send or receive fragmented messages without this. * `Z_FEATURE_MULTICAST_TRANSPORT`: (DEFAULT: ON) Toggle multicast transport feature, the library can't handle multicast connections without this. * `Z_FEATURE_UNICAST_TRANSPORT`: (DEFAULT: ON) Toggle unicast transport feature, the library can't handle unicast connections without this. * `Z_FEATURE_RAWETH_TRANSPORT`: (DEFAULT: OFF) Toggle compilation of raw ethernet transport, the library can't handle raw ethernet connections without this. * `Z_FEATURE_UNICAST_PEER`: (DEFAULT: ON) Toggle unicast peer feature, the library can't do peer to peer unicast without this. * `Z_FEATURE_LINK_TCP`: (DEFAULT: ON) Toggle compilation of TCP link support. * `Z_FEATURE_LINK_UDP_MULTICAST`: (DEFAULT: ON) Toggle compilation of UDP multicast link support. * `Z_FEATURE_LINK_UDP_UNICAST`: (DEFAULT: ON) Toggle compilation of UDP unicast link support. * `Z_FEATURE_LINK_BLUETOOTH`: (DEFAULT: OFF) Toggle compilation of Bluetooth link support. * `Z_FEATURE_LINK_WS`: (DEFAULT: OFF) Toggle compilation of WebSocket link support. * `Z_FEATURE_LINK_SERIAL`: (DEFAULT: OFF) Toggle compilation of Serial link support. * `Z_FEATURE_LINK_SERIAL_USB`: (DEFAULT: OFF) Toggle compilation of Serial USB link support. * `Z_FEATURE_LINK_TLS`: (DEFAULT: OFF) Toggle compilation of TLS support. * `Z_FEATURE_ADMIN_SPACE`: (DEFAULT: OFF) Toggle compilation of admin space API functions. This feature requires both `Z_FEATURE_UNSTABLE_API` and `Z_FEATURE_QUERYABLE`.