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
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.
For more information, please visit https://projects.eclipse.org/projects/iot.zenoh or https://zenoh.io/
We MUST use Zenoh version 1.0.0 or above to ensure the interoperability in different language bindings.
While initializing up-transport library, we MUST include the following information.
-
Zenoh Config: If users want to configure how Zenoh works, they can adjust the configuration.
-
UUri: The local UUri we are using, and we need this to derive the Zenoh key.
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.
Since the type of user attachment is ZBytes in Zenoh, we MUST transform UAttribute into ZBytes. To keep the flexibility of updating UAttributes in the future, we also reserve 1 byte to represent the version. Therefore, the format of user attachment will be like following:
| order | value |
|---|---|
1 |
UAttribute version (1 byte) |
2 |
UAttribute object encoded into protobuf |
Note that the only supported version now is 0x01.
There are 4 kinds of message types in uProtocol (publish, notification, request, response), all of said messages are sent using the zenoh put() API meaning we shall use the pub/sub infrastructure only of zenoh and not the queryable APIs.
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_type]/[source.ue_instance]/[source.ue_version_major]/[source.resource_id]/[sink.authority_name]/[sink.ue_type]/[sink.ue_instance]/[sink.ue_version_major]/[sink.resource_id]
-
up/: Zenoh key MUST always start withup/, 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_type,ue_instance,ue_version_majorandresource_id: They MUST be mapped to the upper-case base16 encoding without any leading 0.
Note:
-
In Publish use case, there is no sink UURI. We MUST use
{}to replace the emptyauthority_name,ue_type,ue_instance,ue_version_major, andresource_id. -
The wildcard values in each part of UUri is mapped to the asterisk (*).
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/0/3/80CD/{}/{}/{}/{}/{} |
Subscribe messages |
//192.168.1.100/10AB/3/80CD |
- |
up/192.168.1.100/10AB/0/3/80CD/{}/{}/{}/{}/{} |
Send Notification |
//192.168.1.100/10AB/3/80CD |
//192.168.1.101/300EF/4/0 |
up/192.168.1.100/10AB/0/3/80CD/192.168.1.101/EF/3/4/0 |
Receive all Notifications |
//*/FFFFFFFF/FF/FFFF |
//192.168.1.101/300EF/4/0 |
up/*/*/*/*/*/192.168.1.101/EF/3/4/0 |
Send Request |
//my-host1/403AB/3/0 |
//my-host2/CD/4/B |
up/my-host1/3AB/4/3/0/my-host2/CD/0/4/B |
Receive all Requests |
//*/FFFFFFFF/FF/FFFF |
//my-host2/CD/4/B |
up/*/*/*/*/*/my-host2/CD/0/4/B |
Receive all messages to a device |
//*/FFFFFFFF/FF/FFFF |
//[::1]/FFFFFFFF/FF/FFFF |
up/*/*/*/*/*/[::1]/*/*/*/* |