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 include/zenoh-pico/config.h.

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.

Listen

Defines a single endpoint a node will listen on.

  • Z_CONFIG_LISTEN_KEY: The index of the option in the config table.

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 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 either in config.h directly or 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_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_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_SUBSCRIPTION: (DEFAULT: ON) Toggle compilation of subscription API functions, the library can’t subscribe without this.

  • 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: ON) Toggle local subscriber feature, subscribers will not be triggered by local publications 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.