Zenoh-net API Reference¶

The network level zenoh API.

Examples:¶

Publish¶

>>> import zenoh
>>> s = zenoh.net.open({})
>>> s.write('/resource/name', bytes('value', encoding='utf8'))

Query¶

>>> import zenoh, time
>>> from zenoh.net import QueryTarget, queryable
>>> def query_callback(reply):
...     print("Received : {}".format(reply))
>>>
>>> s = zenoh.net.open({})
>>> s.query('/resource/name', 'predicate', query_callback)
>>> time.sleep(1)

zenoh.net.open()¶

Open a zenoh-net Session.

Parameters:	config (dict {str: str}) – The configuration of the zenoh-net session
Return type:	Session
Example:

>>> import zenoh
>>> z = zenoh.net.open(zenoh.net.config::peer())

zenoh.net.scout()¶

Scout for routers and/or peers.

This spawns a task that periodically sends scout messages for a specified duration and returns a list of received Hello messages.

Parameters:	whatami (int) – The kind of zenoh process to scout for config (dict {str: str}) – The configuration to use for scouting scout_duration (float) – the duration of scout (in seconds)
Return type:	list of `Hello`
Example:

>>> import zenoh
>>> hellos = zenoh.net.scout(zenoh.net.whatami.PEER | zenoh.net.whatami.ROUTER, {}, 1.0)
>>> for hello in hellos:
>>>     print(hello)

Hello¶

class zenoh.net.Hello¶

A Hello message received as a response to a scout()

locators¶

The locators list of the Hello message sender

Type:	list of str or `None`

pid¶

The PeerId of the Hello message sender

Type:	`PeerId` or `None`

whatami¶

The mode of the Hello message sender (bitmask of constants from whatami)

Type:	int or `None`

Session¶

class zenoh.net.Session¶

A zenoh-net session.

close()¶: Close the zenoh-net Session.

declare_publisher()¶

Declare a Publisher for the given resource key.

Written resources that match the given key will only be sent on the network if matching subscribers exist in the system.

The resource parameter also accepts the following types that can be converted to a ResKey:

int for a ResKey.Rid(int)
str for a ResKey.RName(str)
(int, str) for a ResKey.RIdWithSuffix(int, str)

Parameters:	resource (ResKey) – The resource key to publish
Return type:	Publisher
Examples:

>>> import zenoh
>>> s = zenoh.net.open({})
>>> rid = s.declare_publisher('/resource/name')
>>> s.write('/resource/name', bytes('value', encoding='utf8'))

declare_queryable()¶

Declare a Queryable for the given resource key.

The resource parameter also accepts the following types that can be converted to a ResKey:

int for a ResKey.Rid(int)
str for a ResKey.RName(str)
(int, str) for a ResKey.RIdWithSuffix(int, str)

Parameters:	resource (ResKey) – The resource key the Queryable will reply to info (int) – The kind of Queryable callback (function(`Query`)) – the queryable callback
Return type:	Queryable
Examples:

>>> import zenoh, time
>>> from zenoh.net import Sample, queryable
>>> def callback(query):
...     print("Received : {}".format(query))
...     query.reply(Sample('/resource/name', bytes('value', encoding='utf8')))
>>>
>>> s = zenoh.net.open({})
>>> q = s.declare_queryable('/resource/name', queryable.EVAL, callback)
>>> time.sleep(60)

declare_resource()¶

Associate a numerical Id with the given resource key.

This numerical Id will be used on the network to save bandwidth and ease the retrieval of the concerned resource in the routing tables.

The resource parameter also accepts the following types that can be converted to a ResKey:

int for a ResKey.Rid(int)
str for a ResKey.RName(str)
(int, str) for a ResKey.RIdWithSuffix(int, str)

Parameters:	resource (ResKey) – The resource key to map to a numerical Id
Return type:	int
Examples:

>>> import zenoh
>>> s = zenoh.net.open({})
>>> rid = s.declare_resource('/resource/name')

declare_subscriber()¶

Declare a Subscxriber for the given resource key.

The resource parameter also accepts the following types that can be converted to a ResKey:

int for a ResKey.Rid(int)
str for a ResKey.RName(str)
(int, str) for a ResKey.RIdWithSuffix(int, str)

Parameters:	resource (ResKey) – The resource key to subscribe info (SubInfo) – The `SubInfo` to configure the subscription callback (function(`Sample`)) – the subscription callback
Return type:	Subscriber
Examples:

