Collaborate on good documentation ( Zenoh book )

[jcos1]

• official zenoh book
• repo with official docs
• Awesome Zenoh
• Paper: On the performance of Zenoh in Industrial IoT Scenarios

Some notes to get started (at a lower level) ...

Intro

To send a resource to a zenoh router, various messages need to be exhanged between the zenoh client and the zenoh router.

First four handshake messages are sent. These are the Message ❱ InitSyn, the Message ❱ InitAck*)*, the Message ❱ OpenSyn and the Message ❱ OpenAck.

Then a Message ❱ Frame can be sent. One type of frame is a Message ❱ Frame ❱ Push. A push frame can contain a Message ❱ Frame ❱ Push ❱ Put. This put will publish a resource (some payload on some resource key).

So to publish a value we will need the following messages:

1. Client->Router | Message ❱ InitSyn
2. Router->Client | Message ❱ InitAck
3. Client->Router | Message ❱ OpenSyn
4. Router->Client | Message ❱ OpenAck
5. Client->Router | Message ❱ Frame ❱ Declare ❱ D_KEYEXPR
6. Client->Router | Message ❱ Frame ❱ Push ❱ Put

Transports

The messages can be implemented for different transports. These transports are described over here at
io/zenoh-links

• zenoh-link-quic
• zenoh-link-serial
• zenoh-link-tcp
• zenoh-link-tls
• zenoh-link-udp
• zenoh-link-unixpipe
• zenoh-link-unixsock_stream
• zenoh-link-vsock
• zenoh-link-ws

Message

We will now have a look at the messages on TCP.

Each Zenoh TCP message starts with 2 bytes indicating the length (little-endian).

This is followed by a byte containing some flags and an ID to indicate what is inside the message.

The possible types of messages are defined here at
commons/zenoh-protocol/src/transport

• 0x00 oam.rs
• 0x01 init.rs
• 0x02 open.rs
• 0x03 close.rs
• 0x04 keepalive.rs
• 0x05 frame.rs
• 0x06 fragment.rs
• 0x07 join.rs

The IDs for these messages are defined here at commons/zenoh-protocol/src/transport/mod.rs

Message ❱ Init (Syn and Ack)

These messages are described over here at commons/zenoh-protocol/src/transport/init.rs

Message ❱ Open (Syn and Ack)

These message are described over here at commons/zenoh-protocol/src/transport/open.rs

Message ❱ KeepAlive

KeepAlive messages are sent by both client and router to keep the connection alive.

The keep alive message is described over here at commons/zenoh-protocol/src/transport/keepalive.rs

Message ❱ Frame

A Message ❱ Frame starts with a byte containing an ID to indicate what is inside the frame.
The first three bits of this byte are used to set some flags for the frame.

The possible types of frames are defined here at commons/zenoh-protocol/src/network

• 0x1F oam
• 0x1E declare
• 0x1D push
• 0x1C request
• 0x1B response
• 0x1A response final

The IDs for these frames are defined here at commons/zenoh-protocol/src/network/mod.rs

Message ❱ Frame ❱ Declare

The Message ❱ Frame ❱ Declare contains a declaration. These are defined over here at
commons/zenoh-protocol/src/network/declare.rs

This declaration can be one of these.

• 0x00 D_KEYEXPR
• 0x01 U_KEYEXPR
• 0x02 D_SUBSCRIBER
• 0x03 U_SUBSCRIBER
• 0x04 D_QUERYABLE
• 0x05 U_QUERYABLE
• 0x06 D_TOKEN
• 0x07 U_TOKEN
• 0x08 D_INTEREST
• 0x09 F_INTEREST
• 0x0A U_INTEREST

The IDs for these declarations are defined here at
commons/zenoh-protocol/src/network/declare.rs

Example: a Message ❱ Frame ❱ Declare ❱ D_SUBSCRIBER message is sent to subscribe to a certain key expression.

Example: a Message ❱ Frame ❱ Declare ❱ D_KEYEXPR message is sent to map a resource key (aka topic name) to a short number. This is very useful when sending data repeatedly because it reduces the message size alot.

Message ❱ Frame ❱ Push

The possible types of Message ❱ Frame ❱ Push message are defined here at commons/zenoh-protocol/src/zenoh

• 0x01 put
• 0x02 del

pub enum PushBody {
    Put(Put),
    Del(Del),
}

Example: a Message ❱ Frame ❱ Push ❱ Put message is sent to publish a certain key.

Message ❱ Frame ❱ Request ❱ Query

There is only one type of Message ❱ Frame ❱ Request message. This is described over here at commons/zenoh-protocol/src/zenoh

• 0x03 query

The other types were removed from the protocol:

• Removal of pull
• Removal of Put and Del

pub enum RequestBody {
    Query(Query),
    //Put(Put),
    //Del(Del),
    //Pull(Pull),
}

Message ❱ Frame ❱ Response

There are two types of Message ❱ Frame ❱ Response message. This is described over here at commons/zenoh-protocol/src/zenoh

• 0x04 reply
• 0x05 err

pub enum ResponseBody {
    Reply(Reply),
    Err(Err),
}

TO BE DOCUMENTED

There are some other IDs for possible frame bodies defined over here at commons/zenoh-protocol/src/zenoh/mod.rs

• Message ❱ Frame ❱ ? ❱ oam
• Message ❱ Frame ❱ ? ❱ ack

Testing and troubleshooting

• Troubleshooting section in the official docs

set RUST_LOG = TRACE

• Zenoh swiss army knife CLI Tool

• Zenoh-hammer (aka MQTT Explorer for zenoh)