Skip to content

Latest commit

 

History

History
131 lines (92 loc) · 4.97 KB

zenoh.adoc

File metadata and controls

131 lines (92 loc) · 4.97 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 users want to configure how Zenoh works, they can adjust the configuration.

  • UAuthority: The authority might be omitted in local UUri, and we need this to derive the Zenoh key.

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.4. Payload

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: The authority_name defined in URI spec is mapped into Zenoh key directly. If the authority_name is omitted in UUri, it MUST be filled with UAuthority which is initialized while creating UPClienZenoh.

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

Note that in Publish use case, there is no sink UURI. We MUST use {} to replace the empty authority_name, ue_id, ue_version_major, and resource_id.

Take some examples:

Use Case Source Sink Zenoh Key

Send Publish

/10AB/3/80CD (If publisher’s authority is 192.168.1.100)

-

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

Subscribe messages

//192.168.1.100/10AB/3/80CD

-

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

Send Notification

//192.168.1.100/10AB/3/80CD

//192.168.1.101/20EF/4/0

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

Receive all Notifications

//*/FFFF/FF/FFFF

//192.168.1.101/20EF/4/0

up/*/*/*/*/192.168.1.101/20EF/4/0

Send Request

//my-host1/10AB/3/0

//my-host2/20EF/4/B

up/my-host1/10AB/3/0/my-host2/20EF/4/B

Receive all Requests

//*/FFFF/FF/FFFF

//my-host2/20EF/4/B

up/*/*/*/*/my-host2/20EF/4/B

Receive all messages to a device

//*/FFFF/FF/FFFF

//[::1]/FFFF/FF/FFFF

up/*/*/*/*/[::1]/*/*/*