-
Notifications
You must be signed in to change notification settings - Fork 5
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
readme updated: daemon run instructions added, obsolete info removed #67
Merged
+140
−73
Merged
Changes from 3 commits
Commits
Show all changes
4 commits
Select commit
Hold shift + click to select a range
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,12 @@ | ||
| { | ||
| mode: 'router', | ||
| plugins_loading: { | ||
| enabled: true, | ||
| search_dirs: ['./target/debug', '~/.zenoh/lib', '/usr/lib'] | ||
| }, | ||
| plugins: { | ||
| remote_api: { | ||
| "__config__": "zenoh-plugin-remote-api/EXAMPLE_CONFIG.json5" | ||
| } | ||
| } | ||
| } |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,104 +1,168 @@ | ||
| <img src="https://raw.githubusercontent.com/eclipse-zenoh/zenoh/master/zenoh-dragon.png" height="150"> | ||
|
|
||
| > :warning: **This is a WIP Active development project**: Experiment with with it, but it is **Not** production Ready! | ||
| > :warning: **This is a WIP Active development project**: Experiment with it, but it is **Not** production ready! | ||
|
|
||
| [](https://discord.gg/2GJ958VuHs) | ||
| [](https://opensource.org/licenses/Apache-2.0) | ||
|
|
||
| # Eclipse Zenoh Typescript / Javascript API | ||
|
|
||
| The Eclipse Zenoh: Zero Overhead Pub/sub, Store/Query and Compute. | ||
| The Eclipse Zenoh: Zero Overhead Pub/sub, Store/Query, and Compute. | ||
|
|
||
| Zenoh (pronounce _/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. | ||
| Zenoh (pronounced _/zeno/_) unifies data in motion, data at rest, and computations. It carefully blends traditional pub/sub with | ||
| geo-distributed storage, 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](http://zenoh.io) and the [roadmap](https://github.com/eclipse-zenoh/roadmap) for more detailed information. | ||
|
|
||
| --- | ||
|
|
||
| # Typescript/Javascript API | ||
| ## Typescript/Javascript API | ||
|
|
||
| This repository provides a Typscript / Javascript binding through the use of the `remote-api-plugin` in this repo. | ||
| The long term plan is to use zenoh [Zenoh written in Rust](https://github.com/eclipse-zenoh/zenoh) to target WASM. | ||
| In its current state, it is not possible to compile Zenoh (Rust) to target WASM, and will need to undergo a fair amount of refactoring before that can happen. | ||
| This repository provides a Typescript / Javascript binding through the use of the `remote-api-plugin` in this repo. | ||
| The long-term plan is to use zenoh [Zenoh written in Rust](https://github.com/eclipse-zenoh/zenoh) to target WASM. | ||
| In its current state, it is not possible to compile Zenoh (Rust) to target WASM, and it will need to undergo a fair | ||
| amount of refactoring before that can happen. | ||
|
|
||
| Docs can be accessed at [Docs Link](https://eclipse-zenoh.github.io/zenoh-ts/) | ||
|
|
||
| --- | ||
|
|
||
| ## How to build it | ||
| ## How to build and run 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. | ||
| > :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 into maintaining | ||
| compatibility between the various git repositories in the Zenoh project. | ||
|
|
||
| ## Building the Typescript project | ||
| ### Executing the `zenohd` with `zenoh-plugin-remote-api` plugin | ||
|
|
||
| 1. Make sure that the following utilities are available on your platform. | ||
| - [NPM](https://www.npmjs.com/package/npm) | ||
| - [yarn](https://classic.yarnpkg.com/lang/en/docs/install/#debian-stable) | ||
| - [Typescript](https://www.typescriptlang.org/download/) | ||
| 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. | ||
|
|
||
| 2. Navigate to the directory `zenoh-ts` | ||
| Therefore one of the methods below is recommended to ensure that plugin and router are compatible. | ||
|
|
||
| 3. Run the commands: | ||
| The file `EXAMPLE_CONFIG.json5` references the `zenoh-plugin-remote-api\EXAMPLE_CONFIG.json5` with minimal necessary set of options to run the plugin. See also full set of available options, like ssl certificate settings in `zenoh-plugin-remote-api\config.json5`. | ||
|
|
||
| ```bash | ||
| yarn install | ||
| # | ||
| yarn run build | ||
| ``` | ||
| 1. Install the latest release of `zenohd` and `zenoh-plugin-remote-api` | ||
|
|
||
| Ubuntu: | ||
|
|
||
| ```sh | ||
| 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 | ||
| ``` | ||
|
|
||
| Mac-OS: | ||
|
|
||
| ```sh | ||
| brew tap eclipse-zenoh/homebrew-zenoh | ||
| brew install zenoh | ||
| brew install zenoh-plugin-remote-api | ||
| ``` | ||
|
|
||
| Run the installed zenoh router with example config | ||
|
|
||
| ```sh | ||
| zenohd --config EXAMPLE_CONFIG.json5 | ||
| ``` | ||
|
|
||
| Expected output should be something similar to: | ||
|
|
||
| ```txt | ||
| 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: | ||
|
|
||
| ## Building the Rust Plugin | ||
| Build the plugin `zenoh-plugin-remote-api` | ||
|
|
||
| 1. Make sure that the following utilities are available on your platform. | ||
| - [Cargo + Rust Compiler](https://rustup.rs/) | ||
| ```sh | ||
| cargo build | ||
| ``` | ||
|
|
||
| 2. Navigate to `zenoh-plugin-remote-api` | ||
| Build and run the zenohd from the same sources which were used for the plugin. | ||
| The zenohd dependency is specified in the `[workspace.metadata.bin]` section in Cargo.toml which is processed by the 3rd party tool [cargo-run-bin](https://crates.io/crates/cargo-run-bin). | ||
|
|
||
| 3. Run `cargo build` | ||
| ```sh | ||
| cargo install cargo-run-bin | ||
| cargo bin zenohd --config EXAMPLE_CONFIG.json5 | ||
| ``` | ||
|
|
||
| ## **Examples of usage** | ||
| Expected output should be something similar to: | ||
|
|
||
| ### Running the Rust Plugin | ||
| ```txt | ||
| 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/... | ||
| ``` | ||
|
|
||
| Prerequisites: | ||
| - You have a zenoh router (`zenohd`) installed, and the `zenoh_plugin_remote_api` library file is available in `~/.zenoh/lib`. | ||
| ### Building the library | ||
|
|
||
| ### **Setup via a JSON5 configuration file** | ||
| 1. Make sure that the following utilities are available on your platform. | ||
|
|
||
| - Create a `zenoh.json5` configuration file containing for example: | ||
| ```json5 | ||
| { | ||
| plugins: { | ||
| // configuration of "storage_manager" plugin: | ||
| remote_api: { | ||
| "websocket_port": "10000", | ||
| // secure_websocket configuration is optional | ||
| "secure_websocket": { | ||
| "certificate_path" : "/path/to/certificate", | ||
| "private_key_path" : "/path/to/private_key" | ||
| } | ||
| } | ||
| // Optionally, add the REST plugin | ||
| rest: { http_port: 8000 } | ||
| } | ||
| } | ||
| ``` | ||
| - Run the zenoh router with: | ||
| `zenohd -c zenoh.json5` | ||
| - [NPM](https://www.npmjs.com/package/npm) | ||
| - [yarn](https://classic.yarnpkg.com/lang/en/docs/install/#debian-stable) | ||
| - [Typescript](https://www.typescriptlang.org/download/) | ||
|
|
||
| ## Adding Typescript to your application | ||
| 2. Navigate to the directory `zenoh-ts` | ||
|
|
||
| 3. Run the commands: | ||
|
|
||
| The TypeScript library can be install from the command line: | ||
| ```sh | ||
| yarn install | ||
| yarn run build | ||
| ``` | ||
|
|
||
| `npm install @eclipse-zenoh/[email protected]` | ||
| ### Build and run the command line examples | ||
|
|
||
| Or added via package.json | ||
| This library is currently compatible with browsers, but not with NodeJS due to websocket library limitations. | ||
| To run the command line examples use the javascript runtime [deno](https://deno.com/) which is expected to be consistent with the browser. | ||
|
|
||
| `"@eclipse-zenoh/zenoh-ts": "0.0.8" ` | ||
| 1. Install [deno](https://deno.com/) | ||
| 2. Navigate to the `zenoh-ts/examples/deno` directory | ||
| 3. Install the `zenoh-ts` library by running `yarn install` | ||
| 4. Run zenohd with the remote_api plugin, configured to websocket port 10000, as described above | ||
| 5. Run the examples by running `yarn example <PATH TO EXAMPLE>`, i.e. `yarn example src/z_sub.ts` | ||
|
|
||
| Note: In order to add this library to your project you must log into the github npm repository, | ||
| please refer to this link for more information [Accessing github NPM](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-npm-registry#authenticating-with-a-personal-access-token) | ||
| To run publisher and subscriber examples: | ||
|
|
||
| ```sh | ||
| yarn example src/z_pub.rs | ||
| ``` | ||
|
|
||
| [zenoh]: https://github.com/eclipse-zenoh/zenoh | ||
| ```sh | ||
| yarn example src/z_sub.rs | ||
| ``` | ||
|
|
||
| The subscriber should start to receive messages from publisher: | ||
|
|
||
| ```text | ||
| >> [Subscriber] Received PUT ('demo/example/zenoh-ts-pub': '[0] 122,101,110,111,104') | ||
| >> [Subscriber] Received PUT ('demo/example/zenoh-ts-pub': '[1] 122,101,110,111,104') | ||
| >> [Subscriber] Received PUT ('demo/example/zenoh-ts-pub': '[2] 122,101,110,111,104') | ||
| ``` | ||
|
|
||
| This will start an instance of Deno running the example. | ||
| The application will attempt to connect to a `websocket_port` : `10000` where the Remote API plugin is expected to be running. | ||
|
|
||
| ### Adding Typescript to your application | ||
|
|
||
| The latest version of zenoh-ts library can be installed from npm: | ||
|
|
||
| ```sh | ||
| npm install @eclipse-zenoh/zenoh-ts | ||
| ``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,16 +1,3 @@ | ||
| { | ||
| mode: 'router', | ||
| plugins_loading: { | ||
| enabled: true, | ||
| search_dirs: ['./target/debug', '~/.zenoh/lib'] | ||
| }, | ||
| plugins: { | ||
| remote_api: { | ||
| websocket_port: '10000', | ||
| secure_websocket: { | ||
| certificate_path: 'path/to/certificate_path', | ||
| private_key_path: 'path/to/private_key_path' | ||
| } | ||
| } | ||
| } | ||
| websocket_port: '10000' | ||
| } |
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Should we not also mention that the user can add configuration for certificates for secure websockets here ?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The goal was to allow to user to run the examples immediately, without making any changes. The example with certificates is in "config.json5" file, I'll add reference to it to readme.
There is no way to comment out part of json config :-(