Eclipse Zenoh

Eclipse Zenoh: Zero Overhead Pub/sub, Store/Query and Compute.

Zenoh (pronounced /zeno/) unifies data in motion, data at rest, and computations. It carefully blends traditional pub/sub with geo-distributed storages, queries, and computations, while retaining a level of time and space efficiency that is well beyond any of the mainstream stacks.

Check the website zenoh.io and the roadmap for more detailed information.

Remote API Plugin

In Zenoh, the remote API plugin is a library loaded into a Zenohd instance at startup, which allows the creation of a Session and declaration of Zenoh resources (Subscribers, Publishers, Queryables) remotely via WebSockets, for runtime environments where it is currently unsupported to run a Zenoh binary. The Remote API was designed to support the TypeScript Zenoh bindings running in a browser.

Examples of usage

Prerequisites:

• You have a Zenoh router (zenohd) installed, and the libzenoh_plugin_remote_api.so library file is available in ~/.zenoh/lib or ~/target/debug.

Setup via a JSON5 configuration file

• Create a zenoh.json5 configuration file containing, for example:

  {
  mode: "router",
      plugins_loading: {
          enabled: true,
          search_dirs: ["./target/debug", "~/.zenoh/lib"],
      },
      plugins: {
          remote_api: {
              "websocket_port": "10000",
          },
      },
  }
  
  

• Run the Zenoh router with: zenohd -c EXAMPLE_CONFIG.json5

How to build it

:warning: WARNING :warning: : Zenoh and its ecosystem are under active development. When you build from git, make sure you also build from git any other Zenoh repository you plan to use (e.g. binding, plugin, backend, etc.). It may happen that some changes in git are not compatible with the most recent packaged Zenoh release (e.g. deb, docker, pip). We put particular effort in maintaining compatibility between the various git repositories in the Zenoh project.

First, install Cargo and Rust. If you already have the Rust toolchain installed, make sure it is up-to-date with:

rustup update

:warning: WARNING :warning: : As Rust doesn't have a stable ABI, the backend library should be built with the exact same Rust version as zenohd, and using the same version (or commit number) for the zenoh dependency as zenohd. Otherwise, incompatibilities in memory mapping of shared types between zenohd and the library can lead to a "SIGSEGV" crash.

The zenohd router and its plugins should be built with the same Zenoh sources, the same version of the Rust compiler, and with the same set of features. This requirement exists because the router and plugins share common Rust structures, and Rust doesn't guarantee ABI compatibility of the memory representation of these structures.

Therefore, one of the methods below is recommended to ensure that the plugin and router are compatible.

The file EXAMPLE_CONFIG.json5 references the zenoh-plugin-remote-api\EXAMPLE_CONFIG.json5 with the minimal necessary set of options to run the plugin. See also the full set of available options, such as SSL certificate settings in zenoh-plugin-remote-api\config.json5.

1. Install the latest release of zenohd and zenoh-plugin-remote-api

   Ubuntu:

   echo "deb [trusted=yes] https://download.eclipse.org/zenoh/debian-repo/ /" | sudo tee -a /etc/apt/sources.list.d/zenoh.list > /dev/null
   sudo apt update
   sudo apt install zenohd
   sudo apt install zenoh-plugin-remote-api
   

   macOS:

   brew tap eclipse-zenoh/homebrew-zenoh
   brew install zenoh
   brew install zenoh-plugin-remote-api
   

   Run the installed Zenoh router with the example config:

   zenohd --config EXAMPLE_CONFIG.json5
   

   The expected output should be something similar to:

   zenohd: zenohd v1.0.3 built with rustc 1.75.0 (82e1608df 2023-12-21)
   zenoh::net::runtime: Using ZID: f7bc54e0941036422ec08ebac6fbdb40
   zenoh::api::loader: Loading plugin "remote_api" zenoh::api::loader: Starting
   plugin "remote_api" zenoh::api::loader: Successfully started plugin remote_api
   from "/usr/lib/libzenoh_plugin_remote_api.so" zenoh::api::loader: Finished
   loading plugins zenoh::net::runtime::orchestrator: Zenoh can be reached at:
   tcp/....
   

2. Build both the plugin and the router from the sources manually:

   Build the plugin zenoh-plugin-remote-api:

   cargo build
   

   Build and run zenohd from the same sources used for the plugin. The zenohd dependency is specified in the [workspace.metadata.bin] section in Cargo.toml, which is processed by the third-party tool cargo-run-bin.

   The zenohd binary is built into the .bin directory local to the project. If necessary, remove the .bin directory with rm -rf .bin to rebuild it, as the cargo-run-bin tool does not handle this automatically.

   cargo install cargo-run-bin
   cargo bin zenohd --config EXAMPLE_CONFIG.json5
   

   The expected output should be something similar to:

   zenohd: zenohd vc764bf9b built with rustc 1.75.0 (82e1608df 2023-12-21)
   zenoh::net::runtime: Using ZID: bb3fb16628f57e92f92accf2f5c81511
   zenoh::api::loader: Loading  plugin "remote_api"
   zenoh::api::loader: Starting  plugin "remote_api"
   zenoh::api::loader: Successfully started plugin remote_api from "./target/debug\\zenoh_plugin_remote_api.dll"
   zenoh::api::loader: Finished loading plugins
   zenoh::net::runtime::orchestrator: Zenoh can be reached at: tcp/...