>>> import zenoh, time
>>> from zenoh.net import SubInfo, Reliability, SubMode
>>>
>>> s = zenoh.net.open({})
>>> sub_info = SubInfo(Reliability.Reliable, SubMode.Push)
>>> sub = s.declare_subscriber('/resource/name', sub_info, lambda sample:
...     print("Received : {}".format(sample)))
>>> time.sleep(60)

info()¶

Get informations about the zenoh-net Session.

Return type:	dict {str: str}
Example:

>>> import zenoh
>>> s = zenoh.net.open({})
>>> info = s.info()
>>> for key in info:
>>>    print("{} : {}".format(key, info[key]))

query()¶

Query data from the matching queryables in the system.

The replies are provided by calling the provided callback for each reply. The callback is called a last time with None when the query is complete.

The resource parameter also accepts the following types that can be converted to a ResKey:

int for a ResKey.Rid(int)
str for a ResKey.RName(str)
(int, str) for a ResKey.RIdWithSuffix(int, str)

Parameters:

resource (ResKey) – The resource key to query
predicate (str) – An indication to matching queryables about the queried data
callback (function(Reply)) – the query callback which will receive the replies
target (QueryTarget, optional) – The kind of queryables that should be target of this query
consolidation (QueryConsolidation, optional) – The kind of consolidation that should be applied on replies

Examples:

>>> import zenoh, time
>>> from zenoh.net import QueryTarget, queryable
>>>
>>> s = zenoh.net.open({})
>>> s.query('/resource/name', 'predicate', lambda reply:
...    print("Received : {}".format(
...        reply.data if reply is not None else "FINAL")))

query_collect()¶

Query data from the matching queryables in the system.

Replies are collected in a list.

The resource parameter also accepts the following types that can be converted to a ResKey:

int for a ResKey.Rid(int)
str for a ResKey.RName(str)
(int, str) for a ResKey.RIdWithSuffix(int, str)

Parameters:	resource (ResKey) – The resource key to query predicate (str) – An indication to matching queryables about the queried data target (QueryTarget, optional) – The kind of queryables that should be target of this query consolidation (QueryConsolidation, optional) – The kind of consolidation that should be applied on replies
Return type:	[`Reply`]
Examples:

>>> import zenoh, time
>>> from zenoh.net import QueryTarget, queryable
>>>
>>> s = zenoh.net.open({})
>>> replies = s.query_collect('/resource/name', 'predicate')
>>> for reply in replies:
...    print("Received : {}".format(reply.data))

undeclare_resource()¶

Undeclare the numerical Id/resource key association previously declared with declare_resource().

Parameters:	rid (ResKey) – The numerical Id to unmap
Examples:

>>> import zenoh
>>> s = zenoh.net.open({})
>>> rid = s.declare_resource('/resource/name')
>>> s.undeclare_resource(rid)

write()¶

Write data.

The resource parameter also accepts the following types that can be converted to a ResKey:

int for a ResKey.Rid(int)
str for a ResKey.RName(str)
(int, str) for a ResKey.RIdWithSuffix(int, str)

Parameters:	resource (ResKey) – The resource key to write payload (bytes) – The value to write
Examples:

>>> import zenoh
>>> s = zenoh.net.open({})
>>> s.write('/resource/name', bytes('value', encoding='utf8'))

Subscriber¶

class zenoh.net.Subscriber¶

A subscriber

pull()¶: Pull available data for a pull-mode subscriber.

undeclare()¶: Undeclare the subscriber.

ResKey¶

class zenoh.net.ResKey¶

A resource key

static RId()¶

Creates a resource key from a resource id returned by Session.declare_resource().

Parameters:	id (int) – the resrouce id

static RIdWithSuffix()¶

Creates a resource key from a resource id returned by Session.declare_resource() and a suffix.

Parameters:	id (int) – the resrouce id suffix (str) – the suffix

static RName()¶

Creates a resource key from a name.

Parameters:	name (str) – the resrouce name

is_numerical()¶: Returns True if the resource key is a RId().

rid()¶: Returns the resource id, or 0 if the resource key is a RName().

PeerId¶

class zenoh.net.PeerId¶: A Peer id

Timestamp¶

class zenoh.net.Timestamp¶

A Timestamp composed of a time and the identifier of the timestamp source.

id¶

The identifier of the timestamp source

Type:	bytes

time¶

The time in seconds since the UNIX EPOCH (January 1, 1970, 00:00:00 (UTC)) as a floating point number.

Type:	float

DataInfo¶

class zenoh.net.DataInfo¶

Some informations about the associated data

encoding¶

The encoding flag of the data.

Type:	int or `None`

first_router_id¶

The PeerId of the 1st router that routed the data.

Type:	`PeerId` or `None`

first_router_sn¶

The first router sequence number of the data.

