Skip to content

Latest commit

 

History

History
152 lines (109 loc) · 5.57 KB

zenoh.adoc

File metadata and controls

152 lines (109 loc) · 5.57 KB
Raw

Zenoh

Table of Contents

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in IETF BCP14 (RFC2119 & RFC8174)

SPDX-FileCopyrightText: 2024 Contributors to the Eclipse Foundation

See the NOTICE file(s) distributed with this work for additional
information regarding copyright ownership.

This program and the accompanying materials are made available under
the terms of the Apache License Version 2.0 which is available at
https://www.apache.org/licenses/LICENSE-2.0

SPDX-FileType: DOCUMENTATION
SPDX-License-Identifier: Apache-2.0

1. Overview

Zero Overhead Network Protocol.

Zenoh /zeno/ is a pub/sub/query protocol unifying data in motion, data at rest and computations. It elegantly 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.

2. Specifications

2.1. Zenoh Version

We MUST use Zenoh version 0.11.0-rc.3 to ensure the interoperability in different language bindings.

2.2. UPClientZenoh initialization

While initializing up-client library, we MUST include the following information.

  • Zenoh Config: If user wants to configure how Zenoh works, they can adjust the configuration.

  • UAuthority: UAuthority is used in two scenarios:

    • UAuthority is used to generate source authority field in Zenoh key.

    • While calling invoke_method, we need UAuthority and UEntity to generate the response UUri.

  • UEntity: While calling invoke_method, we need UAuthority and UEntity to generate the response UUri.

2.3. UAttribute Mapping

Zenoh supports user attachment. We MUST send additional information with the mechanism, for example, UAttribute. This reduces the unnecessary serialization on payload, which mostly takes time.

User attachment supports non-unique key-value pairs, which means one key can include several values. In this case, the order of the values matters. To decrease the network overhead, we MUST keep the key empty and put the value in the order according to the following table.

order value

1

UAttribute version (1 byte)

2

UAttribute object encoded into protobuf

We use 1 byte to represent the UAttribute version. The version field will keep the flexibility of updating UAttribute in the future. Now the version is always 0x01.

2.3.1. Message Type

There are 4 kinds of message types in uProtocol (publish, notification, request, response). Different message types MUST use different Zenoh API.

uProtocol message type Zenoh API

publish

put

notification

put

request

get (query)

response

reply (queryable)

2.3.2. Priority Mapping (uProtocol to Zenoh):

uProtocol priority Zenoh Priority

CS0

BACKGROUND

CS1

DATA_LOW

CS2

DATA

CS3

DATA_HIGH

CS4

INTERACTIVE_LOW

CS5

INTERACTIVE_HIGH

CS6

REAL_TIME

2.3.3. TTL

While sending Request messages, TTL MUST be mapped to the timeout configuration in Zenoh query.

2.3.4. Payload Format

Payload Format MUST be sent with Zenoh encoding. Zenoh supports Encoding::WithSuffix. The encoding here is KnownEncoding::AppCustom and the UPayloadFormat (int32) is transformed into the string.

Encoding::WithSuffix(
    KnownEncoding::AppCustom,
    payload.format.value().to_string().into(),
)

2.4. UPayload

The data is sent with Zenoh directly without further processing.

2.5. URI Mapping

UUri are transformed into Zenoh key expressions following the format defined below. The format of Zenoh key MUST be up/[source.authority_name]/[source.ue_id]/[source.ue_version_major]/[source.resource_id]/[sink.authority_name]/[sink.ue_id]/[sink.ue_version_major]/[sink.resource_id]

  • up/: Zenoh key MUST always start with up/, which can be used to identify the uProtocol traffic.

  • authority_name: Since authority is case-insensitive and allows some special characters defined in RFC3986, Section 3.2.2. The implementation MUST transform all the alphabets to lowercase and use {} to escape special characters.

  • entity_id, ue_version_major and resource_id: They MUST be mapped to the upper-case base16 encoding.

Special characters in authority Zenoh Key

empty

{}

$

{dollar}

Take some examples:

Use Case Source Sink Zenoh Key

Send Publish

up://192.168.1.100/10AB/3/80CD

-

up/192.168.1.100/10AB/3/80CD/{}/{}/{}/{}

Subscribe messages

up://192.168.1.100/10AB/3/80CD

-

up/192.168.1.100/10AB/3/80CD/{}/{}/{}/{}

Send Notification

up://192.168.1.100/10AB/3/80CD

up://192.168.1.101/20EF/4/80GH

up/192.168.1.100/10AB/3/80CD/192.168.1.101/20EF/4/80GH

Receive all Notifications

up://*/FFFF/FF/FFFF

up://192.168.1.101/20EF/4/80GH

up/*/*/*/*/192.168.1.101/20EF/4/80GH

Send Request

up://MY-HOST1/10AB/3/0

up://my-host$/20EF/4/B

up/my-host1/10AB/3/0/my-host{dollar}/20EF/4/B

Receive all Requests

up://*/FFFF/FF/FFFF

up://my-host$/20EF/4/B

up/*/*/*/*/my-host{dollar}/20EF/4/B

Receive all messages to a device

up://*/FFFF/FF/FFFF

up://192.168.1.101/FFFF/FF/FFFF

up/*/*/*/*/192.168.1.101/*/*/*