Understanding nodes and topics¶
Nodes¶
The communication in Ignition Transport follows a pure distributed architecture, where there is no central process, broker or similar. All the nodes in the network can act as publishers, subscribers, provide services and request services.
A publisher is a node that produces information and a subscriber is a node that consumes information. There are two categories or ways to communicate in Ignition Transport. First, we could use a publish/subscribe approach, where a node advertises a topic, and then, publishes periodic updates. On the other side, one or more nodes subscribe to the same topic registering a function that will be executed each time a new message is received. An alternative communication paradigm is based on service calls. A service call is a remote service that a node offers to the rest of the nodes. A node can request a service in a similar way a local function is executed.
Topics¶
A topic is just a name for grouping a specific set of messages or a particular
service. Imagine that you have a camera and want to periodically publish its
images. Your node could advertise a topic called /image
, and then, publish a
new message on this topic every time a new image is available. Other nodes, will
subscribe to the same topic and will receive the messages containing the image.
A node could also offer an echo service in the topic /echo
. Any node
interested in this service will request a service call on topic /echo
. The
service call will accept arguments and will return a result. In our echo
service example, the result will be similar to the input parameter passed to the
service.
There are some rules to follow when selecting a topic name. It should be any
alphanumeric name followed by zero or more slashes. For example: /image
,
head_position
, /robot1/joints/HeadPitch
are examples of valid topic
names. The next table summarizes the allowed and not allowed topic rules.
Topic name | Validity | Comment |
---|---|---|
/topicA | Valid | |
/topicA/ | Valid | Equivalent to /topicA |
topicA | Valid | |
/a/b | Valid | |
Invalid | Empty string is invalid | |
my topic | Invalid | Contains white space |
//image | Invalid | Contains two consecutive // |
/ | Invalid | / topic is not allowed |
~myTopic | Invalid | Symbol ~ not allowed |
Topic scope¶
A topic can be optionally advertised with a scope. A scope allows you to set the
visibility of this topic. The available scopes are Process
, Host
, and
All
. A Process
scope means that the advertised topic will only be
visible in the nodes within the same process as the advertiser. A topic with a
Host
scope restricts the visibility of a topic to nodes located in the same
machine as the advertiser. Finally, by specifying a scope with an All
value,
you’re allowing your topic to be visible by any node.
Partition and namespaces¶
When you create your node you can specify some options to customize its behavior. Among those options you can set a partition name and a namespace.
A partition is used to isolate a set of topics or services within a group of
nodes that share the same partition name. E.g.: Node1 advertises topic /foo
and Node2 advertises /foo
too. If we don’t use a partition, a node
subscribed to /foo
will receive the messages published from Node1 and Node2.
Alternatively, we could specify p1
as a partition for Node1 and p2
as a
partition for Node2. When we create the node for our subscriber, if we specify
p1
as a partition name, we’ll receive the messages published only by Node1.
If we use p2
, we’ll only receive the messages published by Node2. If we
don’t set a partition name, we won’t receive any messages from Node1 or Node2.
A partition name is any alphanumeric string with a few exceptions.
The symbol /
is allowed as part of a partition name but just /
is
not allowed. The symbols @
, ~
or white spaces are not allowed as
part of a partition name. Two or more consecutive slashes (//
) are not
allowed.
The default partition name is created using a combination of your hostname,
followed by :
and your username. E.g.: bb8:caguero
. It’s also possible
to use the environment variable IGN_PARTITION
for setting a custom partition
name.
A namespace is considered a prefix that might be potentially applied to some of the topic/services advertised in a node.
E.g.: Node1 sets a namespace ns1
and advertises the topics
t1
, t2
and /t3
. /t3
is considered an absolute topic (starts
with /
) and it won’t be affected by a namespace. However, t1
and
t2
will be advertised as /ns1/t1
and /ns1/t2
.
A namespace is any alphanumeric string with a few exceptions.
The symbol /
is allowed as part of a namespace but just /
is not
allowed. The symbols @
, ~
or white spaces are not allowed as
part of a namespace. Two or more consecutive slashes (//
) are not allowed.
If topic name or namespace is invalid than fully qualified topic name is
invalid too.
Namespace | Topic name | Fully qualified topic | Validity | Comment |
---|---|---|---|---|
ns1 | /topicA | /topicA | Valid | Absolute topic |
/topicA | /topicA | Valid | Absolute topic | |
ns1 | topicA | /ns1/topicA | Valid | |
topicA | /topicA | Valid | ||
ns1 | topic A | Invalid | Topic contains white space | |
topic A | Invalid | Topic contains white space | ||
my ns | topicA | Invalid | Namespace contains white space | |
//ns | topicA | Invalid | Namespace contains two consecutive // |
|
/ | topicA | Invalid | / namespace is not allowed |
|
~myns | topicA | Invalid | Symbol ~ not allowed |