Type:	int or `None`

kind¶

The kind of the data.

Type:	int or `None`

source_id¶

The PeerId of the data source.

Type:	`PeerId` or `None`

source_sn¶

The source sequence number of the data.

Type:	int or `None`

timestamp¶

The Timestamp of the data.

Type:	`Timestamp` or `None`

Sample¶

class zenoh.net.Sample¶

A zenoh sample.

Parameters:	res_name (str) – the resource name payload (bytes) – the data payload data_info (DataInfo, optional) – some information about the data

data_info¶

Some information about the data

Type:	`DataInfo` or `None`

payload¶

The data payload

Type:	bytes

res_name¶

The resource name

Type:	str

Reliability¶

class zenoh.net.Reliability¶

The kind of reliability

BestEffort¶

Reliable¶

SubMode¶

class zenoh.net.SubMode¶

The subscription mode.

Push¶

Pull¶

Period¶

class zenoh.net.Period¶: A time period.

SubInfo¶

class zenoh.net.SubInfo¶

Informations to configure a subscription.

Parameters:	reliability (Reliability, optional) – the reliability mode (default: `Reliability.Reliable`) mode (SubMode, optional) – the subscription mode (default: `SubMode.Push`) period (Period, optional) – the pull period

Publisher¶

class zenoh.net.Publisher¶

A publisher

undeclare()¶: Undeclare the publisher.

Query¶

class zenoh.net.Query¶

Type received by a queryable callback. See Session.declare_queryable().

predicate¶

The predicate of the query

Type:	str

reply()¶

Send a reply to the query

Parameters:	sample – the reply sample
Type:	Sample

res_name¶

The resrouce name of the query

Type:	str

Queryable¶

class zenoh.net.Queryable¶

An entity able to reply to queries.

undeclare()¶: Undeclare the queryable.

Target¶

class zenoh.net.Target¶: The queryables that should be target of a Query

QueryTarget¶

class zenoh.net.QueryTarget¶

The queryables that should be target of a Query.

Parameters:	kind (int, optional) – the kind of queryable (one constant from `queryable`) target (Target, optional) – a characteristic of the queryable.

ConsolidationMode¶

class zenoh.net.ConsolidationMode¶

The kind of consolidation that should be applied on replies to a Session.query().

No¶

Lazy¶

Full¶

QueryConsolidation¶

class zenoh.net.QueryConsolidation¶

The kind of consolidation that should be applied on replies to a Session.query() at the different stages of the reply process.

Parameters:

first_routers (ConsolidationMode, optional) – the consolidation mode to apply on first routers of the replies routing path (default: ConsolidationMode.Lazy)
last_router (ConsolidationMode, optional) – the consolidation mode to apply on last router of the replies routing path (default: ConsolidationMode.Lazy)
reception (ConsolidationMode, optional) – the consolidation mode to apply at reception of the replies (default: ConsolidationMode.Full)

Reply¶

class zenoh.net.Reply¶

Type received by a query callback. See Session.query().

data¶

The data

Type:	Sample

replier_id()¶

The identifier of reply source

Type:	PeerId

source_kind¶

The kind of reply source

Type:	int

module zenoh.net.config¶

Constants and helpers to build the configuration to pass to zenoh.net.open().

module zenoh.net.info¶

Constants and helpers to interpret the properties returned by zenoh.net.Session.info().

module zenoh.net.whatami¶

Constants defining the different zenoh process to look for with zenoh.net.scout().

zenoh.net.whatami.to_string()¶

module zenoh.net.queryable¶

Constants defining the different modes of a zenoh Queryable.

module zenoh.net.resource_name¶

zenoh.net.resource_name.intersect()¶

Return true if both resource names intersect.

Parameters:	s1 (str) – the 1st resource name s2 (str) – the 2nd resource name

module zenoh.net.encoding¶

Constants defining the different encoding flags.

zenoh.net.encoding.from_str()¶

zenoh.net.encoding.to_string()¶

Zenoh-net API Reference¶

Examples:¶

Publish¶

Subscribe¶

Query¶

Hello¶

Session¶

Subscriber¶

ResKey¶

PeerId¶

Timestamp¶

DataInfo¶

Sample¶

Reliability¶

SubMode¶

Period¶

SubInfo¶

Publisher¶

Query¶

Queryable¶

Target¶

QueryTarget¶

ConsolidationMode¶

QueryConsolidation¶

Reply¶

module zenoh.net.config¶

module zenoh.net.info¶

module zenoh.net.whatami¶

module zenoh.net.queryable¶

module zenoh.net.resource_name¶

module zenoh.net.encoding¶