From e40c23640fdc927edf500cdcba28f123ee48aac1 Mon Sep 17 00:00:00 2001 From: "ChenYing Kuo (CY)" Date: Wed, 18 Dec 2024 17:09:46 +0800 Subject: [PATCH] Add CI for checking markdown format. (#837) Signed-off-by: ChenYing Kuo --- .github/workflows/build-check.yaml | 9 ++ .markdownlint.yaml | 6 + README.md | 195 ++++++++++++++++++----------- 3 files changed, 136 insertions(+), 74 deletions(-) create mode 100644 .markdownlint.yaml diff --git a/.github/workflows/build-check.yaml b/.github/workflows/build-check.yaml index c83c2c969..f9881bbcb 100644 --- a/.github/workflows/build-check.yaml +++ b/.github/workflows/build-check.yaml @@ -295,3 +295,12 @@ jobs: CMAKE_GENERATOR=Ninja ASAN=ON make python3 ./build/tests/no_router.py timeout-minutes: 5 + + markdown_lint: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: DavidAnson/markdownlint-cli2-action@v18 + with: + config: '.markdownlint.yaml' + globs: '**/README.md' diff --git a/.markdownlint.yaml b/.markdownlint.yaml new file mode 100644 index 000000000..12f737945 --- /dev/null +++ b/.markdownlint.yaml @@ -0,0 +1,6 @@ +{ + "MD013": false, # Line length limitation + "MD033": false, # Enable Inline HTML + "MD041": false, # Allow first line heading + "MD045": false, # Allow Images have no alternate text +} \ No newline at end of file diff --git a/README.md b/README.md index 741fc8208..04e2e7448 100644 --- a/README.md +++ b/README.md @@ -9,6 +9,7 @@ [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) # Eclipse Zenoh + 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. @@ -16,6 +17,7 @@ Zenoh (pronounce _/zeno/_) unifies data in motion, data at rest, and computation Check the website [zenoh.io](http://zenoh.io) and the [roadmap](https://github.com/eclipse-zenoh/roadmap) for more detailed information. ------------------------------- + # Zenoh-Pico: native C library for constrained devices zenoh-pico is the [Eclipse zenoh](http://zenoh.io) implementation that targets constrained devices, offering a native C API. @@ -39,6 +41,7 @@ Currently, zenoh-pico provides support for the following (RT)OSs and protocols: Check the website [zenoh.io](http://zenoh.io) and the [roadmap](https://github.com/eclipse-zenoh/roadmap) for more detailed information. ------------------------------- + ## 1. How to install it The Eclipse zenoh-pico library is available as **Debian**, **RPM**, and **tgz** packages in the [Eclipse zenoh-pico download area](https://download.eclipse.org/zenoh/zenoh-pico/). @@ -46,16 +49,18 @@ Those packages are built using manylinux2010 x86-32 and x86-64 for compatibility There are two kind of packages: - **libzenohpico**: only contains the library file (.so) -- **libzenohpico-dev**: contains the zenoh-pico header files for development and depends on the *libzenohpico* package +- **libzenohpico-dev**: contains the zenoh-pico header files for development and depends on the _libzenohpico_ package -For other platforms - like RTOS for embedded systems / microcontrollers -, you will need to clone and build the sources. Check [below](#how-to-build-for-microcontrollers) for more details. +For other platforms - like RTOS for embedded systems / microcontrollers -, you will need to clone and build the sources. Check [below](#2. how-to-build-it) for more details. ------------------------------- + ## 2. 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 mantaining compatibility between the various git repositories in the Zenoh project. ### 2.1 Unix Environments + To build the **zenoh-pico** library, you need to ensure that [cmake](https://cmake.org) is available on your platform -- if not please install it. @@ -64,27 +69,28 @@ Once the [cmake](https://cmake.org) dependency is satisfied, just do the followi -- CMake version 3 and higher -- ```bash - $ cd /path/to/zenoh-pico - $ make - $ make install # on Linux use **sudo** + cd /path/to/zenoh-pico + make + make install # on Linux use **sudo** ``` If you want to build with debug symbols, set the `BUILD_TYPE=Debug`environment variable before to run make: + ```bash - $ cd /path/to/zenoh-pico - $ BUILD_TYPE=Debug make - $ make install # on Linux use **sudo** + cd /path/to/zenoh-pico + BUILD_TYPE=Debug make + make install # on Linux use **sudo** ``` For those that still have **CMake** version 2.8, do the following commands: ```bash - $ cd /path/to/zenoh-pico - $ mkdir build - $ cd build - $ cmake -DCMAKE_BUILD_TYPE=Release ../cmake-2.8 - $ make - $ make install # on Linux use **sudo** + cd /path/to/zenoh-pico + mkdir build + cd build + cmake -DCMAKE_BUILD_TYPE=Release ../cmake-2.8 + make + make install # on Linux use **sudo** ``` ### 2.2. Real Time Operating System (RTOS) for Embedded Systems and Microcontrollers @@ -97,6 +103,7 @@ Once the PlatformIO dependency is satisfied, follow the steps below for the tested micro controllers. #### 2.2.1. Zephyr + Note: tested with reel_board, nucleo-f767zi, nucleo-f420zi, and nRF52840 boards. A typical PlatformIO project for Zephyr framework must have the following @@ -117,28 +124,29 @@ structure: To initialize this project structure, execute the following commands: ```bash - $ mkdir -p /path/to/project_dir - $ cd /path/to/project_dir - $ platformio init -b reel_board - $ platformio run + mkdir -p /path/to/project_dir + cd /path/to/project_dir + platformio init -b reel_board + platformio run ``` Include the CMakelist.txt and prj.conf in the project_dir/zephyr folder as shown in the structure above, ```bash - $ cp /path/to/zenoh-pico/docs/zephyr/reel_board/CMakelists.txt /path/to/project_dir/zephyr/ - $ cp /path/to/zenoh-pico/docs/zephyr/reel_board/prj.conf /path/to/project_dir/zephyr/ + cp /path/to/zenoh-pico/docs/zephyr/reel_board/CMakelists.txt /path/to/project_dir/zephyr/ + cp /path/to/zenoh-pico/docs/zephyr/reel_board/prj.conf /path/to/project_dir/zephyr/ ``` and add zenoh-pico as a library by doing: ```bash - $ ln -s /path/to/zenoh-pico /path/to/project_dir/lib/zenoh-pico + ln -s /path/to/zenoh-pico /path/to/project_dir/lib/zenoh-pico ``` + or just include the following line in platformio.ini: - ``` + ```ini lib_deps = https://github.com/eclipse-zenoh/zenoh-pico ``` @@ -153,6 +161,7 @@ To build and upload the code into the board, run the following command: ``` #### 2.2.2. Arduino + Note: tested with az-delivery-devkit-v4 ESP32 board A typical PlatformIO project for Arduino framework must have the following @@ -170,19 +179,21 @@ structure: To initialize this project structure, execute the following commands: ```bash - $ mkdir -p /path/to/project_dir - $ cd /path/to/project_dir - $ platformio init -b az-delivery-devkit-v4 - $ platformio run + mkdir -p /path/to/project_dir + cd /path/to/project_dir + platformio init -b az-delivery-devkit-v4 + platformio run ``` Add zenoh-pico as a library by doing: ```bash - $ ln -s /path/to/zenoh-pico /path/to/project_dir/lib/zenoh-pico + ln -s /path/to/zenoh-pico /path/to/project_dir/lib/zenoh-pico ``` + or just include the following line in platformio.ini: - ``` + + ```ini lib_deps = https://github.com/eclipse-zenoh/zenoh-pico ``` @@ -197,6 +208,7 @@ To build and upload the code into the board, run the following command: ``` #### 2.2.3. ESP-IDF + Note: tested with az-delivery-devkit-v4 ESP32 board A typical PlatformIO project for ESP-IDF framework must have the following @@ -216,20 +228,21 @@ structure: To initialize this project structure, execute the following commands: ```bash - $ mkdir -p /path/to/project_dir - $ cd /path/to/project_dir - $ platformio init -b az-delivery-devkit-v4 - $ platformio run + mkdir -p /path/to/project_dir + cd /path/to/project_dir + platformio init -b az-delivery-devkit-v4 + platformio run ``` Add zenoh-pico as a library by doing: ```bash - $ ln -s /path/to/zenoh-pico /path/to/project_dir/lib/zenoh-pico + ln -s /path/to/zenoh-pico /path/to/project_dir/lib/zenoh-pico ``` + or just include the following line in platformio.ini: - ``` + ```ini lib_deps = https://github.com/eclipse-zenoh/zenoh-pico ``` @@ -244,6 +257,7 @@ To build and upload the code into the board, run the following command: ``` #### 2.2.4. MbedOS + Note: tested with nucleo-f747zi and nucleo-f429zi boards A typical PlatformIO project for MbedOS framework must have the following structure: @@ -259,19 +273,21 @@ A typical PlatformIO project for MbedOS framework must have the following struct To initialize this project structure, execute the following commands: ```bash - $ mkdir -p /path/to/project_dir - $ cd /path/to/project_dir - $ platformio init -b az-delivery-devkit-v4 - $ platformio run + mkdir -p /path/to/project_dir + cd /path/to/project_dir + platformio init -b az-delivery-devkit-v4 + platformio run ``` Add zenoh-pico as a library by doing: ```bash - $ ln -s /path/to/zenoh-pico /path/to/project_dir/lib/zenoh-pico + ln -s /path/to/zenoh-pico /path/to/project_dir/lib/zenoh-pico ``` + or just include the following line in platformio.ini: - ``` + + ```ini lib_deps = https://github.com/eclipse-zenoh/zenoh-pico ``` @@ -286,6 +302,7 @@ To build and upload the code into the board, run the following command: ``` #### 2.2.5. OpenCR + Note: tested with ROBOTIS OpenCR 1.0 board A typical PlatformIO project for OpenCR framework must have the following structure: @@ -304,19 +321,21 @@ Note: to add support for OpenCR in PlatformIO, follow the steps presented in our To initialize this project structure, execute the following commands: ```bash - $ mkdir -p /path/to/project_dir - $ cd /path/to/project_dir - $ platformio init -b opencr - $ platformio run + mkdir -p /path/to/project_dir + cd /path/to/project_dir + platformio init -b opencr + platformio run ``` Add zenoh-pico as a library by doing: ```bash - $ ln -s /path/to/zenoh-pico /path/to/project_dir/lib/zenoh-pico + ln -s /path/to/zenoh-pico /path/to/project_dir/lib/zenoh-pico ``` + or just include the following line in platformio.ini: - ``` + + ```ini lib_deps = https://github.com/eclipse-zenoh/zenoh-pico ``` @@ -330,7 +349,8 @@ To build and upload the code into the board, run the following command: platformio run -t upload ``` -#### 2.2.6. Raspberry Pi Pico +#### 2.2.6. Raspberry Pi Pico + Note: tested with `Raspberry Pi Pico W` and `Raspberry Pi Pico 2 W` boards Ensure your system has the necessary tools and libraries installed. Run the following commands: @@ -361,7 +381,8 @@ git submodule update --init ``` Setup and build the examples: -- `PICO_BOARD` - Pico board type: pico, pico_w, pico2, pico2_w (default: pico_w) + +- `PICO_BOARD` - Pico board type: pico, pico_w, pico2, pico2_w (default: pico_w) - `WIFI_SSID` - Wi-Fi network SSID - `WIFI_PASSWORD` - Wi-Fi password - `ZENOH_CONFIG_MODE` - client or peer mode (default: client) @@ -381,7 +402,8 @@ To flash the Raspberry Pi Pico board, connect it in bootloader mode (it will app To connect via UART specify pins or predefined device name and baud rate: e.g. -``` + +```bash -DZENOH_CONFIG_CONNECT="serial/0.1#baudrate=38400" -DZENOH_CONFIG_CONNECT="serial/uart1_0#baudrate=38400" ``` @@ -396,123 +418,148 @@ Valid PIN combinations and associated device names: | 12.13 | uart0_1 | | 16.17 | uart0_2 | - **USB Serial connection (experemental)**: - To enable this feature, zenoh-pico should be compiled with `Z_FEATURE_LINK_SERIAL_USB` and `Z_FEATURE_UNSTABLE_API` enabled. To connect via USB CDC, specify `usb` device: e.g. -``` + +```bash -DZENOH_CONFIG_CONNECT="serial/usb#baudrate=112500" ``` On the host Zenoh, specify the USB CDC device: e.g. -``` + +```bash zenohd -l serial//dev/ttyACM1#baudrate=112500 ``` ## 3. Running the Examples + The simplest way to run some of the example is to get a Docker image of the **zenoh** router (see [http://zenoh.io/docs/getting-started/quick-test/](http://zenoh.io/docs/getting-started/quick-test/)) and then to run the examples on your machine. ### 3.1. Starting the Zenoh Router + Assuming you've pulled the Docker image of the **zenoh** router on a Linux host (to leverage UDP multicast scouting as explained [here](https://zenoh.io/docs/getting-started/quick-test/#run-zenoh-router-in-a-docker-container), then simply do: + ```bash -$ docker run --init --net host eclipse/zenoh:main +docker run --init --net host eclipse/zenoh:main ``` To see the zenoh manual page, simply do: + ```bash -$ docker run --init --net host eclipse/zenoh:main --help +docker run --init --net host eclipse/zenoh:main --help ``` :warning: **Please notice that the `--net host` option in Docker is restricted to Linux only.** The cause is that Docker doesn't support UDP multicast between a container and its host (see cases [moby/moby#23659](https://github.com/moby/moby/issues/23659), [moby/libnetwork#2397](https://github.com/moby/libnetwork/issues/2397) or [moby/libnetwork#552](https://github.com/moby/libnetwork/issues/552)). The only known way to make it work is to use the `--net host` option that is [only supported on Linux hosts](https://docs.docker.com/network/host/). ### 3.2. Basic Pub/Sub Example + Assuming that (1) you are running the **zenoh** router, and (2) you are under the build directory, do: + ```bash -$ ./z_sub +./z_sub ``` And on another shell, do: + ```bash -$ ./z_pub +./z_pub ``` + ### 3.3. Basic Queryable/Get Example + Assuming you are running the **zenoh** router, do: + ```bash -$ ./z_queryable +./z_queryable ``` And on another shell, do: + ```bash -$ ./z_get +./z_get ``` ### 3.4. Basic Pub/Sub Example - P2P over UDP multicast + Zenoh-Pico can also work in P2P mode over UDP multicast. This allows a Zenoh-Pico application to communicate directly with another Zenoh-Pico application without requiring a Zenoh Router. Assuming that (1) you are under the build directory, do: + ```bash -$ ./z_sub -m peer -l udp/224.0.0.123:7447#iface=lo0 +./z_sub -m peer -l udp/224.0.0.123:7447#iface=lo0 ``` And on another shell, do: + ```bash -$ ./z_pub -m peer -l udp/224.0.0.123:7447#iface=lo0 +./z_pub -m peer -l udp/224.0.0.123:7447#iface=lo0 ``` + where `lo0` is the network interface you want to use for multicast communication. > [!WARNING] > Multicast communication does not perform any negotiation upon group joining. Because of that, it is important that all transport parameters are the same to make sure all your nodes in the system can communicate. > One common parameter to configure is the batch size since its default value depends on the actual platform when operating on multicast: -> - with zenoh-pico you can configure it via the `BATCH_MULTICAST_SIZE` build option (see [below](#error-when-opening-a-session-on-a-microcontroller)) -> - with other Zenoh APIs, set the "transport/link/tx/batch_size" value in configuration file +> +> - with zenoh-pico you can configure it via the `BATCH_MULTICAST_SIZE` build option (see [below](#error-when-opening-a-session-on-a-microcontroller)) +> - with other Zenoh APIs, set the "transport/link/tx/batch_size" value in configuration file > > E.g., the batch size on Linux and Windows is 65535 bytes, on Mac OS X is 9216, anything else is 8192. ### 3.4. Basic Pub/Sub Example - Mixing Client and P2P communication -To allow Zenoh-Pico unicast clients to talk to Zenoh-Pico multicast peers, as well as with any other Zenoh client/peer, you need to start a Zenoh Router that listens on both multicast and unicast: + +To allow Zenoh-Pico unicast clients to talk to Zenoh-Pico multicast peers, as well as with any other Zenoh client/peer, you need to start a Zenoh Router that listens on both multicast and unicast: + ```bash -$ docker run --init --net host eclipse/zenoh:main -l udp/224.0.0.123:7447#iface=lo0 -l tcp/127.0.0.1:7447 +docker run --init --net host eclipse/zenoh:main -l udp/224.0.0.123:7447#iface=lo0 -l tcp/127.0.0.1:7447 ``` Assuming that (1) you are running the **zenoh** router as indicated above, and (2) you are under the build directory, do: + ```bash -$ ./z_sub -m client -e tcp/127.0.0.1:7447 +./z_sub -m client -e tcp/127.0.0.1:7447 ``` + A subscriber will connect in client mode to the **zenoh** router over TCP unicast. And on another shell, do: + ```bash -$ ./z_pub -m peer -l udp/224.0.0.123:7447#iface=lo0 +./z_pub -m peer -l udp/224.0.0.123:7447#iface=lo0 ``` + A publisher will start publishing over UDP multicast and the **zenoh** router will take care of forwarding data from the Zenoh-Pico publisher to the Zenoh-Pico subscriber. ## Troubleshooting ### Activate debug logs + By default debug logs are deactivated but if you're encountering issues they can help you finding the cause. To activate them you need to pass the build flag value: `-DZENOH_DEBUG=3` ### Error when opening a session on a microcontroller + If you get an error when opening the session even though everything is setup correctly, it might be because the default buffer sizes are too large for the limited memory available on your system. The first thing to try is to reduce the values of the following configuration options (found in `CMakeLists.txt`): -* BATCH_UNICAST_SIZE: The maximum size of a packet in client mode. -* BATCH_MULTICAST_SIZE: The maximum size of a packet in peer mode. -* FRAG_MAX_SIZE: The maximum size of a message that can be fragmented into multiple packets. + +- BATCH_UNICAST_SIZE: The maximum size of a packet in client mode. +- BATCH_MULTICAST_SIZE: The maximum size of a packet in peer mode. +- FRAG_MAX_SIZE: The maximum size of a message that can be fragmented into multiple packets. Until you find values that suits both your app requirements and your system memory constraints. These values can also be passed directly as cmake args. For example, in a `platformio.ini` you might write: -``` + +```bash board_build.cmake_extra_args= - -DBATCH_UNICAST_SIZE=1024 - -DFRAG_MAX_SIZE=2048 + -DBATCH_UNICAST_SIZE=1024 + -DFRAG_MAX_SIZE=2048 ``` -